proposal for shared microtask queues

#34023 added microtaskMode: 'afterEvaluate', which gives a context its own microtask queue and drains it after evaluation. There was discussion about giving authors broader control over the queue, but that was ultimately left out as beyond what users seemed to need.

However, the HTML Standard is riddled with requirements that need this kind of control. For example, HTML assigns a microtask queue to each event loop. Its clean up after running script algorithm then requires:

• Finishing a script removes its realm execution context from the stack.
• If the stack is then empty, the event loop performs a microtask checkpoint.

A Window and its same-agent iframe have separate realms but share an event loop. If they are represented by separate vm.Contexts, they therefore need one shared microtask queue.

Currently there's just not enough control over when queues are drained:

• Default contexts share Node's queue, but there is no public API to synchronously drain it.
• afterEvaluate drains synchronously, but gives every context a separate queue.

Let's try to explore this with code.

const vm = require('node:vm');

function run(options, drain = () => {}) {
  const trace = [];
  const record = (entry) => trace.push(entry);
  const window = vm.createContext({ record }, options);
  const iframe = vm.createContext({ record }, options);

  vm.runInContext(`
    const pending = new Promise((resolve) => {
      globalThis.resolve = resolve;
    });
    pending.then(() => {
      record('win-rxn');
      Promise.resolve().then(() => record('win-follow-up'));
    });
  `, window);

  vm.runInContext(`
    const pending = new Promise((resolve) => {
      globalThis.resolve = resolve;
    });
    pending.then(() => record('iframe-rxn'));
  `, iframe);

  window.resolveIframe = iframe.resolve;
  vm.runInContext('resolve(); resolveIframe();', window);
  drain(iframe);

  return trace;
}

console.log(run());
// []

console.log(run(
  { microtaskMode: 'afterEvaluate' },
  (iframe) => vm.runInContext('', iframe),
));
// ['win-rxn', 'win-follow-up', 'iframe-rxn']

The HTML model instead requires:

['win-rxn', 'iframe-rxn', 'win-follow-up']

With default contexts, both reactions are placed on Node's shared microtask queue in the required order, but there is no supported public API for performing the required checkpoint before run() returns. That is why the first call returns [].

With afterEvaluate, returning from the Window evaluation immediately drains the Window's private queue to exhaustion. The Window reaction therefore runs its follow-up before the iframe's private queue can be drained:

['win-rxn', 'win-follow-up', 'iframe-rxn']

Even if the iframe's private queue could be drained before the Window's, that would merely reverse the problem:

['iframe-rxn', 'win-rxn', 'win-follow-up']

Node's public vm therefore cannot perform this synchronous shared-queue checkpoint. Well, it isn't entirely impossible to make this example pass: process._tickCallback() does it. I initially thought that might be an acceptable hack for my own code, but it's deprecated and, after trying to build an actual event loop around it, looks DOA as a general solution because it’s a club when I needed a sewing needle (it drains Node’s shared nextTick and microtask queues, including work unrelated to the checkpoint).

My proposal is to expose a queue that multiple contexts can share and let authors be responsible for the draining. Something like:

const queue = vm.createMicrotaskQueue();

console.log(run(
  { microtaskQueue: queue },
  () => queue.runMicrotasks(),
));
// ['win-rxn', 'iframe-rxn', 'win-follow-up']

I do have a working prototype dreamed up with AI assist, but Node/V8 embedding internals are honestly outside my working knowledge.

Start with the node:vm entry points shown here: createContext, runInContext, microtaskMode, and the proposed createMicrotaskQueue API. Review the linked prototype and compare its behavior with the provided ordering example, including the limitations of process._tickCallback(). Done means an agreed public design can provide a synchronous shared-queue checkpoint without draining unrelated work.