Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
a5593db
src: add NewIsolate() overload taking a platform delegate
jasnell Nov 5, 2026
fa58066
lib,src: add experimental node:green_threads module
jasnell Nov 5, 2026
6f652f4
lib,src: schedule isolates on any pool thread
jasnell Nov 5, 2026
5b6537e
lib,src: fix teardown, timer and task lifetime issues
jasnell Nov 5, 2026
1aff5a9
lib,src: add CPU and memory limits and a warm pool
jasnell Nov 5, 2026
96cafbe
benchmark: add green_threads benchmarks
jasnell Nov 5, 2026
0e24cf9
lib,src: resolve setWarmPoolSize() once the pool is full
jasnell Nov 5, 2026
4631217
lib,src: fix ArrayBuffer memory limit before the first GC
jasnell Nov 5, 2026
c454a18
lib,src: add isolate groups
jasnell Nov 5, 2026
59fa57b
lib,src: stop green threads that ignore termination
jasnell Nov 5, 2026
67f8dee
lib,src: add setUnresponsiveTimeouts()
jasnell Nov 5, 2026
bc5d851
src: fix build with the V8 sandbox enabled
jasnell Nov 5, 2026
484667d
lib,src: initialize warm isolates in the background
jasnell Nov 5, 2026
68067a8
lib,src: add EventTarget and AbortController
jasnell Nov 5, 2026
579ef2b
lib,src: add RPC
jasnell Nov 5, 2026
7bd1c1a
lib,src: transfer ArrayBuffers and share SharedArrayBuffers
jasnell Nov 5, 2026
f52e10c
worker: allow MessagePortData owners other than MessagePorts
jasnell Nov 5, 2026
bd66770
lib,src: add MessageChannel and MessagePort
jasnell Nov 5, 2026
c177974
lib,src: add ES modules and exports
jasnell Nov 6, 2026
daa219f
lib,src: keep the properties of errors
jasnell Nov 6, 2026
9bc6614
lib,src: start green threads from a bootstrapped snapshot
jasnell Nov 14, 2026
8fc3bae
lib,src: set the time origin when green threads start
jasnell Nov 14, 2026
4ce50df
lib,src: build the startup snapshots of green threads
jasnell Nov 14, 2026
f651038
lib,src: use a small snapshot in the default isolate group
jasnell Nov 14, 2026
ba4ecd2
lib,src: add NODE_GREEN_THREADS_POOL_SIZE
jasnell Nov 14, 2026
c554c4b
src: only query the memory for heap defaults when used
jasnell Nov 14, 2026
9e649e4
lib,src: keep the young generation limit
jasnell Nov 14, 2026
52cea99
lib,src: add warm pools for isolate groups and memory limits
jasnell Nov 14, 2026
baf2be9
lib,src: don't copy the runtime's sources into snapshots
jasnell Nov 14, 2026
f423788
src,doc: fix lint and formatting of green threads
jasnell Nov 14, 2026
cc475f0
src: don't build green threads' snapshot for embedders
jasnell Nov 14, 2026
8028d75
lib,src: add BroadcastChannel to green threads
jasnell Nov 14, 2026
05eaf4a
lib,src: close the ports of abandoned green threads
jasnell Nov 14, 2026
9b5284c
lib,src: add greenThread.close()
jasnell Nov 14, 2026
2e840b1
lib,src: export RPC objects only once a message is serialized
jasnell Nov 16, 2026
03d76fe
lib: keep imported AbortSignals alive until they abort
jasnell Nov 16, 2026
abc175f
src,lib: add the --allow-green-threads permission
jasnell Nov 16, 2026
a42c05a
lib,src: add greenThreads.setStallPolicy()
jasnell Nov 16, 2026
43eb49f
doc: explain how green threads avoid and break stalls
jasnell Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions benchmark/green_threads/roundtrip.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
'use strict';
const common = require('../common.js');
const { once } = require('events');

const bench = common.createBenchmark(main, {
kind: ['green-thread', 'worker'],
concurrency: [1, 16],
n: [10000],
}, {
flags: ['--experimental-green-threads', '--no-warnings'],
});

// Sends `n` messages in total, spread over `concurrency` threads, each of
// which echoes every message back before it gets the next one.
async function main({ kind, concurrency, n }) {
let threads;
if (kind === 'green-thread') {
const { GreenThread } = require('node:green_threads');
threads = Array.from({ length: concurrency }, () => new GreenThread(
'onmessage = ({ data }) => postMessage(data);'));
} else {
const { Worker } = require('worker_threads');
threads = Array.from({ length: concurrency }, () => new Worker(`
const { parentPort } = require('worker_threads');
parentPort.on('message', (data) => parentPort.postMessage(data));
`, { eval: true }));
await Promise.all(threads.map((w) => once(w, 'online')));
}
const perThread = Math.ceil(n / concurrency);
bench.start();
await Promise.all(threads.map(async (thread) => {
for (let i = 0; i < perThread; i++) {
const reply = once(thread, 'message');
thread.postMessage(i);
await reply;
}
}));
bench.end(perThread * concurrency);
await Promise.all(threads.map((thread) => thread.terminate()));
}
52 changes: 52 additions & 0 deletions benchmark/green_threads/rpc.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
'use strict';
const common = require('../common.js');

const bench = common.createBenchmark(main, {
direction: ['green-to-host', 'host-to-green'],
concurrency: [1, 16],
n: [10000],
}, {
flags: ['--experimental-green-threads', '--no-warnings'],
});

// Makes `n` RPC calls in total, spread over `concurrency` green threads, each
// of which makes or receives one call at a time.
async function main({ direction, concurrency, n }) {
const { GreenThread } = require('node:green_threads');
const perThread = Math.ceil(n / concurrency);
let started;
const ready = new Promise((resolve) => { started = resolve; });
const echoes = [];
const greenThreads = Array.from({ length: concurrency }, () => {
return new GreenThread(direction === 'green-to-host' ? `
onmessage = async ({ data: n }) => {
for (let i = 0; i < n; i++) await env.echo(i);
postMessage(0);
};
` : 'env.register((value) => value);', {
env: {
echo: (value) => value,
register(echo) {
echoes.push(echo);
if (echoes.length === concurrency) started();
},
},
});
});
if (direction === 'host-to-green') await ready;
bench.start();
await Promise.all(greenThreads.map(async (greenThread, index) => {
if (direction === 'green-to-host') {
const done = new Promise((resolve) => {
greenThread.once('message', resolve);
});
greenThread.postMessage(perThread);
await done;
} else {
const echo = echoes[index];
for (let i = 0; i < perThread; i++) await echo(i);
}
}));
bench.end(perThread * concurrency);
await Promise.all(greenThreads.map((greenThread) => greenThread.terminate()));
}
49 changes: 49 additions & 0 deletions benchmark/green_threads/startup.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
'use strict';
const common = require('../common.js');
const { once } = require('events');

const bench = common.createBenchmark(main, {
kind: ['green-thread', 'green-thread-warm', 'worker', 'vm-context'],
n: [50],
}, {
flags: ['--experimental-green-threads', '--no-warnings'],
});

// Starts `n` of `kind` at once, and measures until each has sent a message.
async function main({ kind, n }) {
switch (kind) {
case 'green-thread':
case 'green-thread-warm': {
const { GreenThread, setWarmPoolSize } = require('node:green_threads');
if (kind === 'green-thread-warm') await setWarmPoolSize(n);
bench.start();
const greenThreads = Array.from(
{ length: n }, () => new GreenThread('postMessage(0);'));
await Promise.all(greenThreads.map((g) => once(g, 'message')));
bench.end(n);
await setWarmPoolSize(0);
await Promise.all(greenThreads.map((g) => g.terminate()));
break;
}
case 'worker': {
const { Worker } = require('worker_threads');
bench.start();
const workers = Array.from({ length: n }, () => new Worker(
"require('worker_threads').parentPort.postMessage(0);",
{ eval: true }));
await Promise.all(workers.map((w) => once(w, 'message')));
bench.end(n);
await Promise.all(workers.map((w) => w.terminate()));
break;
}
case 'vm-context': {
const vm = require('vm');
bench.start();
for (let i = 0; i < n; i++) {
vm.runInContext('0', vm.createContext());
}
bench.end(n);
break;
}
}
}
64 changes: 64 additions & 0 deletions doc/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,39 @@ When passing a single flag with a comma a warning will be displayed.

Examples can be found in the [File System Permissions][] documentation.

### `--allow-green-threads`

<!-- YAML
added: REPLACEME
-->

> Stability: 1.0 - Early development

When using the [Permission Model][], the process will not be able to start
[green threads][] by default. Attempts to create a `GreenThread`, or to call
`setWarmPoolSize()`, will throw an `ERR_ACCESS_DENIED` exception unless the
user explicitly passes the `--allow-green-threads` flag when starting Node.js.

Unlike [`--allow-worker`][], this doesn't grant code more than the permission
model allows: green threads can't use any Node.js API, and only have what the
host passes them.

Example:

```js
const { GreenThread } = require('node:green_threads');
new GreenThread('postMessage(1);');
```

```console
$ node --permission --allow-fs-read=* --experimental-green-threads index.js
Error: Access to this API has been restricted. Use --allow-green-threads to manage permissions.
at new GreenThread (node:green_threads:350:20) {
code: 'ERR_ACCESS_DENIED',
permission: 'GreenThreads'
}
```

### `--allow-inspector`

<!-- YAML
Expand Down Expand Up @@ -1489,6 +1522,16 @@ added:

Enable exposition of [EventSource Web API][] on the global scope.

### `--experimental-green-threads`

<!-- YAML
added: REPLACEME
-->

> Stability: 1 - Experimental

@marco-ippolito marco-ippolito Nov 20, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> Stability: 1 - Experimental
> Stability: 1.0 - Early development

We should use the new experimental status:


Enable the experimental [`node:green_threads`][] module.

### `--experimental-import-meta-resolve`

<!-- YAML
Expand Down Expand Up @@ -2609,6 +2652,7 @@ following permissions are restricted:
* Environment variables - manageable through [`--allow-env`][] flag
* Child Process - manageable through [`--allow-child-process`][] flag
* Worker Threads - manageable through [`--allow-worker`][] flag
* Green threads - manageable through [`--allow-green-threads`][] flag
* WASI - manageable through [`--allow-wasi`][] flag
* Addons - manageable through [`--allow-addons`][] flag
* FFI - manageable through [`--allow-ffi`](#--allow-ffi) flag
Expand Down Expand Up @@ -4210,6 +4254,20 @@ The `NODE_EXTRA_CA_CERTS` environment variable is only read when the Node.js
process is first launched. Changing the value at runtime using
`process.env.NODE_EXTRA_CA_CERTS` has no effect on the current process.

### `NODE_GREEN_THREADS_POOL_SIZE=size`

<!-- YAML
added: REPLACEME
-->

> Stability: 1.0 - Early development

Set the number of OS threads that [green threads][] are scheduled onto to
`size`. Values above `1024` mean `1024`, and values that aren't positive
integers are ignored. By default, the pool has as many threads as
[`os.availableParallelism()`][], up to `8`. The pool is created when the first
green thread starts, so the variable has to be set before then.

### `NODE_ICU_DATA=file`

<!-- YAML
Expand Down Expand Up @@ -4276,6 +4334,7 @@ one is included in the list below.
* `--allow-fs-read`
* `--allow-fs-vfs`
* `--allow-fs-write`
* `--allow-green-threads`
* `--allow-inspector`
* `--allow-net`
* `--allow-openssl-store`
Expand Down Expand Up @@ -4310,6 +4369,7 @@ one is included in the list below.
* `--experimental-detect-module`
* `--experimental-dtls`
* `--experimental-eventsource`
* `--experimental-green-threads`
* `--experimental-import-meta-resolve`
* `--experimental-import-text`
* `--experimental-json-modules`
Expand Down Expand Up @@ -4947,6 +5007,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
[`--allow-env`]: #--allow-env
[`--allow-fs-read`]: #--allow-fs-read
[`--allow-fs-write`]: #--allow-fs-write
[`--allow-green-threads`]: #--allow-green-threads
[`--allow-net`]: #--allow-net
[`--allow-openssl-store`]: #--allow-openssl-store
[`--allow-wasi`]: #--allow-wasi
Expand Down Expand Up @@ -4999,9 +5060,11 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
[`inspector.open()`]: inspector.md#inspectoropenport-host-wait
[`net.getDefaultAutoSelectFamilyAttemptTimeout()`]: net.md#netgetdefaultautoselectfamilyattempttimeout
[`node:ffi`]: ffi.md
[`node:green_threads`]: green_threads.md
[`node:sqlite`]: sqlite.md
[`node:stream/iter`]: stream_iter.md
[`node:vfs`]: vfs.md
[`os.availableParallelism()`]: os.md#osavailableparallelism
[`permission.drop()`]: permissions.md#permissiondropscope-reference
[`process.setUncaughtExceptionCaptureCallback()`]: process.md#processsetuncaughtexceptioncapturecallbackfn
[`session.connectToMainThread()`]: inspector.md#sessionconnecttomainthread
Expand All @@ -5026,6 +5089,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
[environment_variables]: #environment-variables-1
[filtering tests by name]: test.md#filtering-tests-by-name
[global setup and teardown]: test.md#global-setup-and-teardown
[green threads]: green_threads.md
[jitless]: https://v8.dev/blog/jitless
[libuv threadpool documentation]: https://docs.libuv.org/en/latest/threadpool.html
[module compile cache]: module.md#module-compile-cache
Expand Down
75 changes: 75 additions & 0 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -1528,6 +1528,76 @@ file in chunks.
The number of file system events queued without being handled exceeded the size specified in
`maxQueue` in `fs.watch()`.

<a id="ERR_GREEN_THREAD_BROADCAST_SCOPE"></a>

### `ERR_GREEN_THREAD_BROADCAST_SCOPE`

A [green thread][] created a `BroadcastChannel` whose name isn't one of its
`broadcastScopes`.

<a id="ERR_GREEN_THREAD_CLOSING"></a>

### `ERR_GREEN_THREAD_CLOSING`

[`greenThread.evaluate()`][] was called after [`greenThread.close()`][].

<a id="ERR_GREEN_THREAD_CPU_LIMIT"></a>

### `ERR_GREEN_THREAD_CPU_LIMIT`

A [green thread][] was terminated because it reached one of its CPU time
limits.

<a id="ERR_GREEN_THREAD_EXITED"></a>

### `ERR_GREEN_THREAD_EXITED`

An operation was attempted on a [green thread][] that has exited, or a pending
[`greenThread.evaluate()`][] call was interrupted because the green thread
exited.

<a id="ERR_GREEN_THREAD_ISOLATE_GROUPS_UNSUPPORTED"></a>

### `ERR_GREEN_THREAD_ISOLATE_GROUPS_UNSUPPORTED`

An [`IsolateGroup`][] was created, or a [green thread][] was asked to use a new
isolate group, but this build of Node.js does not support isolate groups.
They require building Node.js with `--experimental-enable-pointer-compression`.

<a id="ERR_GREEN_THREAD_OUT_OF_MEMORY"></a>

### `ERR_GREEN_THREAD_OUT_OF_MEMORY`

A [green thread][] was terminated because it reached its heap limit.

<a id="ERR_GREEN_THREAD_RPC_DISPOSED"></a>

### `ERR_GREEN_THREAD_RPC_DISPOSED`

A method of an RPC stub of a [green thread][] was called after the stub was
disposed.

<a id="ERR_GREEN_THREAD_RPC_NO_SUCH_METHOD"></a>

### `ERR_GREEN_THREAD_RPC_NO_SUCH_METHOD`

An RPC call between a [green thread][] and its host was made for a method that
the target doesn't have.

<a id="ERR_GREEN_THREAD_RPC_UNKNOWN_EXPORT"></a>

### `ERR_GREEN_THREAD_RPC_UNKNOWN_EXPORT`

An RPC call between a [green thread][] and its host was made to a target that
was already released.

<a id="ERR_GREEN_THREAD_STALLED"></a>

### `ERR_GREEN_THREAD_STALLED`

A [green thread][] was terminated because it [stalled][green thread stalls]
other green threads.

<a id="ERR_HTTP2_ALTSVC_INVALID_ORIGIN"></a>

### `ERR_HTTP2_ALTSVC_INVALID_ORIGIN`
Expand Down Expand Up @@ -4815,6 +4885,7 @@ An error occurred trying to allocate memory. This should never happen.
[`ERR_REQUIRE_ASYNC_MODULE`]: #err_require_async_module
[`Error.isError`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/isError
[`EventEmitter`]: events.md#class-eventemitter
[`IsolateGroup`]: green_threads.md#class-isolategroup
[`MessagePort`]: worker_threads.md#class-messageport
[`Object.getPrototypeOf`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getPrototypeOf
[`Object.setPrototypeOf`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/setPrototypeOf
Expand Down Expand Up @@ -4851,6 +4922,8 @@ An error occurred trying to allocate memory. This should never happen.
[`fs.symlinkSync()`]: fs.md#fssymlinksynctarget-path-type
[`fs.unlink`]: fs.md#fsunlinkpath-callback
[`fs`]: fs.md
[`greenThread.close()`]: green_threads.md#greenthreadcloseoptions
[`greenThread.evaluate()`]: green_threads.md#greenthreadevaluatesource-options
[`hash.digest()`]: crypto.md#hashdigestencoding
[`hash.update()`]: crypto.md#hashupdatedata-inputencoding
[`http`]: http.md
Expand Down Expand Up @@ -4894,6 +4967,8 @@ An error occurred trying to allocate memory. This should never happen.
[domains]: domain.md
[event emitter-based]: events.md#class-eventemitter
[file descriptors]: https://en.wikipedia.org/wiki/File_descriptor
[green thread]: green_threads.md
[green thread stalls]: green_threads.md#stalls
[package map]: packages.md#package-maps
[relative URL]: https://url.spec.whatwg.org/#relative-url-string
[self-reference a package using its name]: packages.md#self-referencing-a-package-using-its-name
Expand Down
Loading
Loading