worker: rename to worker_threads

PR-URL: #20876
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: Shingo Inoue <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Tiancheng "Timothy" Gu <[email protected]>
Reviewed-By: John-David Dalton <[email protected]>
Reviewed-By: Gus Caplan <[email protected]>

Author: addaleax

benchmark/fixtures/echo.worker.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { parentPort } = require('worker');
+const { parentPort } = require('worker_threads');
 
 parentPort.on('message', (msg) => {
   parentPort.postMessage(msg);

benchmark/worker/echo.js

@@ -12,7 +12,7 @@ const bench = common.createBenchmark(main, {
 const workerPath = path.resolve(__dirname, '..', 'fixtures', 'echo.worker.js');
 
 function main(conf) {
-  const { Worker } = require('worker');
+  const { Worker } = require('worker_threads');
 
   const n = +conf.n;
   const workers = +conf.workers;

doc/api/_toc.md

@@ -53,7 +53,7 @@
 * [Utilities](util.html)
 * [V8](v8.html)
 * [VM](vm.html)
-* [Worker](worker.html)
+* [Worker Threads](worker_threads.html)
 * [ZLIB](zlib.html)
 
 <div class="line"></div>

doc/api/all.md

@@ -46,5 +46,5 @@
 @include util
 @include v8
 @include vm
-@include worker
+@include worker_threads
 @include zlib

doc/api/async_hooks.md

@@ -728,4 +728,4 @@ never be called.
 [Hook Callbacks]: #async_hooks_hook_callbacks
 [PromiseHooks]: https://docs.google.com/document/d/1rda3yKGHimKIhg5YeoAmCOtyURgsbTH_qaYR79FELlk
 [promise execution tracking]: #async_hooks_promise_execution_tracking
-[`Worker`]: worker.html#worker_worker
+[`Worker`]: worker_threads.html#worker_threads_class_worker

doc/api/process.md

@@ -2018,7 +2018,7 @@ cases:
 [`ChildProcess`]: child_process.html#child_process_class_childprocess
 [`Error`]: errors.html#errors_class_error
 [`EventEmitter`]: events.html#events_class_eventemitter
-[`Worker`]: worker.html#worker_worker
+[`Worker`]: worker_threads.html#worker_threads_class_worker
 [`console.error()`]: console.html#console_console_error_data_args
 [`console.log()`]: console.html#console_console_log_data_args
 [`domain`]: domain.html

doc/api/worker.md renamed to doc/api/worker_threads.md

@@ -1,4 +1,4 @@
-# Worker
+# Worker Threads
 
 <!--introduced_in=REPLACEME-->
 
@@ -9,7 +9,7 @@ on independent threads, and to create message channels between them. It
 can be accessed using:
 
 ```js
-const worker = require('worker');
+const worker = require('worker_threads');
 ```
 
 Workers are useful for performing CPU-intensive JavaScript operations; do not
@@ -23,7 +23,9 @@ share memory efficiently by transferring `ArrayBuffer` instances or sharing
 ## Example
 
 ```js
-const { Worker, isMainThread, parentPort, workerData } = require('worker');
+const {
+  Worker, isMainThread, parentPort, workerData
+} = require('worker_threads');
 
 if (isMainThread) {
   module.exports = async function parseJSAsync(script) {
@@ -104,7 +106,7 @@ yields an object with `port1` and `port2` properties, which refer to linked
 [`MessagePort`][] instances.
 
 ```js
-const { MessageChannel } = require('worker');
+const { MessageChannel } = require('worker_threads');
 
 const { port1, port2 } = new MessageChannel();
 port1.on('message', (message) => console.log('received', message));
@@ -241,8 +243,8 @@ Notable differences inside a Worker environment are:
 
 - The [`process.stdin`][], [`process.stdout`][] and [`process.stderr`][]
   may be redirected by the parent thread.
-- The [`require('worker').isMainThread`][] property is set to `false`.
-- The [`require('worker').parentPort`][] message port is available,
+- The [`require('worker_threads').isMainThread`][] property is set to `false`.
+- The [`require('worker_threads').parentPort`][] message port is available,
 - [`process.exit()`][] does not stop the whole program, just the single thread,
   and [`process.abort()`][] is not available.
 - [`process.chdir()`][] and `process` methods that set group or user ids
@@ -283,7 +285,9 @@ For example:
 
 ```js
 const assert = require('assert');
-const { Worker, MessageChannel, MessagePort, isMainThread } = require('worker');
+const {
+  Worker, MessageChannel, MessagePort, isMainThread
+} = require('worker_threads');
 if (isMainThread) {
   const worker = new Worker(__filename);
   const subChannel = new MessageChannel();
@@ -292,7 +296,7 @@ if (isMainThread) {
     console.log('received:', value);
   });
 } else {
-  require('worker').once('workerMessage', (value) => {
+  require('worker_threads').once('workerMessage', (value) => {
     assert(value.hereIsYourPort instanceof MessagePort);
     value.hereIsYourPort.postMessage('the worker is sending this');
     value.hereIsYourPort.close();
@@ -309,9 +313,9 @@ if (isMainThread) {
   * `eval` {boolean} If true, interpret the first argument to the constructor
     as a script that is executed once the worker is online.
   * `data` {any} Any JavaScript value that will be cloned and made
-    available as [`require('worker').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
+    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).
   * stdin {boolean} If this is set to `true`, then `worker.stdin` will
     provide a writable stream whose contents will appear as `process.stdin`
@@ -351,8 +355,8 @@ added: REPLACEME
 * `value` {any} The transmitted value
 
 The `'message'` event is emitted when the worker thread has invoked
-[`require('worker').postMessage()`][]. See the [`port.on('message')`][] event
-for more details.
+[`require('worker_threads').postMessage()`][]. See the [`port.on('message')`][]
+event for more details.
 
 ### Event: 'online'
 <!-- YAML
@@ -371,8 +375,8 @@ added: REPLACEME
 * `transferList` {Object[]}
 
 Send a message to the worker that will be received via
-[`require('worker').on('workerMessage')`][]. See [`port.postMessage()`][] for
-more details.
+[`require('worker_threads').on('workerMessage')`][].
+See [`port.postMessage()`][] for more details.
 
 ### worker.ref()
 <!-- YAML
@@ -444,7 +448,7 @@ added: REPLACEME
 * {integer}
 
 An integer identifier for the referenced thread. Inside the worker thread,
-it is available as [`require('worker').threadId`][].
+it is available as [`require('worker_threads').threadId`][].
 
 ### worker.unref()
 <!-- YAML
@@ -457,14 +461,14 @@ active handle in the event system. If the worker is already `unref()`ed calling
 
 [`Buffer`]: buffer.html
 [`EventEmitter`]: events.html
-[`MessagePort`]: #worker_class_messageport
-[`port.postMessage()`]: #worker_port_postmessage_value_transferlist
-[`Worker`]: #worker_class_worker
-[`worker.terminate()`]: #worker_worker_terminate_callback
-[`worker.postMessage()`]: #worker_worker_postmessage_value_transferlist_1
-[`worker.on('message')`]: #worker_event_message_1
-[`worker.threadId`]: #worker_worker_threadid_1
-[`port.on('message')`]: #worker_event_message
+[`MessagePort`]: #worker_threads_class_messageport
+[`port.postMessage()`]: #worker_threads_port_postmessage_value_transferlist
+[`Worker`]: #worker_threads_class_worker
+[`worker.terminate()`]: #worker_threads_worker_terminate_callback
+[`worker.postMessage()`]: #worker_threads_worker_postmessage_value_transferlist_1
+[`worker.on('message')`]: #worker_threads_event_message_1
+[`worker.threadId`]: #worker_threads_worker_threadid_1
+[`port.on('message')`]: #worker_threads_event_message
 [`process.exit()`]: process.html#process_process_exit_code
 [`process.abort()`]: process.html#process_process_abort
 [`process.chdir()`]: process.html#process_process_chdir_directory
@@ -473,11 +477,11 @@ active handle in the event system. If the worker is already `unref()`ed calling
 [`process.stderr`]: process.html#process_process_stderr
 [`process.stdout`]: process.html#process_process_stdout
 [`process.title`]: process.html#process_process_title
-[`require('worker').workerData`]: #worker_worker_workerdata
-[`require('worker').on('workerMessage')`]: #worker_event_workermessage
-[`require('worker').postMessage()`]: #worker_worker_postmessage_value_transferlist
-[`require('worker').isMainThread`]: #worker_worker_ismainthread
-[`require('worker').threadId`]: #worker_worker_threadid
+[`require('worker_threads').workerData`]: #worker_threads_worker_workerdata
+[`require('worker_threads').on('workerMessage')`]: #worker_threads_event_workermessage
+[`require('worker_threads').postMessage()`]: #worker_threads_worker_postmessage_value_transferlist
+[`require('worker_threads').isMainThread`]: #worker_threads_worker_ismainthread
+[`require('worker_threads').threadId`]: #worker_threads_worker_threadid
 [`cluster` module]: cluster.html
 [`inspector`]: inspector.html
 [v8.serdes]: v8.html#v8_serialization_api

lib/internal/bootstrap/loaders.js

@@ -195,7 +195,8 @@
 
     NativeModule.isInternal = function(id) {
       return id.startsWith('internal/') ||
-          (id === 'worker' && !process.binding('config').experimentalWorker);
+          (id === 'worker_threads' &&
+           !process.binding('config').experimentalWorker);
     };
   }
 

lib/internal/modules/cjs/helpers.js

@@ -106,7 +106,7 @@ const builtinLibs = [
 ];
 
 if (process.binding('config').experimentalWorker) {
-  builtinLibs.push('worker');
+  builtinLibs.push('worker_threads');
   builtinLibs.sort();
 }
 

lib/internal/worker.js

@@ -387,7 +387,7 @@ function setupChild(evalScript) {
   debug(`[${threadId}] is setting up worker child environment`);
   const port = getEnvMessagePort();
 
-  const publicWorker = require('worker');
+  const publicWorker = require('worker_threads');
 
   port.on('message', (message) => {
     if (message.type === 'loadScript') {

lib/worker.js renamed to lib/worker_threads.js

@@ -78,7 +78,7 @@
       'lib/util.js',
       'lib/v8.js',
       'lib/vm.js',
-      'lib/worker.js',
+      'lib/worker_threads.js',
       'lib/zlib.js',
       'lib/internal/assert.js',
       'lib/internal/async_hooks.js',

node.gyp

@@ -48,7 +48,7 @@ Object.defineProperty(exports, 'PORT', {
 
 exports.isMainThread = (() => {
   try {
-    return require('worker').isMainThread;
+    return require('worker_threads').isMainThread;
   } catch {
     // Worker module not enabled → only a single main thread exists.
     return true;

test/common/index.js

@@ -1,3 +1,3 @@
-import worker from 'worker';
+import worker from 'worker_threads';
 
 worker.parentPort.postMessage('Hello, world!');

test/fixtures/worker-script.mjs

@@ -3,14 +3,14 @@
 
 const common = require('../common');
 const assert = require('assert');
-const { Worker } = require('worker');
+const { Worker } = require('worker_threads');
 
 {
   const sharedArrayBuffer = new SharedArrayBuffer(12);
   const local = Buffer.from(sharedArrayBuffer);
 
   const w = new Worker(`
-    const { parentPort } = require('worker');
+    const { parentPort } = require('worker_threads');
     parentPort.on('message', ({ sharedArrayBuffer }) => {
       const local = Buffer.from(sharedArrayBuffer);
       local.write('world!', 6);

test/parallel/test-message-channel-sharedarraybuffer.js

@@ -2,7 +2,7 @@
 'use strict';
 const common = require('../common');
 const assert = require('assert');
-const { MessageChannel, MessagePort, Worker } = require('worker');
+const { MessageChannel, MessagePort, Worker } = require('worker_threads');
 
 {
   const channel = new MessageChannel();
@@ -29,9 +29,9 @@ const { MessageChannel, MessagePort, Worker } = require('worker');
   const channel = new MessageChannel();
 
   const w = new Worker(`
-    const { MessagePort } = require('worker');
+    const { MessagePort } = require('worker_threads');
     const assert = require('assert');
-    require('worker').parentPort.on('message', ({ port }) => {
+    require('worker_threads').parentPort.on('message', ({ port }) => {
       assert(port instanceof MessagePort);
       port.postMessage('works');
     });

test/parallel/test-message-channel.js

@@ -3,7 +3,7 @@
 const common = require('../common');
 const assert = require('assert');
 
-const { MessageChannel } = require('worker');
+const { MessageChannel } = require('worker_threads');
 
 {
   const { port1, port2 } = new MessageChannel();

test/parallel/test-message-port-arraybuffer.js

@@ -3,7 +3,7 @@
 const common = require('../common');
 const assert = require('assert');
 
-const { MessageChannel } = require('worker');
+const { MessageChannel } = require('worker_threads');
 
 {
   const { port1: basePort1, port2: basePort2 } = new MessageChannel();

test/parallel/test-message-port-message-port-transferring.js

@@ -3,7 +3,7 @@
 const common = require('../common');
 const assert = require('assert');
 
-const { MessageChannel, MessagePort } = require('worker');
+const { MessageChannel, MessagePort } = require('worker_threads');
 
 {
   const { port1, port2 } = new MessageChannel();

test/parallel/test-message-port.js

@@ -2,7 +2,7 @@
 'use strict';
 const common = require('../common');
 const assert = require('assert');
-const { Worker, isMainThread, parentPort } = require('worker');
+const { Worker, isMainThread, parentPort } = require('worker_threads');
 const { Server } = require('net');
 const fs = require('fs');
 

test/parallel/test-worker-cleanup-handles.js

@@ -1,12 +1,12 @@
 // Flags: --experimental-worker
 'use strict';
 const common = require('../common');
-const { Worker } = require('worker');
+const { Worker } = require('worker_threads');
 
 const w = new Worker(`
 const dns = require('dns');
 dns.lookup('nonexistent.org', () => {});
-require('worker').parentPort.postMessage('0');
+require('worker_threads').parentPort.postMessage('0');
 `, { eval: true });
 
 w.on('message', common.mustCall(() => {

test/parallel/test-worker-dns-terminate.js

@@ -3,7 +3,7 @@
 const common = require('../common');
 const fixtures = require('../common/fixtures');
 const assert = require('assert');
-const { Worker } = require('worker');
+const { Worker } = require('worker_threads');
 
 const w = new Worker(fixtures.path('worker-script.mjs'));
 w.on('message', common.mustCall((message) => {

test/parallel/test-worker-esmodule.js

@@ -3,7 +3,7 @@
 const common = require('../common');
 const assert = require('assert');
 const util = require('util');
-const { Worker } = require('worker');
+const { Worker } = require('worker_threads');
 
 const numWorkers = +process.env.JOBS || require('os').cpus().length;
 
@@ -13,7 +13,7 @@ function run(n, done) {
   if (n <= 0)
     return done();
   const worker = new Worker(
-    'require(\'worker\').parentPort.postMessage(2 + 2)',
+    'require(\'worker_threads\').parentPort.postMessage(2 + 2)',
     { eval: true });
   worker.on('message', common.mustCall((value) => {
     assert.strictEqual(value, 4);

test/parallel/test-worker-memory.js

@@ -1,13 +1,13 @@
 // Flags: --experimental-worker
 'use strict';
 const common = require('../common');
-const { Worker } = require('worker');
+const { Worker } = require('worker_threads');
 
 // Checks that terminating in the middle of `process.nextTick()` does not
 // Crash the process.
 
 const w = new Worker(`
-require('worker').parentPort.postMessage('0');
+require('worker_threads').parentPort.postMessage('0');
 process.nextTick(() => {
   while(1);
 });

test/parallel/test-worker-nexttick-terminate.js

@@ -5,7 +5,7 @@ const assert = require('assert');
 const fs = require('fs');
 const util = require('util');
 const { Writable } = require('stream');
-const { Worker, isMainThread } = require('worker');
+const { Worker, isMainThread } = require('worker_threads');
 
 class BufferingWritable extends Writable {
   constructor() {

test/parallel/test-worker-stdio.js

@@ -3,7 +3,7 @@
 const common = require('../common');
 const fixtures = require('../common/fixtures');
 const assert = require('assert');
-const { Worker } = require('worker');
+const { Worker } = require('worker_threads');
 
 // Do not use isMainThread so that this test itself can be run inside a Worker.
 if (!process.env.HAS_STARTED_WORKER) {