diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index 7de28b99e403dc..2f46c6ef1a14ef 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -14,8 +14,8 @@ const worker = require('worker_threads'); ``` Workers (threads) are useful for performing CPU-intensive JavaScript operations. -They will not help much with I/O-intensive work. Node.js’s built-in asynchronous -I/O operations are more efficient than Workers can be. +They do not help much with I/O-intensive work. The Node.js built-in +asynchronous I/O operations are more efficient than Workers can be. Unlike `child_process` or `cluster`, `worker_threads` can share memory. They do so by transferring `ArrayBuffer` instances or sharing `SharedArrayBuffer` @@ -48,11 +48,11 @@ if (isMainThread) { ``` The above example spawns a Worker thread for each `parse()` call. In actual -practice, use a pool of Workers instead for these kinds of tasks. Otherwise, the +practice, use a pool of Workers for these kinds of tasks. Otherwise, the overhead of creating Workers would likely exceed their benefit. When implementing a worker pool, use the [`AsyncResource`][] API to inform -diagnostic tools (e.g. in order to provide asynchronous stack traces) about the +diagnostic tools (e.g. to provide asynchronous stack traces) about the correlation between tasks and their outcomes. See ["Using `AsyncResource` for a `Worker` thread pool"][async-resource-worker-pool] in the `async_hooks` documentation for an example implementation. @@ -90,7 +90,7 @@ added: --> Mark an object as not transferable. If `object` occurs in the transfer list of -a [`port.postMessage()`][] call, it will be ignored. +a [`port.postMessage()`][] call, it is ignored. In particular, this makes sense for objects that can be cloned, rather than transferred, and which are used by other objects on the sending side. @@ -126,22 +126,22 @@ There is no equivalent to this API in browsers. added: v11.13.0 --> -* `port` {MessagePort} The message port which will be transferred. +* `port` {MessagePort} The message port to transfer. * `contextifiedSandbox` {Object} A [contextified][] object as returned by the `vm.createContext()` method. * Returns: {MessagePort} Transfer a `MessagePort` to a different [`vm`][] Context. The original `port` -object will be rendered unusable, and the returned `MessagePort` instance will -take its place. +object is rendered unusable, and the returned `MessagePort` instance +takes its place. -The returned `MessagePort` will be an object in the target context, and will -inherit from its global `Object` class. Objects passed to the -[`port.onmessage()`][] listener will also be created in the target context +The returned `MessagePort` is an object in the target context and +inherits from its global `Object` class. Objects passed to the +[`port.onmessage()`][] listener are also created in the target context and inherit from its global `Object` class. -However, the created `MessagePort` will no longer inherit from +However, the created `MessagePort` no longer inherits from [`EventTarget`][], and only [`port.onmessage()`][] can be used to receive events using it. @@ -152,11 +152,11 @@ added: v10.5.0 * {null|MessagePort} -If this thread was spawned as a [`Worker`][], this will be a [`MessagePort`][] +If this thread is a [`Worker`][], this is a [`MessagePort`][] allowing communication with the parent thread. Messages sent using -`parentPort.postMessage()` will be available in the parent thread +`parentPort.postMessage()` are available in the parent thread using `worker.on('message')`, and messages sent from the parent thread -using `worker.postMessage()` will be available in this thread using +using `worker.postMessage()` are available in this thread using `parentPort.on('message')`. ```js @@ -201,8 +201,8 @@ console.log(receiveMessageOnPort(port2)); // Prints: undefined ``` -When this function is used, no `'message'` event will be emitted and the -`onmessage` listener will not be invoked. +When this function is used, no `'message'` event is emitted and the +`onmessage` listener is not invoked. ## `worker.resourceLimits` Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed -BroadcastChannel will *not* let the program exit if it's the only active handle +BroadcastChannel does *not* let the program exit if it's the only active handle left (the default behavior). If the port is `ref()`ed, calling `ref()` again -will have no effect. +has no effect. ### `broadcastChannel.unref()` -Calling `unref()` on a BroadcastChannel will allow the thread to exit if this +Calling `unref()` on a BroadcastChannel allows the thread to exit if this is the only active handle in the event system. If the BroadcastChannel is -already `unref()`ed calling `unref()` again will have no effect. +already `unref()`ed calling `unref()` again has no effect. ## Class: `MessageChannel` -Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed port will +Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed port does *not* let the program exit if it's the only active handle left (the default -behavior). If the port is `ref()`ed, calling `ref()` again will have no effect. +behavior). If the port is `ref()`ed, calling `ref()` again has no effect. -If listeners are attached or removed using `.on('message')`, the port will -be `ref()`ed and `unref()`ed automatically depending on whether +If listeners are attached or removed using `.on('message')`, the port +is `ref()`ed and `unref()`ed automatically depending on whether listeners for the event exist. ### `port.start()` @@ -625,13 +625,13 @@ added: v10.5.0 --> Starts receiving messages on this `MessagePort`. When using this port -as an event emitter, this will be called automatically once `'message'` +as an event emitter, this is called automatically once `'message'` listeners are attached. This method exists for parity with the Web `MessagePort` API. In Node.js, it is only useful for ignoring messages when no event listener is present. -Node.js also diverges in its handling of `.onmessage`. Setting it will -automatically call `.start()`, but unsetting it will let messages queue up +Node.js also diverges in its handling of `.onmessage`. Setting it +automatically calls `.start()`, but unsetting it lets messages queue up until a new handler is set or the port is discarded. ### `port.unref()` @@ -639,12 +639,12 @@ until a new handler is set or the port is discarded. added: v10.5.0 --> -Calling `unref()` on a port will allow the thread to exit if this is the only +Calling `unref()` on a port allows the thread to exit if this is the only active handle in the event system. If the port is already `unref()`ed calling -`unref()` again will have no effect. +`unref()` again has no effect. -If listeners are attached or removed using `.on('message')`, the port will -be `ref()`ed and `unref()`ed automatically depending on whether +If listeners are attached or removed using `.on('message')`, the port is +`ref()`ed and `unref()`ed automatically depending on whether listeners for the event exist. ## Class: `Worker` @@ -668,12 +668,12 @@ Notable differences inside a Worker environment are: * [`process.chdir()`][] and `process` methods that set group or user ids are not available. * [`process.env`][] is a copy of the parent thread's environment variables, - unless otherwise specified. Changes to one copy will not be visible in other - threads, and will not be visible to native add-ons (unless - [`worker.SHARE_ENV`][] has been passed as the `env` option to the + unless otherwise specified. Changes to one copy are not visible in other + threads, and are not visible to native add-ons (unless + [`worker.SHARE_ENV`][] is passed as the `env` option to the [`Worker`][] constructor). * [`process.title`][] cannot be modified. -* Signals will not be delivered through [`process.on('...')`][Signals events]. +* Signals are not delivered through [`process.on('...')`][Signals events]. * Execution may stop at any point as a result of [`worker.terminate()`][] being invoked. * IPC channels from parent processes are not accessible. @@ -772,45 +772,45 @@ changes: * `options` {Object} * `argv` {any[]} List of arguments which would be stringified and appended to `process.argv` in the worker. This is mostly similar to the `workerData` - but the values will be available on the global `process.argv` as if they + but the values are available on the global `process.argv` as if they were passed as CLI options to the script. * `env` {Object} If set, specifies the initial value of `process.env` inside the Worker thread. As a special value, [`worker.SHARE_ENV`][] may be used to specify that the parent thread and the child thread should share their environment variables; in that case, changes to one thread’s `process.env` - object will affect the other thread as well. **Default:** `process.env`. + object affect the other thread as well. **Default:** `process.env`. * `eval` {boolean} If `true` and the first argument is a `string`, interpret the first argument to the constructor as a script that is executed once the worker is online. * `execArgv` {string[]} List of node CLI options passed to the worker. V8 options (such as `--max-old-space-size`) and options that affect the - process (such as `--title`) are not supported. If set, this will be provided - as [`process.execArgv`][] inside the worker. By default, options will be + process (such as `--title`) are not supported. If set, this is provided + as [`process.execArgv`][] inside the worker. By default, options are inherited from the parent thread. - * `stdin` {boolean} If this is set to `true`, then `worker.stdin` will - provide a writable stream whose contents will appear as `process.stdin` + * `stdin` {boolean} If this is set to `true`, then `worker.stdin` + provides a writable stream whose contents appear as `process.stdin` inside the Worker. By default, no data is provided. - * `stdout` {boolean} If this is set to `true`, then `worker.stdout` will - not automatically be piped through to `process.stdout` in the parent. - * `stderr` {boolean} If this is set to `true`, then `worker.stderr` will - not automatically be piped through to `process.stderr` in the parent. - * `workerData` {any} Any JavaScript value that will be cloned and made - available as [`require('worker_threads').workerData`][]. The cloning will - occur as described in the [HTML structured clone algorithm][], and an error - will be thrown if the object cannot be cloned (e.g. because it contains + * `stdout` {boolean} If this is set to `true`, then `worker.stdout` is + not automatically piped through to `process.stdout` in the parent. + * `stderr` {boolean} If this is set to `true`, then `worker.stderr` is + not automatically piped through to `process.stderr` in the parent. + * `workerData` {any} Any JavaScript value that is cloned and made + available as [`require('worker_threads').workerData`][]. The cloning + occurs as described in the [HTML structured clone algorithm][], and an error + is thrown if the object cannot be cloned (e.g. because it contains `function`s). - * `trackUnmanagedFds` {boolean} If this is set to `true`, then the Worker will - track raw file descriptors managed through [`fs.open()`][] and - [`fs.close()`][], and close them when the Worker exits, similar to other + * `trackUnmanagedFds` {boolean} If this is set to `true`, then the Worker + tracks raw file descriptors managed through [`fs.open()`][] and + [`fs.close()`][], and closes them when the Worker exits, similar to other resources like network sockets or file descriptors managed through the [`FileHandle`][] API. This option is automatically inherited by all nested `Worker`s. **Default**: `true`. * `transferList` {Object[]} If one or more `MessagePort`-like objects are passed in `workerData`, a `transferList` is required for those - items or [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`][] will be thrown. + items or [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`][] is thrown. See [`port.postMessage()`][] for more information. * `resourceLimits` {Object} An optional set of resource limits for the new - JS engine instance. Reaching these limits will lead to termination of the + JS engine instance. Reaching these limits leads to termination of the `Worker` instance. These limits only affect the JS engine, and no external data, including no `ArrayBuffer`s. Even if these limits are set, the process may still abort if it encounters a global out-of-memory situation. @@ -830,7 +830,7 @@ added: v10.5.0 * `err` {Error} The `'error'` event is emitted if the worker thread throws an uncaught -exception. In that case, the worker will be terminated. +exception. In that case, the worker is terminated. ### Event: `'exit'` -Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker will +Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker does *not* let the program exit if it's the only active handle left (the default -behavior). If the worker is `ref()`ed, calling `ref()` again will have +behavior). If the worker is `ref()`ed, calling `ref()` again has no effect. ### `worker.resourceLimits` @@ -1005,7 +1005,7 @@ added: v10.5.0 This is a readable stream which contains data written to [`process.stderr`][] inside the worker thread. If `stderr: true` was not passed to the -[`Worker`][] constructor, then data will be piped to the parent thread's +[`Worker`][] constructor, then data is piped to the parent thread's [`process.stderr`][] stream. ### `worker.stdin` @@ -1028,7 +1028,7 @@ added: v10.5.0 This is a readable stream which contains data written to [`process.stdout`][] inside the worker thread. If `stdout: true` was not passed to the -[`Worker`][] constructor, then data will be piped to the parent thread's +[`Worker`][] constructor, then data is piped to the parent thread's [`process.stdout`][] stream. ### `worker.terminate()` @@ -1065,9 +1065,9 @@ This value is unique for each `Worker` instance inside a single process. added: v10.5.0 --> -Calling `unref()` on a worker will allow the thread to exit if this is the only +Calling `unref()` on a worker allows the thread to exit if this is the only active handle in the event system. If the worker is already `unref()`ed calling -`unref()` again will have no effect. +`unref()` again has no effect. [Addons worker support]: addons.md#addons_worker_support [ECMAScript module loader]: esm.md#esm_data_imports