Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
8bef9d9
src: add NewIsolate() overload taking a platform delegate
jasnell Nov 5, 2026
97853d8
lib,src: add experimental node:green_threads module
jasnell Nov 5, 2026
7144a87
lib,src: schedule isolates on any pool thread
jasnell Nov 5, 2026
fc9bcc1
lib,src: fix teardown, timer and task lifetime issues
jasnell Nov 5, 2026
93aa9c4
lib,src: add CPU and memory limits and a warm pool
jasnell Nov 5, 2026
b2b591a
benchmark: add green_threads benchmarks
jasnell Nov 5, 2026
522d5b0
lib,src: resolve setWarmPoolSize() once the pool is full
jasnell Nov 5, 2026
8db7d07
lib,src: fix ArrayBuffer memory limit before the first GC
jasnell Nov 5, 2026
7918e60
lib,src: add isolate groups
jasnell Nov 5, 2026
3cba778
lib,src: stop green threads that ignore termination
jasnell Nov 5, 2026
138381b
lib,src: add setUnresponsiveTimeouts()
jasnell Nov 5, 2026
2848754
src: fix build with the V8 sandbox enabled
jasnell Nov 5, 2026
d80d6c3
lib,src: initialize warm isolates in the background
jasnell Nov 5, 2026
db2dc18
lib,src: add EventTarget and AbortController
jasnell Nov 5, 2026
08f925f
lib,src: add RPC
jasnell Nov 5, 2026
674e445
lib,src: transfer ArrayBuffers and share SharedArrayBuffers
jasnell Nov 5, 2026
e0e285b
worker: allow MessagePortData owners other than MessagePorts
jasnell Nov 5, 2026
40b99fd
lib,src: add MessageChannel and MessagePort
jasnell Nov 5, 2026
604892a
lib,src: add ES modules and exports
jasnell Nov 6, 2026
a9e2785
lib,src: keep the properties of errors
jasnell Nov 6, 2026
76a41b5
lib,src: start green threads from a bootstrapped snapshot
jasnell Nov 14, 2026
8b5fd7f
lib,src: set the time origin when green threads start
jasnell Nov 14, 2026
d462fe9
lib,src: build the startup snapshots of green threads
jasnell Nov 14, 2026
7f0203c
lib,src: use a small snapshot in the default isolate group
jasnell Nov 14, 2026
432f680
lib,src: add NODE_GREEN_THREADS_POOL_SIZE
jasnell Nov 14, 2026
f3423f1
src: only query the memory for heap defaults when used
jasnell Nov 14, 2026
972ea1e
lib,src: keep the young generation limit
jasnell Nov 14, 2026
26b6a3f
lib,src: add warm pools for isolate groups and memory limits
jasnell Nov 14, 2026
4b6fe8b
lib,src: don't copy the runtime's sources into snapshots
jasnell Nov 14, 2026
5e081b8
src,doc: fix lint and formatting of green threads
jasnell Nov 14, 2026
9ef7765
src: don't build green threads' snapshot for embedders
jasnell Nov 14, 2026
7897161
lib,src: add BroadcastChannel to green threads
jasnell Nov 14, 2026
b4556d3
lib,src: close the ports of abandoned green threads
jasnell Nov 14, 2026
2b4c77c
lib,src: add greenThread.close()
jasnell Nov 14, 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;
}
}
}
28 changes: 28 additions & 0 deletions doc/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -1489,6 +1489,16 @@ added:

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

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

<!-- YAML
added: REPLACEME
-->

> Stability: 1 - Experimental

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

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

<!-- YAML
Expand Down Expand Up @@ -4237,6 +4247,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 @@ -4337,6 +4361,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 @@ -5028,9 +5053,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 @@ -5056,6 +5083,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
67 changes: 67 additions & 0 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -1535,6 +1535,69 @@ 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_HTTP2_ALTSVC_INVALID_ORIGIN"></a>

### `ERR_HTTP2_ALTSVC_INVALID_ORIGIN`
Expand Down Expand Up @@ -4810,6 +4873,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 @@ -4846,6 +4910,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 @@ -4889,6 +4955,7 @@ 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
[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