Initial project import

tools/v/vlib/x/async/examples/README.md

@@ -0,0 +1,54 @@
+# x.async examples
+
+This folder contains short public examples for the current `x.async` API.
+Each file focuses on one idea and uses only local, in-memory work.
+
+Examples are documentation-first programs. They show how the public API is
+expected to be used in small readable scenarios. They are executed by the
+validation script to avoid bit rot, but the regression guarantees live in the
+`tests/` folder.
+
+## Rules
+
+- No external service is required.
+- No fixed local path is used.
+- No network listener is opened.
+- Examples avoid `panic()` as a control-flow pattern.
+- Cancellation remains cooperative; examples show jobs checking `ctx.done()`
+  when they may run for more than a tiny unit of work.
+
+## Examples
+
+- `basic_group.v`: first error propagation and cooperative sibling
+  cancellation.
+- `basic_task.v`: one value-returning task consumed with `wait()`.
+- `worker_pool.v`: fixed concurrency and explicit `try_submit()` backpressure.
+- `bounded_pool_submit.v`: wait for pool admission with a timeout or context
+  while jobs keep using the pool context.
+- `periodic.v`: a blocking `every()` loop stopped by context cancellation.
+- `timeout.v`: one cooperative job bounded by `with_timeout()`.
+- `net_http/`: synthetic `net.http` request/response processing with `Pool`.
+- `net_websocket/`: in-memory `websocket.Message` processing. It is not an
+  end-to-end websocket server example.
+- `mcp/`: in-memory MCP request/response dispatch with `Task[T]`.
+- `veb/`: synthetic `veb.Context` response lifecycle with `Task[T]`.
+
+## Run
+
+From the repository root:
+
+```sh
+./v run vlib/x/async/examples/basic_group.v
+./v run vlib/x/async/examples/basic_task.v
+./v run vlib/x/async/examples/worker_pool.v
+./v run vlib/x/async/examples/bounded_pool_submit.v
+./v run vlib/x/async/examples/periodic.v
+./v run vlib/x/async/examples/timeout.v
+./v run vlib/x/async/examples/net_http/request_batch.v
+./v run vlib/x/async/examples/net_websocket/message_pipeline.v
+./v run vlib/x/async/examples/mcp/tool_dispatch.v
+./v run vlib/x/async/examples/veb/app_lifecycle.v
+```
+
+Use `tools/validate.sh` for the guarded module validation path. It isolates V
+temporary/cache directories and keeps validation runners serialized.