vm: support shared microtask queues

Add `vm.MicrotaskQueue` and `options.microtaskQueue` to allow multiple
contexts to share an explicit V8 microtask queue and let users control
synchronous checkpoint draining.

Document how options.microtaskQueue and options.microtaskMode interact
across createContext, runInNewContext, and script.runInNewContext.
Update receiver type error expectation for runMicrotasks and add test
coverage for runInNewContext with microtask queues.

Fixes: #65555
Signed-off-by: Alessio Attilio <alessio.attilio@protonmail.com>
Assisted-by: Antigravity

Author: kairosci

doc/api/vm.md

@@ -316,7 +316,19 @@ changes:
   * `microtaskMode` {string} If set to `afterEvaluate`, microtasks (tasks
     scheduled through `Promise`s and `async function`s) will be run immediately
     after the script has run. They are included in the `timeout` and
-    `breakOnSigint` scopes in that case.
+    `breakOnSigint` scopes in that case. If `microtaskQueue` (or
+    `contextMicrotaskQueue`) is also specified, evaluating the script will
+    drain that shared microtask queue (including any microtasks queued from
+    other contexts sharing the queue). If `microtaskQueue` is not specified, a
+    private microtask queue is created exclusively for this context.
+  * `microtaskQueue` {vm.MicrotaskQueue} A microtask queue created with
+    [`new vm.MicrotaskQueue()`][] or [`vm.createMicrotaskQueue()`][]. If
+    specified, microtasks scheduled inside the new context will be placed on
+    this queue. By default, microtasks placed on this queue are not
+    automatically drained when script evaluation finishes; they remain queued
+    until explicitly drained using [`microtaskQueue.runMicrotasks()`][], unless
+    `microtaskMode: 'afterEvaluate'` is also specified. An alias for this
+    option is `contextMicrotaskQueue`.
 * Returns: {any} the result of the very last statement executed in the script.
 
 This method is a shortcut to `script.runInContext(vm.createContext(options), options)`.
@@ -1318,6 +1330,37 @@ added:
 
 A `ModuleRequest` represents the request to import a module with given import attributes and phase.
 
+## Class: `vm.MicrotaskQueue`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Represents an explicit microtask queue that can be shared across multiple
+`vm.Context` instances and synchronously drained by the embedder.
+
+By default, passing a `vm.MicrotaskQueue` to [`vm.createContext()`][] attaches the
+context to that queue without automatically draining it after script evaluation;
+microtasks remain queued until explicitly drained using
+[`microtaskQueue.runMicrotasks()`][]. If automatic draining upon script completion
+is also desired, pass `microtaskMode: 'afterEvaluate'` alongside `microtaskQueue`.
+
+### `new vm.MicrotaskQueue()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Creates a new `vm.MicrotaskQueue` instance.
+
+### `microtaskQueue.runMicrotasks()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Synchronously runs all microtasks currently queued in this microtask queue.
+
 ## `vm.compileFunction(code[, params[, options]])`
 
 <!-- YAML
@@ -1474,6 +1517,19 @@ changes:
     scheduled through `Promise`s and `async function`s) will be run immediately
     after a script has run through [`script.runInContext()`][].
     They are included in the `timeout` and `breakOnSigint` scopes in that case.
+    If `microtaskQueue` is also specified, evaluating a script in this context
+    will drain that shared microtask queue (including any pending microtasks
+    scheduled by other contexts sharing the queue). If `microtaskQueue` is not
+    specified, a private microtask queue is created exclusively for this
+    context.
+  * `microtaskQueue` {vm.MicrotaskQueue} A microtask queue created with
+    [`new vm.MicrotaskQueue()`][] or [`vm.createMicrotaskQueue()`][]. If
+    specified, microtasks scheduled inside this context will be placed on this
+    queue, allowing multiple contexts to share the same microtask queue.
+    By default, microtasks placed on this queue are not automatically drained
+    when script evaluation finishes; they remain queued until explicitly drained
+    using [`microtaskQueue.runMicrotasks()`][], unless `microtaskMode: 'afterEvaluate'`
+    is also specified.
   * `importModuleDynamically`
     {Function|vm.constants.USE\_MAIN\_CONTEXT\_DEFAULT\_LOADER}
     Used to specify the how the modules should be loaded when `import()` is
@@ -1555,6 +1611,28 @@ Returns `true` if the given `object` object has been [contextified][] using
 [`vm.createContext()`][], or if it's the global object of a context created
 using [`vm.constants.DONT_CONTEXTIFY`][].
 
+## `vm.createMicrotaskQueue()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {vm.MicrotaskQueue}
+
+Creates a new [`vm.MicrotaskQueue`][] instance. Shortcut to
+`new vm.MicrotaskQueue()`.
+
+## `vm.isMicrotaskQueue(object)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `object` {any}
+* Returns: {boolean}
+
+Returns `true` if the given `object` is an instance of [`vm.MicrotaskQueue`][].
+
 ## `vm.measureMemory([options])`
 
 <!-- YAML
@@ -1822,7 +1900,18 @@ changes:
   * `microtaskMode` {string} If set to `afterEvaluate`, microtasks (tasks
     scheduled through `Promise`s and `async function`s) will be run immediately
     after the script has run. They are included in the `timeout` and
-    `breakOnSigint` scopes in that case.
+    `breakOnSigint` scopes in that case. If `microtaskQueue` is also specified,
+    evaluating the script will drain that shared microtask queue (including any
+    pending microtasks scheduled by other contexts sharing the queue). If
+    `microtaskQueue` is not specified, a private microtask queue is created
+    exclusively for this context.
+  * `microtaskQueue` {vm.MicrotaskQueue} A microtask queue created with
+    [`new vm.MicrotaskQueue()`][] or [`vm.createMicrotaskQueue()`][]. If
+    specified, microtasks scheduled inside the new context will be placed on
+    this queue. By default, microtasks placed on this queue are not
+    automatically drained when script evaluation finishes; they must be
+    explicitly drained using [`microtaskQueue.runMicrotasks()`][], unless
+    `microtaskMode: 'afterEvaluate'` is also specified.
 * Returns: {any} the result of the very last statement executed in the script.
 
 This method is a shortcut to
@@ -2577,16 +2666,20 @@ const { Script, SyntheticModule } = require('node:vm');
 [`Error`]: errors.md#class-error
 [`URL`]: url.md#class-url
 [`eval()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval
+[`microtaskQueue.runMicrotasks()`]: #microtaskqueuerunmicrotasks
+[`new vm.MicrotaskQueue()`]: #new-vmmicrotaskqueue
 [`optionsExpression`]: https://tc39.es/proposal-import-attributes/#sec-evaluate-import-call
 [`script.runInContext()`]: #scriptrunincontextcontextifiedobject-options
 [`script.runInThisContext()`]: #scriptruninthiscontextoptions
 [`sourceTextModule.instantiate()`]: #sourcetextmoduleinstantiate
 [`sourceTextModule.linkRequests(modules)`]: #sourcetextmodulelinkrequestsmodules
 [`sourceTextModule.moduleRequests`]: #sourcetextmodulemodulerequests
 [`url.origin`]: url.md#urlorigin
+[`vm.MicrotaskQueue`]: #class-vmmicrotaskqueue
 [`vm.compileFunction()`]: #vmcompilefunctioncode-params-options
 [`vm.constants.DONT_CONTEXTIFY`]: #vmconstantsdont_contextify
 [`vm.createContext()`]: #vmcreatecontextcontextobject-options
+[`vm.createMicrotaskQueue()`]: #vmcreatemicrotaskqueue
 [`vm.runInContext()`]: #vmrunincontextcode-contextifiedobject-options
 [`vm.runInThisContext()`]: #vmruninthiscontextcode-options
 [contextified]: #what-does-it-mean-to-contextify-an-object

lib/vm.js

@@ -32,6 +32,8 @@ const {
 
 const {
   ContextifyScript,
+  MicrotaskQueue: ContextifyMicrotaskQueue,
+  isMicrotaskQueue: _isMicrotaskQueue,
   makeContext,
   constants,
   measureMemory: _measureMemory,
@@ -82,6 +84,16 @@ function isContext(object) {
   return _isContext(object);
 }
 
+class MicrotaskQueue extends ContextifyMicrotaskQueue {}
+
+function createMicrotaskQueue() {
+  return new MicrotaskQueue();
+}
+
+function isMicrotaskQueue(object) {
+  return typeof object === 'object' && object !== null && _isMicrotaskQueue(object);
+}
+
 class Script extends ContextifyScript {
   constructor(code, options = kEmptyObject) {
     code = `${code}`;
@@ -202,6 +214,7 @@ function getContextOptions(options) {
     origin: options.contextOrigin,
     codeGeneration: undefined,
     microtaskMode: options.microtaskMode,
+    microtaskQueue: options.microtaskQueue ?? options.contextMicrotaskQueue,
   };
   if (contextOptions.name !== undefined)
     validateString(contextOptions.name, 'options.contextName');
@@ -235,6 +248,7 @@ function createContext(contextObject = { __proto__: ObjectPrototype }, options =
     origin,
     codeGeneration,
     microtaskMode,
+    microtaskQueue,
     importModuleDynamically,
   } = options;
 
@@ -255,12 +269,27 @@ function createContext(contextObject = { __proto__: ObjectPrototype }, options =
   validateOneOf(microtaskMode,
                 'options.microtaskMode',
                 ['afterEvaluate', undefined]);
-  const microtaskQueue = (microtaskMode === 'afterEvaluate');
+  if (microtaskQueue !== undefined && !isMicrotaskQueue(microtaskQueue)) {
+    throw new ERR_INVALID_ARG_TYPE(
+      'options.microtaskQueue',
+      'MicrotaskQueue',
+      microtaskQueue,
+    );
+  }
 
   const hostDefinedOptionId =
     getHostDefinedOptionId(importModuleDynamically, name);
 
-  const result = makeContext(contextObject, name, origin, strings, wasm, microtaskQueue, hostDefinedOptionId);
+  const result = makeContext(
+    contextObject,
+    name,
+    origin,
+    strings,
+    wasm,
+    microtaskQueue ?? (microtaskMode === 'afterEvaluate'),
+    hostDefinedOptionId,
+    microtaskMode === 'afterEvaluate',
+  );
   // Register the context scope callback after the context was initialized.
   registerImportModuleDynamically(result, importModuleDynamically);
   return result;
@@ -413,6 +442,9 @@ module.exports = {
   compileFunction,
   measureMemory,
   constants: vmConstants,
+  MicrotaskQueue,
+  createMicrotaskQueue,
+  isMicrotaskQueue,
 };
 
 // The vm module is patched to include vm.Module, vm.SourceTextModule

src/env_properties.h

@@ -460,6 +460,7 @@
   V(lock_info_template, v8::DictionaryTemplate)                                \
   V(lock_query_template, v8::DictionaryTemplate)                               \
   V(message_port_constructor_template, v8::FunctionTemplate)                   \
+  V(microtask_queue_constructor_template, v8::FunctionTemplate)                \
   V(module_wrap_constructor_template, v8::FunctionTemplate)                    \
   V(mx_record_template, v8::DictionaryTemplate)                                \
   V(naptr_record_template, v8::DictionaryTemplate)                             \

src/node_contextify.cc

@@ -153,10 +153,10 @@ ContextifyContext* ContextifyContext::New(Environment* env,
 
   const SnapshotData* snapshot_data = env->isolate_data()->snapshot_data();
 
-  MicrotaskQueue* queue =
-      options->own_microtask_queue
-          ? options->own_microtask_queue.get()
-          : env->isolate()->GetCurrentContext()->GetMicrotaskQueue();
+  MicrotaskQueue* queue = options->own_microtask_queue.get();
+  if (queue == nullptr) queue = options->shared_microtask_queue.get();
+  if (queue == nullptr)
+    queue = env->isolate()->GetCurrentContext()->GetMicrotaskQueue();
 
   Local<Context> v8_context;
   if (!(CreateV8Context(env->isolate(), object_template, snapshot_data, queue)
@@ -178,7 +178,9 @@ ContextifyContext::ContextifyContext(Environment* env,
                                      ContextOptions* options)
     : microtask_queue_(options->own_microtask_queue
                            ? options->own_microtask_queue.release()
-                           : nullptr) {
+                           : nullptr),
+      shared_microtask_queue_(std::move(options->shared_microtask_queue)),
+      drain_after_evaluate_(options->drain_after_evaluate) {
   CppgcMixin::Wrap(this, env, wrapper);
 
   context_.Reset(env->isolate(), v8_context);
@@ -414,7 +416,7 @@ void ContextifyContext::MakeContext(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   ContextOptions options;
 
-  CHECK_EQ(args.Length(), 7);
+  CHECK_GE(args.Length(), 7);
   Local<Object> sandbox;
   if (args[0]->IsObject()) {
     sandbox = args[0].As<Object>();
@@ -445,11 +447,20 @@ void ContextifyContext::MakeContext(const FunctionCallbackInfo<Value>& args) {
   if (args[5]->IsBoolean() && args[5]->BooleanValue(env->isolate())) {
     options.own_microtask_queue =
         MicrotaskQueue::New(env->isolate(), MicrotasksPolicy::kExplicit);
+    options.drain_after_evaluate = true;
+  } else if (args[5]->IsObject()) {
+    ContextifyMicrotaskQueue* queue;
+    ASSIGN_OR_RETURN_UNWRAP_CPPGC(&queue, args[5].As<Object>());
+    options.shared_microtask_queue = queue->microtask_queue();
   }
 
   CHECK(args[6]->IsSymbol());
   options.host_defined_options_id = args[6].As<Symbol>();
 
+  if (args.Length() > 7 && args[7]->IsBoolean()) {
+    options.drain_after_evaluate = args[7]->BooleanValue(env->isolate());
+  }
+
   TryCatchScope try_catch(env);
   ContextifyContext* context_ptr =
       ContextifyContext::New(env, sandbox, &options);
@@ -2027,13 +2038,87 @@ static void MeasureMemory(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(promise);
 }
 
+void ContextifyMicrotaskQueue::CreatePerIsolateProperties(
+    IsolateData* isolate_data, Local<ObjectTemplate> target) {
+  Isolate* isolate = isolate_data->isolate();
+  Local<String> class_name = FIXED_ONE_BYTE_STRING(isolate, "MicrotaskQueue");
+
+  Local<FunctionTemplate> tmpl = NewFunctionTemplate(isolate, New);
+  tmpl->InstanceTemplate()->SetInternalFieldCount(
+      ContextifyMicrotaskQueue::kInternalFieldCount);
+  tmpl->SetClassName(class_name);
+  SetProtoMethod(isolate, tmpl, "runMicrotasks", RunMicrotasks);
+
+  target->Set(isolate, "MicrotaskQueue", tmpl);
+  SetMethod(isolate, target, "isMicrotaskQueue", IsMicrotaskQueue);
+  isolate_data->set_microtask_queue_constructor_template(tmpl);
+}
+
+void ContextifyMicrotaskQueue::RegisterExternalReferences(
+    ExternalReferenceRegistry* registry) {
+  registry->Register(New);
+  registry->Register(RunMicrotasks);
+  registry->Register(IsMicrotaskQueue);
+}
+
+ContextifyMicrotaskQueue* ContextifyMicrotaskQueue::New(Environment* env,
+                                                        Local<Object> object) {
+  DCHECK_NOT_NULL(env->isolate()->GetCppHeap());
+  return cppgc::MakeGarbageCollected<ContextifyMicrotaskQueue>(
+      env->cppgc_allocation_handle(), env, object);
+}
+
+void ContextifyMicrotaskQueue::New(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  CHECK(args.IsConstructCall());
+  New(env, args.This());
+}
+
+ContextifyMicrotaskQueue::ContextifyMicrotaskQueue(Environment* env,
+                                                   Local<Object> object)
+    : microtask_queue_(
+          MicrotaskQueue::New(env->isolate(), MicrotasksPolicy::kExplicit)) {
+  CppgcMixin::Wrap(this, env, object);
+}
+
+bool ContextifyMicrotaskQueue::InstanceOf(Environment* env,
+                                          const Local<Value>& value) {
+  return !value.IsEmpty() && value->IsObject() &&
+         env->microtask_queue_constructor_template()->HasInstance(value);
+}
+
+void ContextifyMicrotaskQueue::RunMicrotasks(
+    const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  if (!ContextifyMicrotaskQueue::InstanceOf(env, args.This())) {
+    THROW_ERR_INVALID_THIS(env,
+                           "MicrotaskQueue methods can only be called on "
+                           "MicrotaskQueue instances.");
+    return;
+  }
+  ContextifyMicrotaskQueue* queue;
+  ASSIGN_OR_RETURN_UNWRAP_CPPGC(&queue, args.This());
+  queue->microtask_queue_->PerformCheckpoint(args.GetIsolate());
+}
+
+void ContextifyMicrotaskQueue::IsMicrotaskQueue(
+    const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  bool is_queue =
+      args.Length() > 0 && args[0]->IsObject() && InstanceOf(env, args[0]) &&
+      CppgcMixin::Unwrap<ContextifyMicrotaskQueue>(args[0].As<Object>()) !=
+          nullptr;
+  args.GetReturnValue().Set(is_queue);
+}
+
 void CreatePerIsolateProperties(IsolateData* isolate_data,
                                 Local<ObjectTemplate> target) {
   Isolate* isolate = isolate_data->isolate();
 
   ContextifyContext::CreatePerIsolateProperties(isolate_data, target);
   ContextifyScript::CreatePerIsolateProperties(isolate_data, target);
   ContextifyFunction::CreatePerIsolateProperties(isolate_data, target);
+  ContextifyMicrotaskQueue::CreatePerIsolateProperties(isolate_data, target);
 
   SetMethod(isolate, target, "runInterruptible", RunInterruptible);
 
@@ -2083,6 +2168,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   ContextifyContext::RegisterExternalReferences(registry);
   ContextifyScript::RegisterExternalReferences(registry);
   ContextifyFunction::RegisterExternalReferences(registry);
+  ContextifyMicrotaskQueue::RegisterExternalReferences(registry);
 
   registry->Register(CompileFunctionForCJSLoader);
   registry->Register(RunInterruptible);