src: improve performance of coroutine implementation

Author: jasnell

src/api/callback.cc

@@ -22,7 +22,7 @@ using v8::Value;
 CallbackScope::CallbackScope(Isolate* isolate,
                              Local<Object> object,
                              async_context async_context)
-  : CallbackScope(Environment::GetCurrent(isolate), object, async_context) {}
+    : CallbackScope(Environment::GetCurrent(isolate), object, async_context) {}
 
 CallbackScope::CallbackScope(Environment* env,
                              Local<Object> object,
@@ -52,8 +52,7 @@ CallbackScope::CallbackScope(Environment* env,
 }
 
 CallbackScope::~CallbackScope() {
-  if (try_catch_.HasCaught())
-    private_->MarkAsFailed();
+  if (try_catch_.HasCaught()) private_->MarkAsFailed();
   delete private_;
 }
 
@@ -86,7 +85,15 @@ InternalCallbackScope::InternalCallbackScope(
   } else {
     object = std::get<Global<Object>*>(object_arg);
   }
-  std::visit([](auto* ptr) { CHECK_NOT_NULL(ptr); }, object);
+  // Global<Object>* may be null when no resource object was created
+  // (e.g., coroutine tasks when async_hooks are not active).
+  // push_async_context already handles the null case by skipping the
+  // native_execution_async_resources_ store.
+  if (auto* gptr = std::get_if<Global<Object>*>(&object)) {
+    CHECK_IMPLIES(*gptr != nullptr, !(*gptr)->IsEmpty());
+  } else {
+    std::visit([](auto* ptr) { CHECK_NOT_NULL(ptr); }, object);
+  }
 
   env->PushAsyncCallbackScope();
 
@@ -217,8 +224,7 @@ MaybeLocal<Value> InternalMakeCallback(Environment* env,
                                        Local<Value> context_frame) {
   CHECK(!recv.IsEmpty());
 #ifdef DEBUG
-  for (int i = 0; i < argc; i++)
-    CHECK(!argv[i].IsEmpty());
+  for (int i = 0; i < argc; i++) CHECK(!argv[i].IsEmpty());
 #endif
 
   Local<Function> hook_cb = env->async_hooks_callback_trampoline();
@@ -231,8 +237,9 @@ MaybeLocal<Value> InternalMakeCallback(Environment* env,
     flags = InternalCallbackScope::kSkipAsyncHooks;
     use_async_hooks_trampoline =
         async_hooks->fields()[AsyncHooks::kBefore] +
-        async_hooks->fields()[AsyncHooks::kAfter] +
-        async_hooks->fields()[AsyncHooks::kUsesExecutionAsyncResource] > 0;
+            async_hooks->fields()[AsyncHooks::kAfter] +
+            async_hooks->fields()[AsyncHooks::kUsesExecutionAsyncResource] >
+        0;
   }
 
   InternalCallbackScope scope(

src/coro/README.md

@@ -5,14 +5,14 @@ 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,
+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.
+  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
@@ -64,8 +64,8 @@ static void Access(const FunctionCallbackInfo<Value>& args) {
 
 ### 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++
+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
@@ -85,7 +85,7 @@ static coro::UvTrackedTask<void, "COROREADFILE"> ReadFileImpl(
 
 ### Coroutine composition
 
-`UvTask<T>` and `UvTrackedTask<T, Name>` can be co_awaited from other
+`UvTask<T>` and `UvTrackedTask<T, Name>` can be co\_awaited from other
 coroutines. This allows factoring common operations into reusable helpers:
 
 ```cpp
@@ -104,7 +104,7 @@ UvTrackedTask<void, "MYOP"> OuterCoroutine(Environment* env, ...) {
 ### 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
+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.
@@ -119,20 +119,20 @@ adds three phases around `Start()`:
 
 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
+   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\_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,
+   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.
 
@@ -170,22 +170,22 @@ coroutine I/O to finish before destroying the Environment.
 
 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 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) |
+|                               | 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
+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.