diff --git a/doc/api/vm.md b/doc/api/vm.md index 14cd1f269b12..5ac74208e097 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -313,10 +313,18 @@ changes: `EvalError`. **Default:** `true`. * `wasm` {boolean} If set to false any attempt to compile a WebAssembly module will throw a `WebAssembly.CompileError`. **Default:** `true`. - * `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. + * `microtaskMode` {string|Object} + * If set to the string `'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. + * If set to an object of the form `{ type: 'manual', queue }`, where + `queue` is a [`vm.MicrotaskQueue`][] created via + [`vm.createMicrotaskQueue()`][], microtasks scheduled while running the + script are placed on `queue` instead of being drained automatically. + `queue` may be shared with other contexts so that microtasks from all + of them can be drained together, in the order they were scheduled, via + a single explicit [`microtaskQueue.runMicrotasks()`][] call. * 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 +1326,35 @@ added: A `ModuleRequest` represents the request to import a module with given import attributes and phase. +## Class: `vm.MicrotaskQueue` + + + +> Stability: 1 - Experimental + +An explicit microtask queue that can be attached to multiple contexts (via +the `microtaskMode` option of [`vm.createContext()`][], +[`vm.runInNewContext()`][], and [`script.runInNewContext()`][]) so that they +share where their microtasks (`Promise` reactions and `async function` +continuations) are placed, and so that those microtasks are drained together, +explicitly, by the embedder, instead of automatically by Node.js. + +Instances are created with [`vm.createMicrotaskQueue()`][]; the constructor is +not exported by the `node:vm` module. + +### `microtaskQueue.runMicrotasks()` + + + +Synchronously runs every microtask currently queued on `microtaskQueue`, in +the order in which they were scheduled. If running a microtask schedules +further microtasks on the same queue, those are run as well before this +method returns. + ## `vm.compileFunction(code[, params[, options]])` + +* Returns: {vm.MicrotaskQueue} + +Creates a new [`vm.MicrotaskQueue`][] that can be passed as the `queue` of a +`{ type: 'manual', queue }` value for the `microtaskMode` option of +[`vm.createContext()`][], so that multiple contexts can share where their +microtasks are placed. See [`vm.MicrotaskQueue`][] for details. + ## `vm.isContext(object)`