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
8e2366a
src: add NewIsolate() overload taking a platform delegate
jasnell Nov 5, 2026
d0e4387
lib,src: add experimental node:green_threads module
jasnell Nov 5, 2026
3ff4408
lib,src: schedule isolates on any pool thread
jasnell Nov 5, 2026
a2b3204
lib,src: fix teardown, timer and task lifetime issues
jasnell Nov 5, 2026
01260f1
lib,src: add CPU and memory limits and a warm pool
jasnell Nov 5, 2026
e75a190
benchmark: add green_threads benchmarks
jasnell Nov 5, 2026
9d384b6
lib,src: resolve setWarmPoolSize() once the pool is full
jasnell Nov 5, 2026
eae3d86
lib,src: fix ArrayBuffer memory limit before the first GC
jasnell Nov 5, 2026
b83dc93
lib,src: add isolate groups
jasnell Nov 5, 2026
b33ed60
lib,src: stop green threads that ignore termination
jasnell Nov 5, 2026
f178b06
lib,src: add setUnresponsiveTimeouts()
jasnell Nov 5, 2026
e4be24d
src: fix build with the V8 sandbox enabled
jasnell Nov 5, 2026
54f0845
lib,src: initialize warm isolates in the background
jasnell Nov 5, 2026
febaf87
lib,src: add EventTarget and AbortController
jasnell Nov 5, 2026
4b0640e
lib,src: add RPC
jasnell Nov 5, 2026
087fa3b
lib,src: transfer ArrayBuffers and share SharedArrayBuffers
jasnell Nov 5, 2026
198fd24
worker: allow MessagePortData owners other than MessagePorts
jasnell Nov 5, 2026
ed5dcd8
lib,src: add MessageChannel and MessagePort
jasnell Nov 5, 2026
cacf5cb
lib,src: add ES modules and exports
jasnell Nov 6, 2026
f746044
lib,src: keep the properties of errors
jasnell Nov 6, 2026
16706a9
lib,src: start green threads from a bootstrapped snapshot
jasnell Nov 14, 2026
3b99b65
lib,src: set the time origin when green threads start
jasnell Nov 14, 2026
4d89efa
lib,src: build the startup snapshots of green threads
jasnell Nov 14, 2026
9e2218e
lib,src: use a small snapshot in the default isolate group
jasnell Nov 14, 2026
ece5a70
lib,src: add NODE_GREEN_THREADS_POOL_SIZE
jasnell Nov 14, 2026
d280172
src: only query the memory for heap defaults when used
jasnell Nov 14, 2026
0859a0d
lib,src: keep the young generation limit
jasnell Nov 14, 2026
3aa63ab
lib,src: add warm pools for isolate groups and memory limits
jasnell Nov 14, 2026
38f5b50
lib,src: don't copy the runtime's sources into snapshots
jasnell Nov 14, 2026
7d87efd
src,doc: fix lint and formatting of green threads
jasnell Nov 14, 2026
f0952fe
src: don't build green threads' snapshot for embedders
jasnell Nov 14, 2026
5b1cb41
lib,src: add BroadcastChannel to green threads
jasnell Nov 14, 2026
16ad43a
lib,src: close the ports of abandoned green threads
jasnell Nov 14, 2026
b27ffdf
lib,src: add greenThread.close()
jasnell Nov 14, 2026
0592b7b
lib,src: export RPC objects only once a message is serialized
jasnell Nov 16, 2026
147899e
lib: keep imported AbortSignals alive until they abort
jasnell Nov 16, 2026
6d31907
src,lib: add the --allow-green-threads permission
jasnell Nov 16, 2026
086d1d6
lib,src: add greenThreads.setStallPolicy()
jasnell Nov 16, 2026
c555adf
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 @@ -4823,6 +4893,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 @@ -4859,6 +4930,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 @@ -4902,6 +4975,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