{ "type": "module", "source": "doc/api/worker_threads.md", "modules": [ { "textRaw": "Worker Threads", "name": "worker_threads", "introduced_in": "v10.5.0", "stability": 1, "stabilityText": "Experimental", "desc": "<p>The <code>worker</code> module provides a way to create multiple environments running\non independent threads, and to create message channels between them. It\ncan be accessed using the <code>--experimental-worker</code> flag and:</p>\n<pre><code class=\"language-js\">const worker = require('worker_threads');\n</code></pre>\n<p>Workers are useful for performing CPU-intensive JavaScript operations; do not\nuse them for I/O, since Node.js’s built-in mechanisms for performing operations\nasynchronously already treat it more efficiently than Worker threads can.</p>\n<p>Workers, unlike child processes or when using the <code>cluster</code> module, can also\nshare memory efficiently by transferring <code>ArrayBuffer</code> instances or sharing\n<code>SharedArrayBuffer</code> instances between them.</p>\n<pre><code class=\"language-js\">const {\n Worker, isMainThread, parentPort, workerData\n} = require('worker_threads');\n\nif (isMainThread) {\n module.exports = async function parseJSAsync(script) {\n return new Promise((resolve, reject) => {\n const worker = new Worker(__filename, {\n workerData: script\n });\n worker.on('message', resolve);\n worker.on('error', reject);\n worker.on('exit', (code) => {\n if (code !== 0)\n reject(new Error(`Worker stopped with exit code ${code}`));\n });\n });\n };\n} else {\n const { parse } = require('some-js-parsing-library');\n const script = workerData;\n parentPort.postMessage(parse(script));\n}\n</code></pre>\n<p>Note that this example spawns a Worker thread for each <code>parse</code> call.\nIn practice, it is strongly recommended to use a pool of Workers for these\nkinds of tasks, since the overhead of creating Workers would likely exceed the\nbenefit of handing the work off to it.</p>", "properties": [ { "textRaw": "`isMainThread` {boolean}", "type": "boolean", "name": "isMainThread", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<p>Is <code>true</code> if this code is not running inside of a <a href=\"#worker_threads_class_worker\"><code>Worker</code></a> thread.</p>" }, { "textRaw": "`parentPort` {null|MessagePort}", "type": "null|MessagePort", "name": "parentPort", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<p>If this thread was spawned as a <a href=\"#worker_threads_class_worker\"><code>Worker</code></a>, this will be a <a href=\"#worker_threads_class_messageport\"><code>MessagePort</code></a>\nallowing communication with the parent thread. Messages sent using\n<code>parentPort.postMessage()</code> will be available in the parent thread\nusing <code>worker.on('message')</code>, and messages sent from the parent thread\nusing <code>worker.postMessage()</code> will be available in this thread using\n<code>parentPort.on('message')</code>.</p>" }, { "textRaw": "`threadId` {integer}", "type": "integer", "name": "threadId", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<p>An integer identifier for the current thread. On the corresponding worker object\n(if there is any), it is available as <a href=\"#worker_threads_worker_threadid_1\"><code>worker.threadId</code></a>.</p>" }, { "textRaw": "worker.workerData", "name": "workerData", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<p>An arbitrary JavaScript value that contains a clone of the data passed\nto this thread’s <code>Worker</code> constructor.</p>" } ], "classes": [ { "textRaw": "Class: MessageChannel", "type": "class", "name": "MessageChannel", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<p>Instances of the <code>worker.MessageChannel</code> class represent an asynchronous,\ntwo-way communications channel.\nThe <code>MessageChannel</code> has no methods of its own. <code>new MessageChannel()</code>\nyields an object with <code>port1</code> and <code>port2</code> properties, which refer to linked\n<a href=\"#worker_threads_class_messageport\"><code>MessagePort</code></a> instances.</p>\n<pre><code class=\"language-js\">const { MessageChannel } = require('worker_threads');\n\nconst { port1, port2 } = new MessageChannel();\nport1.on('message', (message) => console.log('received', message));\nport2.postMessage({ foo: 'bar' });\n// prints: received { foo: 'bar' } from the `port1.on('message')` listener\n</code></pre>" }, { "textRaw": "Class: MessagePort", "type": "class", "name": "MessagePort", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<ul>\n<li>Extends: <a href=\"events.html#events_class_eventemitter\" class=\"type\">&lt;EventEmitter&gt;</a></li>\n</ul>\n<p>Instances of the <code>worker.MessagePort</code> class represent one end of an\nasynchronous, two-way communications channel. It can be used to transfer\nstructured data, memory regions and other <code>MessagePort</code>s between different\n<a href=\"#worker_threads_class_worker\"><code>Worker</code></a>s.</p>\n<p>With the exception of <code>MessagePort</code>s being <a href=\"events.html\"><code>EventEmitter</code></a>s rather\nthan <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/EventTarget\"><code>EventTarget</code></a>s, this implementation matches <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/MessagePort\">browser <code>MessagePort</code></a>s.</p>", "events": [ { "textRaw": "Event: 'close'", "type": "event", "name": "close", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "params": [], "desc": "<p>The <code>'close'</code> event is emitted once either side of the channel has been\ndisconnected.</p>" }, { "textRaw": "Event: 'message'", "type": "event", "name": "message", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "params": [ { "textRaw": "`value` {any} The transmitted value", "name": "value", "type": "any", "desc": "The transmitted value" } ], "desc": "<p>The <code>'message'</code> event is emitted for any incoming message, containing the cloned\ninput of <a href=\"#worker_threads_port_postmessage_value_transferlist\"><code>port.postMessage()</code></a>.</p>\n<p>Listeners on this event will receive a clone of the <code>value</code> parameter as passed\nto <code>postMessage()</code> and no further arguments.</p>" } ], "methods": [ { "textRaw": "port.close()", "type": "method", "name": "close", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "<p>Disables further sending of messages on either side of the connection.\nThis method can be called when no further communication will happen over this\n<code>MessagePort</code>.</p>" }, { "textRaw": "port.postMessage(value[, transferList])", "type": "method", "name": "postMessage", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`value` {any}", "name": "value", "type": "any" }, { "textRaw": "`transferList` {Object[]}", "name": "transferList", "type": "Object[]", "optional": true } ] } ], "desc": "<p>Sends a JavaScript value to the receiving side of this channel.\n<code>value</code> will be transferred in a way which is compatible with\nthe <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm\">HTML structured clone algorithm</a>. In particular, it may contain circular\nreferences and objects like typed arrays that the <code>JSON</code> API is not able\nto stringify.</p>\n<p><code>transferList</code> may be a list of <code>ArrayBuffer</code> and <code>MessagePort</code> objects.\nAfter transferring, they will not be usable on the sending side of the channel\nanymore (even if they are not contained in <code>value</code>). Unlike with\n<a href=\"child_process.html\">child processes</a>, transferring handles such as network sockets is currently\nnot supported.</p>\n<p>If <code>value</code> contains <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer\"><code>SharedArrayBuffer</code></a> instances, those will be accessible\nfrom either thread. They cannot be listed in <code>transferList</code>.</p>\n<p><code>value</code> may still contain <code>ArrayBuffer</code> instances that are not in\n<code>transferList</code>; in that case, the underlying memory is copied rather than moved.</p>\n<p>Because the object cloning uses the structured clone algorithm,\nnon-enumerable properties, property accessors, and object prototypes are\nnot preserved. In particular, <a href=\"buffer.html\"><code>Buffer</code></a> objects will be read as\nplain <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array\"><code>Uint8Array</code></a>s on the receiving side.</p>\n<p>The message object will be cloned immediately, and can be modified after\nposting without having side effects.</p>\n<p>For more information on the serialization and deserialization mechanisms\nbehind this API, see the <a href=\"v8.html#v8_serialization_api\">serialization API of the <code>v8</code> module</a>.</p>" }, { "textRaw": "port.ref()", "type": "method", "name": "ref", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "<p>Opposite of <code>unref()</code>. Calling <code>ref()</code> on a previously <code>unref()</code>ed port will\n<em>not</em> let the program exit if it's the only active handle left (the default\nbehavior). If the port is <code>ref()</code>ed, calling <code>ref()</code> again will have no effect.</p>\n<p>If listeners are attached or removed using <code>.on('message')</code>, the port will\nbe <code>ref()</code>ed and <code>unref()</code>ed automatically depending on whether\nlisteners for the event exist.</p>" }, { "textRaw": "port.start()", "type": "method", "name": "start", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "<p>Starts receiving messages on this <code>MessagePort</code>. When using this port\nas an event emitter, this will be called automatically once <code>'message'</code>\nlisteners are attached.</p>" }, { "textRaw": "port.unref()", "type": "method", "name": "unref", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "<p>Calling <code>unref()</code> on a port will allow the thread to exit if this is the only\nactive handle in the event system. If the port is already <code>unref()</code>ed calling\n<code>unref()</code> again will have no effect.</p>\n<p>If listeners are attached or removed using <code>.on('message')</code>, the port will\nbe <code>ref()</code>ed and <code>unref()</code>ed automatically depending on whether\nlisteners for the event exist.</p>" } ] }, { "textRaw": "Class: Worker", "type": "class", "name": "Worker", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<ul>\n<li>Extends: <a href=\"events.html#events_class_eventemitter\" class=\"type\">&lt;EventEmitter&gt;</a></li>\n</ul>\n<p>The <code>Worker</code> class represents an independent JavaScript execution thread.\nMost Node.js APIs are available inside of it.</p>\n<p>Notable differences inside a Worker environment are:</p>\n<ul>\n<li>The <a href=\"process.html#process_process_stdin\"><code>process.stdin</code></a>, <a href=\"process.html#process_process_stdout\"><code>process.stdout</code></a> and <a href=\"process.html#process_process_stderr\"><code>process.stderr</code></a>\nmay be redirected by the parent thread.</li>\n<li>The <a href=\"#worker_threads_worker_ismainthread\"><code>require('worker_threads').isMainThread</code></a> property is set to <code>false</code>.</li>\n<li>The <a href=\"#worker_threads_worker_parentport\"><code>require('worker_threads').parentPort</code></a> message port is available.</li>\n<li><a href=\"process.html#process_process_exit_code\"><code>process.exit()</code></a> does not stop the whole program, just the single thread,\nand <a href=\"process.html#process_process_abort\"><code>process.abort()</code></a> is not available.</li>\n<li><a href=\"process.html#process_process_chdir_directory\"><code>process.chdir()</code></a> and <code>process</code> methods that set group or user ids\nare not available.</li>\n<li><a href=\"process.html#process_process_env\"><code>process.env</code></a> is a read-only reference to the environment variables.</li>\n<li><a href=\"process.html#process_process_title\"><code>process.title</code></a> cannot be modified.</li>\n<li>Signals will not be delivered through <a href=\"process.html#process_signal_events\"><code>process.on('...')</code></a>.</li>\n<li>Execution may stop at any point as a result of <a href=\"#worker_threads_worker_terminate_callback\"><code>worker.terminate()</code></a>\nbeing invoked.</li>\n<li>IPC channels from parent processes are not accessible.</li>\n</ul>\n<p>Currently, the following differences also exist until they are addressed:</p>\n<ul>\n<li>The <a href=\"inspector.html\"><code>inspector</code></a> module is not available yet.</li>\n<li>Native addons are not supported yet.</li>\n</ul>\n<p>Creating <code>Worker</code> instances inside of other <code>Worker</code>s is possible.</p>\n<p>Like <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API\">Web Workers</a> and the <a href=\"cluster.html\"><code>cluster</code> module</a>, two-way communication can be\nachieved through inter-thread message passing. Internally, a <code>Worker</code> has a\nbuilt-in pair of <a href=\"#worker_threads_class_messageport\"><code>MessagePort</code></a>s that are already associated with each other\nwhen the <code>Worker</code> is created. While the <code>MessagePort</code> object on the parent side\nis not directly exposed, its functionalities are exposed through\n<a href=\"#worker_threads_worker_postmessage_value_transferlist\"><code>worker.postMessage()</code></a> and the <a href=\"#worker_threads_event_message_1\"><code>worker.on('message')</code></a> event\non the <code>Worker</code> object for the parent thread.</p>\n<p>To create custom messaging channels (which is encouraged over using the default\nglobal channel because it facilitates separation of concerns), users can create\na <code>MessageChannel</code> object on either thread and pass one of the\n<code>MessagePort</code>s on that <code>MessageChannel</code> to the other thread through a\npre-existing channel, such as the global one.</p>\n<p>See <a href=\"#worker_threads_port_postmessage_value_transferlist\"><code>port.postMessage()</code></a> for more information on how messages are passed,\nand what kind of JavaScript values can be successfully transported through\nthe thread barrier.</p>\n<pre><code class=\"language-js\">const assert = require('assert');\nconst {\n Worker, MessageChannel, MessagePort, isMainThread, parentPort\n} = require('worker_threads');\nif (isMainThread) {\n const worker = new Worker(__filename);\n const subChannel = new MessageChannel();\n worker.postMessage({ hereIsYourPort: subChannel.port1 }, [subChannel.port1]);\n subChannel.port2.on('message', (value) => {\n console.log('received:', value);\n });\n} else {\n parentPort.once('message', (value) => {\n assert(value.hereIsYourPort instanceof MessagePort);\n value.hereIsYourPort.postMessage('the worker is sending this');\n value.hereIsYourPort.close();\n });\n}\n</code></pre>", "events": [ { "textRaw": "Event: 'error'", "type": "event", "name": "error", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "params": [ { "textRaw": "`err` {Error}", "name": "err", "type": "Error" } ], "desc": "<p>The <code>'error'</code> event is emitted if the worker thread throws an uncaught\nexception. In that case, the worker will be terminated.</p>" }, { "textRaw": "Event: 'exit'", "type": "event", "name": "exit", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "params": [ { "textRaw": "`exitCode` {integer}", "name": "exitCode", "type": "integer" } ], "desc": "<p>The <code>'exit'</code> event is emitted once the worker has stopped. If the worker\nexited by calling <a href=\"process.html#process_process_exit_code\"><code>process.exit()</code></a>, the <code>exitCode</code> parameter will be the\npassed exit code. If the worker was terminated, the <code>exitCode</code> parameter will\nbe <code>1</code>.</p>" }, { "textRaw": "Event: 'message'", "type": "event", "name": "message", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "params": [ { "textRaw": "`value` {any} The transmitted value", "name": "value", "type": "any", "desc": "The transmitted value" } ], "desc": "<p>The <code>'message'</code> event is emitted when the worker thread has invoked\n<a href=\"#worker_threads_worker_postmessage_value_transferlist\"><code>require('worker_threads').parentPort.postMessage()</code></a>.\nSee the <a href=\"#worker_threads_event_message\"><code>port.on('message')</code></a> event for more details.</p>" }, { "textRaw": "Event: 'online'", "type": "event", "name": "online", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "params": [], "desc": "<p>The <code>'online'</code> event is emitted when the worker thread has started executing\nJavaScript code.</p>" } ], "methods": [ { "textRaw": "worker.postMessage(value[, transferList])", "type": "method", "name": "postMessage", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`value` {any}", "name": "value", "type": "any" }, { "textRaw": "`transferList` {Object[]}", "name": "transferList", "type": "Object[]", "optional": true } ] } ], "desc": "<p>Send a message to the worker that will be received via\n<a href=\"#worker_threads_event_message\"><code>require('worker_threads').parentPort.on('message')</code></a>.\nSee <a href=\"#worker_threads_port_postmessage_value_transferlist\"><code>port.postMessage()</code></a> for more details.</p>" }, { "textRaw": "worker.ref()", "type": "method", "name": "ref", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "<p>Opposite of <code>unref()</code>, calling <code>ref()</code> on a previously <code>unref()</code>ed worker will\n<em>not</em> let the program exit if it's the only active handle left (the default\nbehavior). If the worker is <code>ref()</code>ed, calling <code>ref()</code> again will have\nno effect.</p>" }, { "textRaw": "worker.terminate([callback])", "type": "method", "name": "terminate", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`callback` {Function}", "name": "callback", "type": "Function", "options": [ { "textRaw": "`err` {Error}", "name": "err", "type": "Error" }, { "textRaw": "`exitCode` {integer}", "name": "exitCode", "type": "integer" } ], "optional": true } ] } ], "desc": "<p>Stop all JavaScript execution in the worker thread as soon as possible.\n<code>callback</code> is an optional function that is invoked once this operation is known\nto have completed.</p>\n<p><strong>Warning</strong>: Currently, not all code in the internals of Node.js is prepared to\nexpect termination at arbitrary points in time and may crash if it encounters\nthat condition. Consequently, only call <code>.terminate()</code> if it is known that the\nWorker thread is not accessing Node.js core modules other than what is exposed\nin the <code>worker</code> module.</p>" }, { "textRaw": "worker.unref()", "type": "method", "name": "unref", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "<p>Calling <code>unref()</code> on a worker will allow the thread to exit if this is the only\nactive handle in the event system. If the worker is already <code>unref()</code>ed calling\n<code>unref()</code> again will have no effect.</p>" } ], "properties": [ { "textRaw": "`stderr` {stream.Readable}", "type": "stream.Readable", "name": "stderr", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<p>This is a readable stream which contains data written to <a href=\"process.html#process_process_stderr\"><code>process.stderr</code></a>\ninside the worker thread. If <code>stderr: true</code> was not passed to the\n<a href=\"#worker_threads_class_worker\"><code>Worker</code></a> constructor, then data will be piped to the parent thread's\n<a href=\"process.html#process_process_stderr\"><code>process.stderr</code></a> stream.</p>" }, { "textRaw": "`stdin` {null|stream.Writable}", "type": "null|stream.Writable", "name": "stdin", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<p>If <code>stdin: true</code> was passed to the <a href=\"#worker_threads_class_worker\"><code>Worker</code></a> constructor, this is a\nwritable stream. The data written to this stream will be made available in\nthe worker thread as <a href=\"process.html#process_process_stdin\"><code>process.stdin</code></a>.</p>" }, { "textRaw": "`stdout` {stream.Readable}", "type": "stream.Readable", "name": "stdout", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<p>This is a readable stream which contains data written to <a href=\"process.html#process_process_stdout\"><code>process.stdout</code></a>\ninside the worker thread. If <code>stdout: true</code> was not passed to the\n<a href=\"#worker_threads_class_worker\"><code>Worker</code></a> constructor, then data will be piped to the parent thread's\n<a href=\"process.html#process_process_stdout\"><code>process.stdout</code></a> stream.</p>" }, { "textRaw": "`threadId` {integer}", "type": "integer", "name": "threadId", "meta": { "added": [ "v10.5.0" ], "changes": [] }, "desc": "<p>An integer identifier for the referenced thread. Inside the worker thread,\nit is available as <a href=\"#worker_threads_worker_threadid\"><code>require('worker_threads').threadId</code></a>.</p>" } ], "signatures": [ { "params": [ { "textRaw": "`filename` {string} The path to the Worker’s main script. Must be either an absolute path or a relative path (i.e. relative to the current working directory) starting with `./` or `../`. If `options.eval` is `true`, this is a string containing JavaScript code rather than a path.", "name": "filename", "type": "string", "desc": "The path to the Worker’s main script. Must be either an absolute path or a relative path (i.e. relative to the current working directory) starting with `./` or `../`. If `options.eval` is `true`, this is a string containing JavaScript code rather than a path." }, { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`eval` {boolean} If `true`, interpret the first argument to the constructor as a script that is executed once the worker is online.", "name": "eval", "type": "boolean", "desc": "If `true`, interpret the first argument to the constructor as a script that is executed once the worker is online." }, { "textRaw": "`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 `function`s).", "name": "workerData", "type": "any", "desc": "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 `function`s)." }, { "textRaw": "stdin {boolean} If this is set to `true`, then `worker.stdin` will provide a writable stream whose contents will appear as `process.stdin` inside the Worker. By default, no data is provided.", "name": "stdin", "type": "boolean", "desc": "If this is set to `true`, then `worker.stdin` will provide a writable stream whose contents will appear as `process.stdin` inside the Worker. By default, no data is provided." }, { "textRaw": "stdout {boolean} If this is set to `true`, then `worker.stdout` will not automatically be piped through to `process.stdout` in the parent.", "name": "stdout", "type": "boolean", "desc": "If this is set to `true`, then `worker.stdout` will not automatically be piped through to `process.stdout` in the parent." }, { "textRaw": "stderr {boolean} If this is set to `true`, then `worker.stderr` will not automatically be piped through to `process.stderr` in the parent.", "name": "stderr", "type": "boolean", "desc": "If this is set to `true`, then `worker.stderr` will not automatically be piped through to `process.stderr` in the parent." } ], "optional": true } ] } ] } ], "type": "module", "displayName": "Worker Threads" } ] }