Server : Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips PHP/7.4.20 System : Linux st2.domain.com 3.10.0-1127.10.1.el7.x86_64 #1 SMP Wed Jun 3 14:28:03 UTC 2020 x86_64 User : apache ( 48) PHP Version : 7.4.20 Disable Function : NONE Directory : /home/real/node-v13.0.1/doc/api/ |
{
"type": "module",
"source": "doc/api/worker_threads.md",
"modules": [
{
"textRaw": "Worker Threads",
"name": "worker_threads",
"introduced_in": "v10.5.0",
"stability": 2,
"stabilityText": "Stable",
"desc": "<p>The <code>worker_threads</code> module enables the use of threads that execute JavaScript\nin parallel. To access it:</p>\n<pre><code class=\"language-js\">const worker = require('worker_threads');\n</code></pre>\n<p>Workers (threads) are useful for performing CPU-intensive JavaScript operations.\nThey will not help much with I/O-intensive work. Node.js’s built-in asynchronous\nI/O operations are more efficient than Workers can be.</p>\n<p>Unlike <code>child_process</code> or <code>cluster</code>, <code>worker_threads</code> can share memory. They do\nso by transferring <code>ArrayBuffer</code> instances or sharing <code>SharedArrayBuffer</code>\ninstances.</p>\n<pre><code class=\"language-js\">const {\n Worker, isMainThread, parentPort, workerData\n} = require('worker_threads');\n\nif (isMainThread) {\n module.exports = 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>The above example spawns a Worker thread for each <code>parse()</code> call. In actual\npractice, use a pool of Workers instead for these kinds of tasks. Otherwise, the\noverhead of creating Workers would likely exceed their benefit.</p>\n<p>When implementing a worker pool, use the <a href=\"async_hooks.html#async_hooks_class_asyncresource\"><code>AsyncResource</code></a> API to inform\ndiagnostic tools (e.g. in order to provide asynchronous stack traces) about the\ncorrelation between tasks and their outcomes.</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>\n<pre><code class=\"language-js\">const { Worker, isMainThread } = require('worker_threads');\n\nif (isMainThread) {\n // This re-loads the current file inside a Worker instance.\n new Worker(__filename);\n} else {\n console.log('Inside Worker!');\n console.log(isMainThread); // Prints 'false'.\n}\n</code></pre>"
},
{
"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>\n<pre><code class=\"language-js\">const { Worker, isMainThread, parentPort } = require('worker_threads');\n\nif (isMainThread) {\n const worker = new Worker(__filename);\n worker.once('message', (message) => {\n console.log(message); // Prints 'Hello, world!'.\n });\n worker.postMessage('Hello, world!');\n} else {\n // When a message from the parent thread is received, send it back:\n parentPort.once('message', (message) => {\n parentPort.postMessage(message);\n });\n}\n</code></pre>"
},
{
"textRaw": "`SHARE_ENV` {symbol}",
"type": "symbol",
"name": "SHARE_ENV",
"meta": {
"added": [
"v11.14.0"
],
"changes": []
},
"desc": "<p>A special value that can be passed as the <code>env</code> option of the <a href=\"#worker_threads_class_worker\"><code>Worker</code></a>\nconstructor, to indicate that the current thread and the Worker thread should\nshare read and write access to the same set of environment variables.</p>\n<pre><code class=\"language-js\">const { Worker, SHARE_ENV } = require('worker_threads');\nnew Worker('process.env.SET_IN_WORKER = \"foo\"', { eval: true, env: SHARE_ENV })\n .on('exit', () => {\n console.log(process.env.SET_IN_WORKER); // Prints 'foo'.\n });\n</code></pre>"
},
{
"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>.\nThis value is unique for each <a href=\"#worker_threads_class_worker\"><code>Worker</code></a> instance inside a single process.</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>\n<p>The data is cloned as if using <a href=\"#worker_threads_port_postmessage_value_transferlist\"><code>postMessage()</code></a>,\naccording to the <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm\">HTML structured clone algorithm</a>.</p>\n<pre><code class=\"language-js\">const { Worker, isMainThread, workerData } = require('worker_threads');\n\nif (isMainThread) {\n const worker = new Worker(__filename, { workerData: 'Hello, world!' });\n} else {\n console.log(workerData); // Prints 'Hello, world!'.\n}\n</code></pre>"
}
],
"methods": [
{
"textRaw": "worker.moveMessagePortToContext(port, contextifiedSandbox)",
"type": "method",
"name": "moveMessagePortToContext",
"meta": {
"added": [
"v11.13.0"
],
"changes": []
},
"signatures": [
{
"return": {
"textRaw": "Returns: {MessagePort}",
"name": "return",
"type": "MessagePort"
},
"params": [
{
"textRaw": "`port` {MessagePort} The message port which will be transferred.",
"name": "port",
"type": "MessagePort",
"desc": "The message port which will be transferred."
},
{
"textRaw": "`contextifiedSandbox` {Object} A [contextified][] object as returned by the `vm.createContext()` method.",
"name": "contextifiedSandbox",
"type": "Object",
"desc": "A [contextified][] object as returned by the `vm.createContext()` method."
}
]
}
],
"desc": "<p>Transfer a <code>MessagePort</code> to a different <a href=\"vm.html\"><code>vm</code></a> Context. The original <code>port</code>\nobject will be rendered unusable, and the returned <code>MessagePort</code> instance will\ntake its place.</p>\n<p>The returned <code>MessagePort</code> will be an object in the target context, and will\ninherit from its global <code>Object</code> class. Objects passed to the\n<a href=\"https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/onmessage\"><code>port.onmessage()</code></a> listener will also be created in the target context\nand inherit from its global <code>Object</code> class.</p>\n<p>However, the created <code>MessagePort</code> will no longer inherit from\n<a href=\"events.html\"><code>EventEmitter</code></a>, and only <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/onmessage\"><code>port.onmessage()</code></a> can be used to receive\nevents using it.</p>"
},
{
"textRaw": "worker.receiveMessageOnPort(port)",
"type": "method",
"name": "receiveMessageOnPort",
"meta": {
"added": [
"v12.3.0"
],
"changes": []
},
"signatures": [
{
"return": {
"textRaw": "Returns: {Object|undefined}",
"name": "return",
"type": "Object|undefined"
},
"params": [
{
"textRaw": "`port` {MessagePort}",
"name": "port",
"type": "MessagePort"
}
]
}
],
"desc": "<p>Receive a single message from a given <code>MessagePort</code>. If no message is available,\n<code>undefined</code> is returned, otherwise an object with a single <code>message</code> property\nthat contains the message payload, corresponding to the oldest message in the\n<code>MessagePort</code>’s queue.</p>\n<pre><code class=\"language-js\">const { MessageChannel, receiveMessageOnPort } = require('worker_threads');\nconst { port1, port2 } = new MessageChannel();\nport1.postMessage({ hello: 'world' });\n\nconsole.log(receiveMessageOnPort(port2));\n// Prints: { message: { hello: 'world' } }\nconsole.log(receiveMessageOnPort(port2));\n// Prints: undefined\n</code></pre>\n<p>When this function is used, no <code>'message'</code> event will be emitted and the\n<code>onmessage</code> listener will not be invoked.</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\"><EventEmitter></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>\n<pre><code class=\"language-js\">const { MessageChannel } = require('worker_threads');\nconst { port1, port2 } = new MessageChannel();\n\n// Prints:\n// foobar\n// closed!\nport2.on('message', (message) => console.log(message));\nport2.on('close', () => console.log('closed!'));\n\nport1.postMessage('foobar');\nport1.close();\n</code></pre>"
},
{
"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>\n<p>The <a href=\"#worker_threads_event_close\"><code>'close'</code> event</a> will be emitted on both <code>MessagePort</code> instances that\nare part of the channel.</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>.</p>\n<p>In particular, the significant differences to <code>JSON</code> are:</p>\n<ul>\n<li><code>value</code> may contain circular references.</li>\n<li><code>value</code> may contain instances of builtin JS types such as <code>RegExp</code>s,\n<code>BigInt</code>s, <code>Map</code>s, <code>Set</code>s, etc.</li>\n<li><code>value</code> may contain typed arrays, both using <code>ArrayBuffer</code>s\nand <code>SharedArrayBuffer</code>s.</li>\n<li><code>value</code> may contain <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module\"><code>WebAssembly.Module</code></a> instances.</li>\n<li><code>value</code> may not contain native (C++-backed) objects other than <code>MessagePort</code>s.</li>\n</ul>\n<pre><code class=\"language-js\">const { MessageChannel } = require('worker_threads');\nconst { port1, port2 } = new MessageChannel();\n\nport1.on('message', (message) => console.log(message));\n\nconst circularData = {};\ncircularData.foo = circularData;\n// Prints: { foo: [Circular] }\nport2.postMessage(circularData);\n</code></pre>\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<pre><code class=\"language-js\">const { MessageChannel } = require('worker_threads');\nconst { port1, port2 } = new MessageChannel();\n\nport1.on('message', (message) => console.log(message));\n\nconst uint8Array = new Uint8Array([ 1, 2, 3, 4 ]);\n// This posts a copy of `uint8Array`:\nport2.postMessage(uint8Array);\n// This does not copy data, but renders `uint8Array` unusable:\nport2.postMessage(uint8Array, [ uint8Array.buffer ]);\n\n// The memory for the `sharedUint8Array` will be accessible from both the\n// original and the copy received by `.on('message')`:\nconst sharedUint8Array = new Uint8Array(new SharedArrayBuffer(4));\nport2.postMessage(sharedUint8Array);\n\n// This transfers a freshly created message port to the receiver.\n// This can be used, for example, to create communication channels between\n// multiple `Worker` threads that are children of the same parent thread.\nconst otherChannel = new MessageChannel();\nport2.postMessage({ port: otherChannel.port1 }, [ otherChannel.port1 ]);\n</code></pre>\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>\n<p>This method exists for parity with the Web <code>MessagePort</code> API. In Node.js,\nit is only useful for ignoring messages when no event listener is present.\nNode.js also diverges in its handling of <code>.onmessage</code>. Setting it will\nautomatically call <code>.start()</code>, but unsetting it will let messages queue up\nuntil a new handler is set or the port is discarded.</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\"><EventEmitter></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 copy of the parent thread's environment variables,\nunless otherwise specified. Changes to one copy will not be visible in other\nthreads, and will not be visible to native add-ons (unless\n<a href=\"#worker_threads_worker_share_env\"><code>worker.SHARE_ENV</code></a> has been passed as the <code>env</code> option to the\n<a href=\"#worker_threads_class_worker\"><code>Worker</code></a> constructor).</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\"><code>worker.terminate()</code></a>\nbeing invoked.</li>\n<li>IPC channels from parent processes are not accessible.</li>\n<li>The <a href=\"tracing.html\"><code>trace_events</code></a> module is not supported.</li>\n<li>Native add-ons can only be loaded from multiple threads if they fulfill\n<a href=\"addons.html#addons_worker_support\">certain conditions</a>.</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()",
"type": "method",
"name": "terminate",
"meta": {
"added": [
"v10.5.0"
],
"changes": [
{
"version": "v12.5.0",
"pr-url": "https://github.com/nodejs/node/pull/28021",
"description": "This function now returns a Promise. Passing a callback is deprecated, and was useless up to this version, as the Worker was actually terminated synchronously. Terminating is now a fully asynchronous operation."
}
]
},
"signatures": [
{
"return": {
"textRaw": "Returns: {Promise}",
"name": "return",
"type": "Promise"
},
"params": []
}
],
"desc": "<p>Stop all JavaScript execution in the worker thread as soon as possible.\nReturns a Promise for the exit code that is fulfilled when the\n<a href=\"#worker_threads_event_exit\"><code>'exit'</code> event</a> is emitted.</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>.\nThis value is unique for each <code>Worker</code> instance inside a single process.</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": "`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`.",
"name": "env",
"type": "Object",
"default": "`process.env`",
"desc": "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."
},
{
"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": "`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 inherited from the parent thread.",
"name": "execArgv",
"type": "string[]",
"desc": "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 inherited from the parent thread."
},
{
"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."
},
{
"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)."
}
],
"optional": true
}
]
}
]
}
],
"type": "module",
"displayName": "Worker Threads"
}
]
}