1 | /**
|
2 | * The `worker_threads` module enables the use of threads that execute JavaScript
|
3 | * in parallel. To access it:
|
4 | *
|
5 | * ```js
|
6 | * const worker = require('worker_threads');
|
7 | * ```
|
8 | *
|
9 | * Workers (threads) are useful for performing CPU-intensive JavaScript operations.
|
10 | * They do not help much with I/O-intensive work. The Node.js built-in
|
11 | * asynchronous I/O operations are more efficient than Workers can be.
|
12 | *
|
13 | * Unlike `child_process` or `cluster`, `worker_threads` can share memory. They do
|
14 | * so by transferring `ArrayBuffer` instances or sharing `SharedArrayBuffer`instances.
|
15 | *
|
16 | * ```js
|
17 | * const {
|
18 | * Worker, isMainThread, parentPort, workerData
|
19 | * } = require('worker_threads');
|
20 | *
|
21 | * if (isMainThread) {
|
22 | * module.exports = function parseJSAsync(script) {
|
23 | * return new Promise((resolve, reject) => {
|
24 | * const worker = new Worker(__filename, {
|
25 | * workerData: script
|
26 | * });
|
27 | * worker.on('message', resolve);
|
28 | * worker.on('error', reject);
|
29 | * worker.on('exit', (code) => {
|
30 | * if (code !== 0)
|
31 | * reject(new Error(`Worker stopped with exit code ${code}`));
|
32 | * });
|
33 | * });
|
34 | * };
|
35 | * } else {
|
36 | * const { parse } = require('some-js-parsing-library');
|
37 | * const script = workerData;
|
38 | * parentPort.postMessage(parse(script));
|
39 | * }
|
40 | * ```
|
41 | *
|
42 | * The above example spawns a Worker thread for each `parse()` call. In actual
|
43 | * practice, use a pool of Workers for these kinds of tasks. Otherwise, the
|
44 | * overhead of creating Workers would likely exceed their benefit.
|
45 | *
|
46 | * When implementing a worker pool, use the `AsyncResource` API to inform
|
47 | * diagnostic tools (e.g. to provide asynchronous stack traces) about the
|
48 | * correlation between tasks and their outcomes. See `"Using AsyncResource for a Worker thread pool"` in the `async_hooks` documentation for an example implementation.
|
49 | *
|
50 | * Worker threads inherit non-process-specific options by default. Refer to `Worker constructor options` to know how to customize worker thread options,
|
51 | * specifically `argv` and `execArgv` options.
|
52 | * @see [source](https://github.com/nodejs/node/blob/v17.0.0/lib/worker_threads.js)
|
53 | */
|
54 | declare module 'worker_threads' {
|
55 | import { Blob } from 'node:buffer';
|
56 | import { Context } from 'node:vm';
|
57 | import { EventEmitter } from 'node:events';
|
58 | import { EventLoopUtilityFunction } from 'node:perf_hooks';
|
59 | import { FileHandle } from 'node:fs/promises';
|
60 | import { Readable, Writable } from 'node:stream';
|
61 | import { URL } from 'node:url';
|
62 | import { X509Certificate } from 'node:crypto';
|
63 | const isMainThread: boolean;
|
64 | const parentPort: null | MessagePort;
|
65 | const resourceLimits: ResourceLimits;
|
66 | const SHARE_ENV: unique symbol;
|
67 | const threadId: number;
|
68 | const workerData: any;
|
69 | /**
|
70 | * Instances of the `worker.MessageChannel` class represent an asynchronous,
|
71 | * two-way communications channel.
|
72 | * The `MessageChannel` has no methods of its own. `new MessageChannel()`yields an object with `port1` and `port2` properties, which refer to linked `MessagePort` instances.
|
73 | *
|
74 | * ```js
|
75 | * const { MessageChannel } = require('worker_threads');
|
76 | *
|
77 | * const { port1, port2 } = new MessageChannel();
|
78 | * port1.on('message', (message) => console.log('received', message));
|
79 | * port2.postMessage({ foo: 'bar' });
|
80 | * // Prints: received { foo: 'bar' } from the `port1.on('message')` listener
|
81 | * ```
|
82 | * @since v10.5.0
|
83 | */
|
84 | class MessageChannel {
|
85 | readonly port1: MessagePort;
|
86 | readonly port2: MessagePort;
|
87 | }
|
88 | interface WorkerPerformance {
|
89 | eventLoopUtilization: EventLoopUtilityFunction;
|
90 | }
|
91 | type TransferListItem = ArrayBuffer | MessagePort | FileHandle | X509Certificate | Blob;
|
92 | /**
|
93 | * Instances of the `worker.MessagePort` class represent one end of an
|
94 | * asynchronous, two-way communications channel. It can be used to transfer
|
95 | * structured data, memory regions and other `MessagePort`s between different `Worker` s.
|
96 | *
|
97 | * This implementation matches [browser `MessagePort`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort) s.
|
98 | * @since v10.5.0
|
99 | */
|
100 | class MessagePort extends EventEmitter {
|
101 | /**
|
102 | * Disables further sending of messages on either side of the connection.
|
103 | * This method can be called when no further communication will happen over this`MessagePort`.
|
104 | *
|
105 | * The `'close' event` is emitted on both `MessagePort` instances that
|
106 | * are part of the channel.
|
107 | * @since v10.5.0
|
108 | */
|
109 | close(): void;
|
110 | /**
|
111 | * Sends a JavaScript value to the receiving side of this channel.`value` is transferred in a way which is compatible with
|
112 | * the [HTML structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
|
113 | *
|
114 | * In particular, the significant differences to `JSON` are:
|
115 | *
|
116 | * * `value` may contain circular references.
|
117 | * * `value` may contain instances of builtin JS types such as `RegExp`s,`BigInt`s, `Map`s, `Set`s, etc.
|
118 | * * `value` may contain typed arrays, both using `ArrayBuffer`s
|
119 | * and `SharedArrayBuffer`s.
|
120 | * * `value` may contain [`WebAssembly.Module`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module) instances.
|
121 | * * `value` may not contain native (C++-backed) objects other than:
|
122 | *
|
123 | * ```js
|
124 | * const { MessageChannel } = require('worker_threads');
|
125 | * const { port1, port2 } = new MessageChannel();
|
126 | *
|
127 | * port1.on('message', (message) => console.log(message));
|
128 | *
|
129 | * const circularData = {};
|
130 | * circularData.foo = circularData;
|
131 | * // Prints: { foo: [Circular] }
|
132 | * port2.postMessage(circularData);
|
133 | * ```
|
134 | *
|
135 | * `transferList` may be a list of [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), `MessagePort` and `FileHandle` objects.
|
136 | * After transferring, they are not usable on the sending side of the channel
|
137 | * anymore (even if they are not contained in `value`). Unlike with `child processes`, transferring handles such as network sockets is currently
|
138 | * not supported.
|
139 | *
|
140 | * If `value` contains [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) instances, those are accessible
|
141 | * from either thread. They cannot be listed in `transferList`.
|
142 | *
|
143 | * `value` may still contain `ArrayBuffer` instances that are not in`transferList`; in that case, the underlying memory is copied rather than moved.
|
144 | *
|
145 | * ```js
|
146 | * const { MessageChannel } = require('worker_threads');
|
147 | * const { port1, port2 } = new MessageChannel();
|
148 | *
|
149 | * port1.on('message', (message) => console.log(message));
|
150 | *
|
151 | * const uint8Array = new Uint8Array([ 1, 2, 3, 4 ]);
|
152 | * // This posts a copy of `uint8Array`:
|
153 | * port2.postMessage(uint8Array);
|
154 | * // This does not copy data, but renders `uint8Array` unusable:
|
155 | * port2.postMessage(uint8Array, [ uint8Array.buffer ]);
|
156 | *
|
157 | * // The memory for the `sharedUint8Array` is accessible from both the
|
158 | * // original and the copy received by `.on('message')`:
|
159 | * const sharedUint8Array = new Uint8Array(new SharedArrayBuffer(4));
|
160 | * port2.postMessage(sharedUint8Array);
|
161 | *
|
162 | * // This transfers a freshly created message port to the receiver.
|
163 | * // This can be used, for example, to create communication channels between
|
164 | * // multiple `Worker` threads that are children of the same parent thread.
|
165 | * const otherChannel = new MessageChannel();
|
166 | * port2.postMessage({ port: otherChannel.port1 }, [ otherChannel.port1 ]);
|
167 | * ```
|
168 | *
|
169 | * The message object is cloned immediately, and can be modified after
|
170 | * posting without having side effects.
|
171 | *
|
172 | * For more information on the serialization and deserialization mechanisms
|
173 | * behind this API, see the `serialization API of the v8 module`.
|
174 | * @since v10.5.0
|
175 | */
|
176 | postMessage(value: any, transferList?: ReadonlyArray<TransferListItem>): void;
|
177 | /**
|
178 | * 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
|
179 | * behavior). If the port is `ref()`ed, calling `ref()` again has no effect.
|
180 | *
|
181 | * If listeners are attached or removed using `.on('message')`, the port
|
182 | * is `ref()`ed and `unref()`ed automatically depending on whether
|
183 | * listeners for the event exist.
|
184 | * @since v10.5.0
|
185 | */
|
186 | ref(): void;
|
187 | /**
|
188 | * Calling `unref()` on a port allows the thread to exit if this is the only
|
189 | * active handle in the event system. If the port is already `unref()`ed calling`unref()` again has no effect.
|
190 | *
|
191 | * If listeners are attached or removed using `.on('message')`, the port is`ref()`ed and `unref()`ed automatically depending on whether
|
192 | * listeners for the event exist.
|
193 | * @since v10.5.0
|
194 | */
|
195 | unref(): void;
|
196 | /**
|
197 | * Starts receiving messages on this `MessagePort`. When using this port
|
198 | * as an event emitter, this is called automatically once `'message'`listeners are attached.
|
199 | *
|
200 | * This method exists for parity with the Web `MessagePort` API. In Node.js,
|
201 | * it is only useful for ignoring messages when no event listener is present.
|
202 | * Node.js also diverges in its handling of `.onmessage`. Setting it
|
203 | * automatically calls `.start()`, but unsetting it lets messages queue up
|
204 | * until a new handler is set or the port is discarded.
|
205 | * @since v10.5.0
|
206 | */
|
207 | start(): void;
|
208 | addListener(event: 'close', listener: () => void): this;
|
209 | addListener(event: 'message', listener: (value: any) => void): this;
|
210 | addListener(event: 'messageerror', listener: (error: Error) => void): this;
|
211 | addListener(event: string | symbol, listener: (...args: any[]) => void): this;
|
212 | emit(event: 'close'): boolean;
|
213 | emit(event: 'message', value: any): boolean;
|
214 | emit(event: 'messageerror', error: Error): boolean;
|
215 | emit(event: string | symbol, ...args: any[]): boolean;
|
216 | on(event: 'close', listener: () => void): this;
|
217 | on(event: 'message', listener: (value: any) => void): this;
|
218 | on(event: 'messageerror', listener: (error: Error) => void): this;
|
219 | on(event: string | symbol, listener: (...args: any[]) => void): this;
|
220 | once(event: 'close', listener: () => void): this;
|
221 | once(event: 'message', listener: (value: any) => void): this;
|
222 | once(event: 'messageerror', listener: (error: Error) => void): this;
|
223 | once(event: string | symbol, listener: (...args: any[]) => void): this;
|
224 | prependListener(event: 'close', listener: () => void): this;
|
225 | prependListener(event: 'message', listener: (value: any) => void): this;
|
226 | prependListener(event: 'messageerror', listener: (error: Error) => void): this;
|
227 | prependListener(event: string | symbol, listener: (...args: any[]) => void): this;
|
228 | prependOnceListener(event: 'close', listener: () => void): this;
|
229 | prependOnceListener(event: 'message', listener: (value: any) => void): this;
|
230 | prependOnceListener(event: 'messageerror', listener: (error: Error) => void): this;
|
231 | prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
|
232 | removeListener(event: 'close', listener: () => void): this;
|
233 | removeListener(event: 'message', listener: (value: any) => void): this;
|
234 | removeListener(event: 'messageerror', listener: (error: Error) => void): this;
|
235 | removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
|
236 | off(event: 'close', listener: () => void): this;
|
237 | off(event: 'message', listener: (value: any) => void): this;
|
238 | off(event: 'messageerror', listener: (error: Error) => void): this;
|
239 | off(event: string | symbol, listener: (...args: any[]) => void): this;
|
240 | }
|
241 | interface WorkerOptions {
|
242 | /**
|
243 | * List of arguments which would be stringified and appended to
|
244 | * `process.argv` in the worker. This is mostly similar to the `workerData`
|
245 | * but the values will be available on the global `process.argv` as if they
|
246 | * were passed as CLI options to the script.
|
247 | */
|
248 | argv?: any[] | undefined;
|
249 | env?: NodeJS.Dict<string> | typeof SHARE_ENV | undefined;
|
250 | eval?: boolean | undefined;
|
251 | workerData?: any;
|
252 | stdin?: boolean | undefined;
|
253 | stdout?: boolean | undefined;
|
254 | stderr?: boolean | undefined;
|
255 | execArgv?: string[] | undefined;
|
256 | resourceLimits?: ResourceLimits | undefined;
|
257 | /**
|
258 | * Additional data to send in the first worker message.
|
259 | */
|
260 | transferList?: TransferListItem[] | undefined;
|
261 | /**
|
262 | * @default true
|
263 | */
|
264 | trackUnmanagedFds?: boolean | undefined;
|
265 | }
|
266 | interface ResourceLimits {
|
267 | /**
|
268 | * The maximum size of a heap space for recently created objects.
|
269 | */
|
270 | maxYoungGenerationSizeMb?: number | undefined;
|
271 | /**
|
272 | * The maximum size of the main heap in MB.
|
273 | */
|
274 | maxOldGenerationSizeMb?: number | undefined;
|
275 | /**
|
276 | * The size of a pre-allocated memory range used for generated code.
|
277 | */
|
278 | codeRangeSizeMb?: number | undefined;
|
279 | /**
|
280 | * The default maximum stack size for the thread. Small values may lead to unusable Worker instances.
|
281 | * @default 4
|
282 | */
|
283 | stackSizeMb?: number | undefined;
|
284 | }
|
285 | /**
|
286 | * The `Worker` class represents an independent JavaScript execution thread.
|
287 | * Most Node.js APIs are available inside of it.
|
288 | *
|
289 | * Notable differences inside a Worker environment are:
|
290 | *
|
291 | * * The `process.stdin`, `process.stdout` and `process.stderr` may be redirected by the parent thread.
|
292 | * * The `require('worker_threads').isMainThread` property is set to `false`.
|
293 | * * The `require('worker_threads').parentPort` message port is available.
|
294 | * * `process.exit()` does not stop the whole program, just the single thread,
|
295 | * and `process.abort()` is not available.
|
296 | * * `process.chdir()` and `process` methods that set group or user ids
|
297 | * are not available.
|
298 | * * `process.env` is a copy of the parent thread's environment variables,
|
299 | * unless otherwise specified. Changes to one copy are not visible in other
|
300 | * threads, and are not visible to native add-ons (unless `worker.SHARE_ENV` is passed as the `env` option to the `Worker` constructor).
|
301 | * * `process.title` cannot be modified.
|
302 | * * Signals are not delivered through `process.on('...')`.
|
303 | * * Execution may stop at any point as a result of `worker.terminate()` being invoked.
|
304 | * * IPC channels from parent processes are not accessible.
|
305 | * * The `trace_events` module is not supported.
|
306 | * * Native add-ons can only be loaded from multiple threads if they fulfill `certain conditions`.
|
307 | *
|
308 | * Creating `Worker` instances inside of other `Worker`s is possible.
|
309 | *
|
310 | * Like [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) and the `cluster module`, two-way communication can be
|
311 | * achieved through inter-thread message passing. Internally, a `Worker` has a
|
312 | * built-in pair of `MessagePort` s that are already associated with each other
|
313 | * when the `Worker` is created. While the `MessagePort` object on the parent side
|
314 | * is not directly exposed, its functionalities are exposed through `worker.postMessage()` and the `worker.on('message')` event
|
315 | * on the `Worker` object for the parent thread.
|
316 | *
|
317 | * To create custom messaging channels (which is encouraged over using the default
|
318 | * global channel because it facilitates separation of concerns), users can create
|
319 | * a `MessageChannel` object on either thread and pass one of the`MessagePort`s on that `MessageChannel` to the other thread through a
|
320 | * pre-existing channel, such as the global one.
|
321 | *
|
322 | * See `port.postMessage()` for more information on how messages are passed,
|
323 | * and what kind of JavaScript values can be successfully transported through
|
324 | * the thread barrier.
|
325 | *
|
326 | * ```js
|
327 | * const assert = require('assert');
|
328 | * const {
|
329 | * Worker, MessageChannel, MessagePort, isMainThread, parentPort
|
330 | * } = require('worker_threads');
|
331 | * if (isMainThread) {
|
332 | * const worker = new Worker(__filename);
|
333 | * const subChannel = new MessageChannel();
|
334 | * worker.postMessage({ hereIsYourPort: subChannel.port1 }, [subChannel.port1]);
|
335 | * subChannel.port2.on('message', (value) => {
|
336 | * console.log('received:', value);
|
337 | * });
|
338 | * } else {
|
339 | * parentPort.once('message', (value) => {
|
340 | * assert(value.hereIsYourPort instanceof MessagePort);
|
341 | * value.hereIsYourPort.postMessage('the worker is sending this');
|
342 | * value.hereIsYourPort.close();
|
343 | * });
|
344 | * }
|
345 | * ```
|
346 | * @since v10.5.0
|
347 | */
|
348 | class Worker extends EventEmitter {
|
349 | /**
|
350 | * If `stdin: true` was passed to the `Worker` constructor, this is a
|
351 | * writable stream. The data written to this stream will be made available in
|
352 | * the worker thread as `process.stdin`.
|
353 | * @since v10.5.0
|
354 | */
|
355 | readonly stdin: Writable | null;
|
356 | /**
|
357 | * 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 is piped to the
|
358 | * parent thread's `process.stdout` stream.
|
359 | * @since v10.5.0
|
360 | */
|
361 | readonly stdout: Readable;
|
362 | /**
|
363 | * 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 is piped to the
|
364 | * parent thread's `process.stderr` stream.
|
365 | * @since v10.5.0
|
366 | */
|
367 | readonly stderr: Readable;
|
368 | /**
|
369 | * An integer identifier for the referenced thread. Inside the worker thread,
|
370 | * it is available as `require('worker_threads').threadId`.
|
371 | * This value is unique for each `Worker` instance inside a single process.
|
372 | * @since v10.5.0
|
373 | */
|
374 | readonly threadId: number;
|
375 | /**
|
376 | * Provides the set of JS engine resource constraints for this Worker thread.
|
377 | * If the `resourceLimits` option was passed to the `Worker` constructor,
|
378 | * this matches its values.
|
379 | *
|
380 | * If the worker has stopped, the return value is an empty object.
|
381 | * @since v13.2.0, v12.16.0
|
382 | */
|
383 | readonly resourceLimits?: ResourceLimits | undefined;
|
384 | /**
|
385 | * An object that can be used to query performance information from a worker
|
386 | * instance. Similar to `perf_hooks.performance`.
|
387 | * @since v15.1.0, v14.17.0, v12.22.0
|
388 | */
|
389 | readonly performance: WorkerPerformance;
|
390 | /**
|
391 | * @param filename The path to the Worker’s main script or module.
|
392 | * Must be either an absolute path or a relative path (i.e. relative to the current working directory) starting with ./ or ../,
|
393 | * or a WHATWG URL object using file: protocol. If options.eval is true, this is a string containing JavaScript code rather than a path.
|
394 | */
|
395 | constructor(filename: string | URL, options?: WorkerOptions);
|
396 | /**
|
397 | * Send a message to the worker that is received via `require('worker_threads').parentPort.on('message')`.
|
398 | * See `port.postMessage()` for more details.
|
399 | * @since v10.5.0
|
400 | */
|
401 | postMessage(value: any, transferList?: ReadonlyArray<TransferListItem>): void;
|
402 | /**
|
403 | * 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
|
404 | * behavior). If the worker is `ref()`ed, calling `ref()` again has
|
405 | * no effect.
|
406 | * @since v10.5.0
|
407 | */
|
408 | ref(): void;
|
409 | /**
|
410 | * Calling `unref()` on a worker allows the thread to exit if this is the only
|
411 | * active handle in the event system. If the worker is already `unref()`ed calling`unref()` again has no effect.
|
412 | * @since v10.5.0
|
413 | */
|
414 | unref(): void;
|
415 | /**
|
416 | * Stop all JavaScript execution in the worker thread as soon as possible.
|
417 | * Returns a Promise for the exit code that is fulfilled when the `'exit' event` is emitted.
|
418 | * @since v10.5.0
|
419 | */
|
420 | terminate(): Promise<number>;
|
421 | /**
|
422 | * Returns a readable stream for a V8 snapshot of the current state of the Worker.
|
423 | * See `v8.getHeapSnapshot()` for more details.
|
424 | *
|
425 | * If the Worker thread is no longer running, which may occur before the `'exit' event` is emitted, the returned `Promise` is rejected
|
426 | * immediately with an `ERR_WORKER_NOT_RUNNING` error.
|
427 | * @since v13.9.0, v12.17.0
|
428 | * @return A promise for a Readable Stream containing a V8 heap snapshot
|
429 | */
|
430 | getHeapSnapshot(): Promise<Readable>;
|
431 | addListener(event: 'error', listener: (err: Error) => void): this;
|
432 | addListener(event: 'exit', listener: (exitCode: number) => void): this;
|
433 | addListener(event: 'message', listener: (value: any) => void): this;
|
434 | addListener(event: 'messageerror', listener: (error: Error) => void): this;
|
435 | addListener(event: 'online', listener: () => void): this;
|
436 | addListener(event: string | symbol, listener: (...args: any[]) => void): this;
|
437 | emit(event: 'error', err: Error): boolean;
|
438 | emit(event: 'exit', exitCode: number): boolean;
|
439 | emit(event: 'message', value: any): boolean;
|
440 | emit(event: 'messageerror', error: Error): boolean;
|
441 | emit(event: 'online'): boolean;
|
442 | emit(event: string | symbol, ...args: any[]): boolean;
|
443 | on(event: 'error', listener: (err: Error) => void): this;
|
444 | on(event: 'exit', listener: (exitCode: number) => void): this;
|
445 | on(event: 'message', listener: (value: any) => void): this;
|
446 | on(event: 'messageerror', listener: (error: Error) => void): this;
|
447 | on(event: 'online', listener: () => void): this;
|
448 | on(event: string | symbol, listener: (...args: any[]) => void): this;
|
449 | once(event: 'error', listener: (err: Error) => void): this;
|
450 | once(event: 'exit', listener: (exitCode: number) => void): this;
|
451 | once(event: 'message', listener: (value: any) => void): this;
|
452 | once(event: 'messageerror', listener: (error: Error) => void): this;
|
453 | once(event: 'online', listener: () => void): this;
|
454 | once(event: string | symbol, listener: (...args: any[]) => void): this;
|
455 | prependListener(event: 'error', listener: (err: Error) => void): this;
|
456 | prependListener(event: 'exit', listener: (exitCode: number) => void): this;
|
457 | prependListener(event: 'message', listener: (value: any) => void): this;
|
458 | prependListener(event: 'messageerror', listener: (error: Error) => void): this;
|
459 | prependListener(event: 'online', listener: () => void): this;
|
460 | prependListener(event: string | symbol, listener: (...args: any[]) => void): this;
|
461 | prependOnceListener(event: 'error', listener: (err: Error) => void): this;
|
462 | prependOnceListener(event: 'exit', listener: (exitCode: number) => void): this;
|
463 | prependOnceListener(event: 'message', listener: (value: any) => void): this;
|
464 | prependOnceListener(event: 'messageerror', listener: (error: Error) => void): this;
|
465 | prependOnceListener(event: 'online', listener: () => void): this;
|
466 | prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
|
467 | removeListener(event: 'error', listener: (err: Error) => void): this;
|
468 | removeListener(event: 'exit', listener: (exitCode: number) => void): this;
|
469 | removeListener(event: 'message', listener: (value: any) => void): this;
|
470 | removeListener(event: 'messageerror', listener: (error: Error) => void): this;
|
471 | removeListener(event: 'online', listener: () => void): this;
|
472 | removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
|
473 | off(event: 'error', listener: (err: Error) => void): this;
|
474 | off(event: 'exit', listener: (exitCode: number) => void): this;
|
475 | off(event: 'message', listener: (value: any) => void): this;
|
476 | off(event: 'messageerror', listener: (error: Error) => void): this;
|
477 | off(event: 'online', listener: () => void): this;
|
478 | off(event: string | symbol, listener: (...args: any[]) => void): this;
|
479 | }
|
480 | interface BroadcastChannel extends NodeJS.RefCounted {}
|
481 | /**
|
482 | * Instances of `BroadcastChannel` allow asynchronous one-to-many communication
|
483 | * with all other `BroadcastChannel` instances bound to the same channel name.
|
484 | *
|
485 | * ```js
|
486 | * 'use strict';
|
487 | *
|
488 | * const {
|
489 | * isMainThread,
|
490 | * BroadcastChannel,
|
491 | * Worker
|
492 | * } = require('worker_threads');
|
493 | *
|
494 | * const bc = new BroadcastChannel('hello');
|
495 | *
|
496 | * if (isMainThread) {
|
497 | * let c = 0;
|
498 | * bc.onmessage = (event) => {
|
499 | * console.log(event.data);
|
500 | * if (++c === 10) bc.close();
|
501 | * };
|
502 | * for (let n = 0; n < 10; n++)
|
503 | * new Worker(__filename);
|
504 | * } else {
|
505 | * bc.postMessage('hello from every worker');
|
506 | * bc.close();
|
507 | * }
|
508 | * ```
|
509 | * @since v15.4.0
|
510 | * @experimental
|
511 | */
|
512 | class BroadcastChannel {
|
513 | readonly name: string;
|
514 | /**
|
515 | * Invoked with a single \`MessageEvent\` argument when a message is received.
|
516 | * @since v15.4.0
|
517 | */
|
518 | onmessage: (message: unknown) => void;
|
519 | /**
|
520 | * Invoked with a received message cannot be deserialized.
|
521 | * @since v15.4.0
|
522 | */
|
523 | onmessageerror: (message: unknown) => void;
|
524 | constructor(name: string);
|
525 | /**
|
526 | * Closes the `BroadcastChannel` connection.
|
527 | * @since v15.4.0
|
528 | */
|
529 | close(): void;
|
530 | /**
|
531 | * @since v15.4.0
|
532 | * @param message Any cloneable JavaScript value.
|
533 | */
|
534 | postMessage(message: unknown): void;
|
535 | }
|
536 | /**
|
537 | * Mark an object as not transferable. If `object` occurs in the transfer list of
|
538 | * a `port.postMessage()` call, it is ignored.
|
539 | *
|
540 | * In particular, this makes sense for objects that can be cloned, rather than
|
541 | * transferred, and which are used by other objects on the sending side.
|
542 | * For example, Node.js marks the `ArrayBuffer`s it uses for its `Buffer pool` with this.
|
543 | *
|
544 | * This operation cannot be undone.
|
545 | *
|
546 | * ```js
|
547 | * const { MessageChannel, markAsUntransferable } = require('worker_threads');
|
548 | *
|
549 | * const pooledBuffer = new ArrayBuffer(8);
|
550 | * const typedArray1 = new Uint8Array(pooledBuffer);
|
551 | * const typedArray2 = new Float64Array(pooledBuffer);
|
552 | *
|
553 | * markAsUntransferable(pooledBuffer);
|
554 | *
|
555 | * const { port1 } = new MessageChannel();
|
556 | * port1.postMessage(typedArray1, [ typedArray1.buffer ]);
|
557 | *
|
558 | * // The following line prints the contents of typedArray1 -- it still owns
|
559 | * // its memory and has been cloned, not transferred. Without
|
560 | * // `markAsUntransferable()`, this would print an empty Uint8Array.
|
561 | * // typedArray2 is intact as well.
|
562 | * console.log(typedArray1);
|
563 | * console.log(typedArray2);
|
564 | * ```
|
565 | *
|
566 | * There is no equivalent to this API in browsers.
|
567 | * @since v14.5.0, v12.19.0
|
568 | */
|
569 | function markAsUntransferable(object: object): void;
|
570 | /**
|
571 | * Transfer a `MessagePort` to a different `vm` Context. The original `port`object is rendered unusable, and the returned `MessagePort` instance
|
572 | * takes its place.
|
573 | *
|
574 | * The returned `MessagePort` is an object in the target context and
|
575 | * inherits from its global `Object` class. Objects passed to the [`port.onmessage()`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/onmessage) listener are also created in the
|
576 | * target context
|
577 | * and inherit from its global `Object` class.
|
578 | *
|
579 | * However, the created `MessagePort` no longer inherits from [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), and only
|
580 | * [`port.onmessage()`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/onmessage) can be used to receive
|
581 | * events using it.
|
582 | * @since v11.13.0
|
583 | * @param port The message port to transfer.
|
584 | * @param contextifiedSandbox A `contextified` object as returned by the `vm.createContext()` method.
|
585 | */
|
586 | function moveMessagePortToContext(port: MessagePort, contextifiedSandbox: Context): MessagePort;
|
587 | /**
|
588 | * Receive a single message from a given `MessagePort`. If no message is available,`undefined` is returned, otherwise an object with a single `message` property
|
589 | * that contains the message payload, corresponding to the oldest message in the`MessagePort`’s queue.
|
590 | *
|
591 | * ```js
|
592 | * const { MessageChannel, receiveMessageOnPort } = require('worker_threads');
|
593 | * const { port1, port2 } = new MessageChannel();
|
594 | * port1.postMessage({ hello: 'world' });
|
595 | *
|
596 | * console.log(receiveMessageOnPort(port2));
|
597 | * // Prints: { message: { hello: 'world' } }
|
598 | * console.log(receiveMessageOnPort(port2));
|
599 | * // Prints: undefined
|
600 | * ```
|
601 | *
|
602 | * When this function is used, no `'message'` event is emitted and the`onmessage` listener is not invoked.
|
603 | * @since v12.3.0
|
604 | */
|
605 | function receiveMessageOnPort(port: MessagePort):
|
606 | | {
|
607 | message: any;
|
608 | }
|
609 | | undefined;
|
610 | type Serializable = string | object | number | boolean | bigint;
|
611 | /**
|
612 | * Within a worker thread, `worker.getEnvironmentData()` returns a clone
|
613 | * of data passed to the spawning thread's `worker.setEnvironmentData()`.
|
614 | * Every new `Worker` receives its own copy of the environment data
|
615 | * automatically.
|
616 | *
|
617 | * ```js
|
618 | * const {
|
619 | * Worker,
|
620 | * isMainThread,
|
621 | * setEnvironmentData,
|
622 | * getEnvironmentData,
|
623 | * } = require('worker_threads');
|
624 | *
|
625 | * if (isMainThread) {
|
626 | * setEnvironmentData('Hello', 'World!');
|
627 | * const worker = new Worker(__filename);
|
628 | * } else {
|
629 | * console.log(getEnvironmentData('Hello')); // Prints 'World!'.
|
630 | * }
|
631 | * ```
|
632 | * @since v15.12.0, v14.18.0
|
633 | * @experimental
|
634 | * @param key Any arbitrary, cloneable JavaScript value that can be used as a {Map} key.
|
635 | */
|
636 | function getEnvironmentData(key: Serializable): Serializable;
|
637 | /**
|
638 | * The `worker.setEnvironmentData()` API sets the content of`worker.getEnvironmentData()` in the current thread and all new `Worker`instances spawned from the current context.
|
639 | * @since v15.12.0, v14.18.0
|
640 | * @experimental
|
641 | * @param key Any arbitrary, cloneable JavaScript value that can be used as a {Map} key.
|
642 | * @param value 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
|
643 | * for the `key` will be deleted.
|
644 | */
|
645 | function setEnvironmentData(key: Serializable, value: Serializable): void;
|
646 | }
|
647 | declare module 'node:worker_threads' {
|
648 | export * from 'worker_threads';
|
649 | }
|
650 |
|
\ | No newline at end of file |