src: update coro readme details

Author: jasnell

src/coro/README.md

@@ -24,10 +24,14 @@ AsyncLocalStorage, microtask draining, and environment lifecycle management.
   `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.
+  coroutine frame, avoiding separate heap allocations. Each also exposes a
+  `cancelable_req()` method returning the underlying `uv_req_t*` for
+  cancellation support during environment teardown.
 
 * `uv_promise.h` -- Helpers for bridging coroutines to JavaScript Promises:
-  `MakePromise()`, `ResolvePromise()`, `RejectPromiseWithUVError()`.
+  `MakePromise()`, `ResolvePromise()`, `RejectPromiseWithUVError()`. The
+  resolve and reject helpers guard against calling V8 APIs when the
+  environment is shutting down (`can_call_into_js()` check).
 
 ## Usage
 
@@ -114,14 +118,19 @@ self-destructs when the coroutine completes.
 `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).
+1. **Creation**: The coroutine frame is allocated from the thread-local
+   free-list (see "Frame allocator" below). 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.
+   `async_context_frame` (for AsyncLocalStorage propagation), emits a trace
+   event, and registers in the Environment's coroutine task list for
+   cancellation during teardown. If async\_hooks listeners are active
+   (`kInit > 0` or `kUsesExecutionAsyncResource > 0`), a resource object
+   is created for `executionAsyncResource()` and the `init` hook is emitted.
+   The type name V8 string is cached per template instantiation via
+   `v8::Eternal<v8::String>`, so only the first coroutine of a given type
+   pays the `String::NewFromUtf8` cost.
 
 3. **`Start()`**: Marks the task as detached (fire-and-forget) and resumes
    the coroutine. Each resume-to-suspend segment is wrapped in an
@@ -133,8 +142,10 @@ adds three phases around `Start()`:
 
 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.
+   the task is unregistered from the Environment, and the coroutine frame is
+   returned to the thread-local free-list. If a detached coroutine has a
+   captured C++ exception that was never observed, `std::terminate()` is
+   called rather than silently discarding it.
 
 ## How the awaitable dispatch works
 
@@ -144,7 +155,7 @@ 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.
+   * Records the `uv_req_t*` for cancellation support (via `cancelable_req()`).
    * 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.
@@ -157,6 +168,11 @@ directly in the coroutine frame. When the coroutine hits `co_await`:
    * Opens a new `InternalCallbackScope` for the next segment.
    * Returns the result (e.g., `req_.result` for fs operations).
 
+The liveness counter and cancellation tracking are conditional on the inner
+awaitable having a `cancelable_req()` method (checked at compile time via a
+`requires` expression). When co\_awaiting another `UvTask` or `UvTrackedTask`
+(coroutine composition), these steps are skipped.
+
 ## Environment teardown
 
 During `Environment::CleanupHandles()`, the coroutine task list is iterated and
@@ -166,36 +182,51 @@ in-flight libuv request (if any), which causes the libuv callback to fire with
 The `request_waiting_` counter ensures the teardown loop waits for all
 coroutine I/O to finish before destroying the Environment.
 
+## Frame allocator
+
+Coroutine frames are allocated from a thread-local free-list rather than going
+through `malloc`/`free` on every creation and destruction. This is implemented
+via `promise_type::operator new` and `operator delete` in `TrackedPromiseBase`,
+which route through `CoroFrameAlloc()` and `CoroFrameFree()`.
+
+The free-list uses size-class buckets with 256-byte granularity, covering
+frames up to 4096 bytes (which covers typical coroutine frames). Frames larger
+than 4096 bytes fall through to the global `operator new`. Since all coroutines
+run on the event loop thread, the free-list requires no locking.
+
+After the first coroutine of a given size class completes, subsequent
+coroutines of the same size class are allocated from the free-list with zero
+`malloc` overhead.
+
 ## 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                                 |
+|                      | ReqWrap pattern | Coroutine (no hooks) | Coroutine (hooks active) |
+| -------------------- | --------------- | -------------------- | ------------------------ |
+| C++ heap allocations | 3               | 0 (free-list hit)    | 0 (free-list hit)        |
+| V8 heap objects      | 7               | 2 (resolver+promise) | 3 (+ resource object)    |
+| Total allocations    | 10              | 2                    | 3                        |
 
 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) |
+|                               | 4x ReqWrap | Single coroutine (no hooks) | Single coroutine (hooks active) |
+| ----------------------------- | ---------- | --------------------------- | ------------------------------- |
+| C++ heap allocations          | 12         | 0 (free-list hit)           | 0 (free-list hit)               |
+| V8 heap objects               | 28         | 2                           | 3                               |
+| Total allocations             | 40         | 2                           | 3                               |
+| InternalCallbackScope entries | 4          | 5 (one per segment)         | 5                               |
 
 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.
+* **Heap snapshot visibility**: The coroutine frame is not visible to V8 heap
+  snapshots or `MemoryRetainer`. The thread-local free-list allocator reduces
+  malloc pressure but does not provide V8 with per-frame memory accounting.
+  The exact frame contents are not inspectable from heap snapshot tooling.
 
 * **Snapshot serialization**: `UvTrackedTask` holds `v8::Global` handles that
   cannot be serialized into a startup snapshot. There is currently no safety
@@ -207,3 +238,15 @@ coroutine does not necessarily pay N times the `uv_fs_t` cost.
   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.
+
+* **Free-list growth**: The thread-local free-list does not have a cap on the
+  number of cached frames per size class. Under a workload that creates a
+  large burst of concurrent coroutines and then goes idle, the free-list will
+  retain all of those frames until the thread exits. A maximum per-bucket
+  count could be added if this becomes a concern.
+
+* **Static Eternal handles**: The cached type name `v8::Eternal<v8::String>`
+  is a static variable per template instantiation. It is never freed and is
+  shared across all Isolates on the same thread. This is safe for the
+  single-Isolate case (the common case for Node.js), but would need
+  per-Isolate caching if multiple Isolates use the same coroutine types.