diff options
author | James M Snell <jasnell@gmail.com> | 2021-02-23 03:22:17 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2021-03-15 17:40:26 +0300 |
commit | 802b3e7cf9a5074a72bec75cf1c46758b81e04b1 (patch) | |
tree | 7a7b249e5dec88d0bc7c0688e8b4f131d4a414e3 /doc/api/worker_threads.md | |
parent | 7abdc3ecb42af70dd69460ff2a88b4b521116db5 (diff) |
worker: add setEnvironmentData/getEnvironmentData
These APIs allow arbitrary, cloneable JavaScript values to be set and
passed to all new Worker instances spawned from the current context.
It is similar to `workerData` except that environment data is set
independently of the `new Worker()` constructor, and the the value is
passed automatically to all new Workers.
This is a *partial* fix of https://github.com/nodejs/node/issues/30992
but does not implement a complete fix.
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/37486
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
Diffstat (limited to 'doc/api/worker_threads.md')
-rw-r--r-- | doc/api/worker_threads.md | 49 |
1 files changed, 49 insertions, 0 deletions
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index 7942788df58..c8fc33750ee 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -61,6 +61,38 @@ Worker threads inherit non-process-specific options by default. Refer to [`Worker constructor options`][] to know how to customize worker thread options, specifically `argv` and `execArgv` options. +## `worker.getEnvironmentData(key)` +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +* `key` {any} Any arbitrary, cloneable JavaScript value that can be used as a + {Map} key. +* Returns: {any} + +Within a worker thread, `worker.getEnvironmentData()` returns a clone +of data passed to the spawning thread's `worker.setEnvironmentData()`. +Every new `Worker` receives its own copy of the environment data +automatically. + +```js +const { + Worker, + isMainThread, + setEnvironmentData, + getEnvironmentData, +} = require('worker_threads'); + +if (isMainThread) { + setEnvironmentData('Hello', 'World!'); + const worker = new Worker(__filename); +} else { + console.log(getEnvironmentData('Hello')); // Prints 'World!'. +} +``` + ## `worker.isMainThread` <!-- YAML added: v10.5.0 @@ -246,6 +278,23 @@ new Worker('process.env.SET_IN_WORKER = "foo"', { eval: true, env: SHARE_ENV }) }); ``` +## `worker.setEnvironmentData(key[, value])` +<!--YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +* `key` {any} Any arbitrary, cloneable JavaScript value that can be used as a + {Map} key. +* `value` {any} Any arbitrary, cloneable JavaScript value that will be cloned + and passed automatically to all new `Worker` instances. If `value` is passed + as `undefined`, any previously set value for the `key` will be deleted. + +The `worker.setEnvironmentData()` API sets the content of +`worker.getEnvironmentData()` in the current thread and all new `Worker` +instances spawned from the current context. + ## `worker.threadId` <!-- YAML added: v10.5.0 |