src: add coroutine README.md

Author: jasnell

src/coro/README.md

@@ -0,0 +1,209 @@
+# C++20 Coroutine support for libuv
+
+This directory contains an experimental C++20 coroutine layer for writing
+asynchronous libuv operations as sequential C++ code using `co_await`.
+
+The primary goal is to allow multi-step async operations (such as
+open + stat + read + close) to be written as straight-line C++ instead of
+callback chains, while maintaining full integration with Node.js async_hooks,
+AsyncLocalStorage, microtask draining, and environment lifecycle management.
+
+## File overview
+
+* `uv_task.h` -- `UvTask<T>`: The lightweight, untracked coroutine return type.
+  No V8 or Node.js dependencies. Suitable for internal C++ coroutines that do
+  not need async_hooks visibility or task queue draining.
+
+* `uv_tracked_task.h` -- `UvTrackedTask<T, Name>`: The fully-integrated
+  coroutine return type. Each resume-to-suspend segment is wrapped in an
+  `InternalCallbackScope`, giving it the same semantics as any other callback
+  entry into Node.js. The `Name` template parameter is a compile-time string
+  that identifies the async resource type visible to `async_hooks.createHook()`.
+
+* `uv_awaitable.h` -- Awaitable wrappers for libuv async operations:
+  `UvFsAwaitable` (fs operations), `UvFsStatAwaitable` (stat-family),
+  `UvWorkAwaitable` (thread pool work), and `UvGetAddrInfoAwaitable`
+  (DNS resolution). Each embeds the libuv request struct directly in the
+  coroutine frame, avoiding separate heap allocations.
+
+* `uv_promise.h` -- Helpers for bridging coroutines to JavaScript Promises:
+  `MakePromise()`, `ResolvePromise()`, `RejectPromiseWithUVError()`.
+
+## Usage
+
+### Basic pattern (binding function)
+
+```cpp
+// The coroutine. The return type carries the async resource name as
+// a compile-time template argument.
+static coro::UvTrackedTask<void, "FSREQPROMISE"> DoAccessImpl(
+    Environment* env,
+    v8::Global<v8::Promise::Resolver> resolver,
+    std::string path,
+    int mode) {
+  ssize_t result = co_await coro::UvFs(
+      env->event_loop(), uv_fs_access, path.c_str(), mode);
+  if (result < 0)
+    coro::RejectPromiseWithUVError(env, resolver, result, "access",
+                                   path.c_str());
+  else
+    coro::ResolvePromiseUndefined(env, resolver);
+}
+
+// The binding entry point (called from JavaScript).
+static void Access(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  // ... parse args, check permissions ...
+
+  auto resolver = coro::MakePromise(env, args);
+  auto task = DoAccessImpl(env, std::move(resolver), path, mode);
+  task.InitTracking(env);   // assigns async_id, captures context, emits init
+  task.Start();              // begins execution (fire-and-forget)
+}
+```
+
+### Multi-step operations
+
+Multiple libuv calls within a single coroutine are sequential co_await
+expressions. The intermediate steps (between two co_await points) are pure C++
+with no V8 overhead:
+
+```cpp
+static coro::UvTrackedTask<void, "COROREADFILE"> ReadFileImpl(
+    Environment* env,
+    v8::Global<v8::Promise::Resolver> resolver,
+    std::string path) {
+  ssize_t fd = co_await coro::UvFs(
+      env->event_loop(), uv_fs_open, path.c_str(), O_RDONLY, 0);
+  if (fd < 0) { /* reject and co_return */ }
+
+  auto [err, stat] = co_await coro::UvFsStat(
+      env->event_loop(), uv_fs_fstat, static_cast<uv_file>(fd));
+  // ... read, close, resolve ...
+}
+```
+
+### Coroutine composition
+
+`UvTask<T>` and `UvTrackedTask<T, Name>` can be co_awaited from other
+coroutines. This allows factoring common operations into reusable helpers:
+
+```cpp
+UvTask<ssize_t> OpenFile(uv_loop_t* loop, const char* path, int flags) {
+  co_return co_await UvFs(loop, uv_fs_open, path, flags, 0);
+}
+
+UvTrackedTask<void, "MYOP"> OuterCoroutine(Environment* env, ...) {
+  ssize_t fd = co_await OpenFile(env->event_loop(), path, O_RDONLY);
+  // ...
+}
+```
+
+## Lifecycle
+
+### UvTask (untracked)
+
+`UvTask<T>` uses lazy initialization. The coroutine does not run until it is
+either co_awaited from another coroutine (symmetric transfer) or explicitly
+started with `Start()`. When `Start()` is called, the coroutine runs until its
+first `co_await`, then control returns to the caller. The coroutine frame
+self-destructs when the coroutine completes.
+
+### UvTrackedTask (tracked)
+
+`UvTrackedTask<T, Name>` follows the same lazy/fire-and-forget pattern but
+adds three phases around `Start()`:
+
+1. **Creation**: The coroutine frame is heap-allocated by the compiler.
+   The coroutine is suspended at `initial_suspend` (lazy).
+
+2. **`InitTracking(env)`**: Assigns an `async_id`, captures the current
+   `async_context_frame` (for AsyncLocalStorage propagation), creates a
+   resource object for `executionAsyncResource()`, emits the async_hooks
+   `init` event and a trace event, registers in the Environment's coroutine
+   task list, and reports external memory to V8.
+
+3. **`Start()`**: Marks the task as detached (fire-and-forget) and resumes
+   the coroutine. Each resume-to-suspend segment is wrapped in an
+   `InternalCallbackScope` that provides:
+   * async_hooks `before`/`after` events
+   * `async_context_frame` save/restore (AsyncLocalStorage)
+   * Microtask and `process.nextTick` draining on close
+   * `request_waiting_` counter management for event loop liveness
+
+4. **Completion**: At `final_suspend`, the last `InternalCallbackScope` is
+   closed (draining task queues), the async_hooks `destroy` event is emitted,
+   the task is unregistered from the Environment, external memory accounting
+   is released, and the coroutine frame is freed.
+
+## How the awaitable dispatch works
+
+The `UvFs()` factory function returns a `UvFsAwaitable` that embeds a `uv_fs_t`
+directly in the coroutine frame. When the coroutine hits `co_await`:
+
+1. `await_transform()` on the promise wraps it in a `TrackedAwaitable`.
+2. `TrackedAwaitable::await_suspend()`:
+   * Closes the current `InternalCallbackScope` (drains microtasks/nextTick).
+   * Records the `uv_req_t*` for cancellation support.
+   * Increments `request_waiting_` (event loop liveness).
+   * Calls the inner `await_suspend()`, which dispatches the libuv call with
+     `req_.data = this` pointing back to the awaitable.
+3. The coroutine is suspended. Control returns to the event loop.
+4. When the libuv operation completes, `OnComplete()` calls
+   `handle_.resume()` to resume the coroutine.
+5. `TrackedAwaitable::await_resume()`:
+   * Decrements `request_waiting_`.
+   * Clears the cancellation pointer.
+   * Opens a new `InternalCallbackScope` for the next segment.
+   * Returns the result (e.g., `req_.result` for fs operations).
+
+## Environment teardown
+
+During `Environment::CleanupHandles()`, the coroutine task list is iterated and
+`Cancel()` is called on each active task. This calls `uv_cancel()` on the
+in-flight libuv request (if any), which causes the libuv callback to fire with
+`UV_ECANCELED`. The coroutine resumes, sees the error, and completes normally.
+The `request_waiting_` counter ensures the teardown loop waits for all
+coroutine I/O to finish before destroying the Environment.
+
+## Allocation comparison with ReqWrap
+
+For a single async operation (e.g., `fsPromises.access`):
+
+| | ReqWrap pattern | Coroutine pattern |
+|---|---|---|
+| C++ heap allocations | 3 | 1 (coroutine frame) |
+| V8 heap objects | 7 | 3 (resource + resolver + promise) |
+| Total allocations | 10 | 4 |
+
+For a multi-step operation (open + stat + read + close):
+
+| | 4x ReqWrap | Single coroutine |
+|---|---|---|
+| C++ heap allocations | 12 | 1 |
+| V8 heap objects | 28 | 3 |
+| Total allocations | 40 | 4 |
+| InternalCallbackScope entries | 4 | 5 (one per segment + initial) |
+
+The coroutine frame embeds the `uv_fs_t` (~440 bytes) directly. The compiler
+may overlay non-simultaneously-live awaitables in the frame, so a multi-step
+coroutine does not necessarily pay N times the `uv_fs_t` cost.
+
+## Known limitations
+
+* **Heap snapshot visibility**: The coroutine frame is a plain `malloc`
+  allocated by the C++ coroutine machinery. It is not visible to V8 heap
+  snapshots or `MemoryRetainer`. `AdjustAmountOfExternalAllocatedMemory` is
+  used to give V8 a rough signal of the external memory pressure, but the
+  exact frame contents are not inspectable.
+
+* **Snapshot serialization**: `UvTrackedTask` holds `v8::Global` handles that
+  cannot be serialized into a startup snapshot. There is currently no safety
+  check to prevent snapshotting while coroutines are active. In practice this
+  is not a problem because snapshots are taken at startup before I/O begins.
+
+* **Trace event names**: The existing `AsyncWrap` trace events use a
+  `ProviderType` enum with a switch statement to select the trace event name.
+  The coroutine pattern uses free-form string names. The `init` trace event
+  uses the provided name; the `destroy` trace event currently uses a generic
+  `"coroutine"` category name rather than the per-instance name.