1 import type { MessageChannel
, WorkerOptions
} from
'node:worker_threads'
2 import type { EventEmitter
} from
'node:events'
3 import type { CircularArray
} from
'../circular-array.js'
4 import type { Task
} from
'../utility-types.js'
7 * Callback invoked when the worker has started successfully.
9 * @typeParam Worker - Type of worker.
11 export type OnlineHandler
<Worker
extends IWorker
> = (this: Worker
) => void
14 * Callback invoked if the worker has received a message.
16 * @typeParam Worker - Type of worker.
18 export type MessageHandler
<Worker
extends IWorker
> = (
24 * Callback invoked if the worker raised an error.
26 * @typeParam Worker - Type of worker.
28 export type ErrorHandler
<Worker
extends IWorker
> = (
34 * Callback invoked when the worker exits successfully.
36 * @typeParam Worker - Type of worker.
38 export type ExitHandler
<Worker
extends IWorker
> = (
44 * Worker event handler.
46 * @typeParam Worker - Type of worker.
48 export type EventHandler
<Worker
extends IWorker
> =
49 | OnlineHandler
<Worker
>
50 | MessageHandler
<Worker
>
51 | ErrorHandler
<Worker
>
55 * Measurement statistics.
59 export interface MeasurementStatistics
{
61 * Measurement aggregate.
65 * Measurement minimum.
69 * Measurement maximum.
73 * Measurement average.
81 * Measurement history.
83 readonly history
: CircularArray
<number>
87 * Event loop utilization measurement statistics.
91 export interface EventLoopUtilizationMeasurementStatistics
{
92 readonly idle
: MeasurementStatistics
93 readonly active
: MeasurementStatistics
102 export interface TaskStatistics
{
104 * Number of executed tasks.
108 * Number of executing tasks.
112 * Number of queued tasks.
114 readonly queued
: number
116 * Maximum number of queued tasks.
118 readonly maxQueued
?: number
120 * Number of sequentially stolen tasks.
122 sequentiallyStolen
: number
124 * Number of stolen tasks.
128 * Number of failed tasks.
134 * Enumeration of worker types.
136 export const WorkerTypes
= Object.freeze({
144 export type WorkerType
= keyof
typeof WorkerTypes
147 * Worker information.
151 export interface WorkerInfo
{
155 readonly id
: number | undefined
159 readonly type: WorkerType
170 * This flag is set to `true` when worker node is stealing tasks from another worker node.
174 * Task function names.
176 taskFunctionNames
?: string[]
180 * Worker usage statistics.
184 export interface WorkerUsage
{
188 readonly tasks
: TaskStatistics
190 * Tasks runtime statistics.
192 readonly runTime
: MeasurementStatistics
194 * Tasks wait time statistics.
196 readonly waitTime
: MeasurementStatistics
198 * Tasks event loop utilization statistics.
200 readonly elu
: EventLoopUtilizationMeasurementStatistics
204 * Worker choice strategy data.
208 export interface StrategyData
{
209 virtualTaskEndTimestamp
?: number
215 export interface IWorker
extends EventEmitter
{
221 * Worker thread worker id.
223 readonly threadId
?: number
225 * Registers an event handler.
227 * @param event - The event.
228 * @param handler - The event handler.
230 readonly on
: (event
: string, handler
: EventHandler
<this>) => this
232 * Registers once an event handler.
234 * @param event - The event.
235 * @param handler - The event handler.
237 readonly once
: (event
: string, handler
: EventHandler
<this>) => this
239 * Calling `unref()` on a worker allows the thread to exit if this is the only
240 * active handle in the event system. If the worker is already `unref()`ed calling`unref()` again has no effect.
243 readonly unref
?: () => void
245 * Stop all JavaScript execution in the worker thread as soon as possible.
246 * Returns a Promise for the exit code that is fulfilled when the `'exit' event` is emitted.
248 readonly terminate
?: () => Promise
<number>
250 * Cluster worker disconnect.
252 readonly disconnect
?: () => void
254 * Cluster worker kill.
256 readonly kill
?: (signal
?: string) => void
260 * Worker node options.
264 export interface WorkerNodeOptions
{
265 workerOptions
?: WorkerOptions
266 env
?: Record
<string, unknown
>
267 tasksQueueBackPressureSize
: number | undefined
271 * Worker node interface.
273 * @typeParam Worker - Type of worker.
274 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
277 export interface IWorkerNode
<Worker
extends IWorker
, Data
= unknown
>
278 extends EventEmitter
{
282 readonly worker
: Worker
286 readonly info
: WorkerInfo
288 * Worker usage statistics.
290 readonly usage
: WorkerUsage
292 * Worker choice strategy data.
293 * This is used to store data that are specific to the worker choice strategy.
295 strategyData
?: StrategyData
297 * Message channel (worker thread only).
299 readonly messageChannel
?: MessageChannel
301 * Tasks queue back pressure size.
302 * This is the number of tasks that can be enqueued before the worker node has back pressure.
304 tasksQueueBackPressureSize
: number
308 * @returns The tasks queue size.
310 readonly tasksQueueSize
: () => number
314 * @param task - The task to queue.
315 * @returns The tasks queue size.
317 readonly enqueueTask
: (task
: Task
<Data
>) => number
319 * Prepends a task to the tasks queue.
321 * @param task - The task to prepend.
322 * @returns The tasks queue size.
324 readonly unshiftTask
: (task
: Task
<Data
>) => number
328 * @returns The dequeued task.
330 readonly dequeueTask
: () => Task
<Data
> | undefined
332 * Pops a task from the tasks queue.
334 * @returns The popped task.
336 readonly popTask
: () => Task
<Data
> | undefined
338 * Clears tasks queue.
340 readonly clearTasksQueue
: () => void
342 * Whether the worker node has back pressure (i.e. its tasks queue is full).
344 * @returns `true` if the worker node has back pressure, `false` otherwise.
346 readonly hasBackPressure
: () => boolean
348 * Resets usage statistics.
350 readonly resetUsage
: () => void
352 * Terminates the worker node.
354 readonly terminate
: () => Promise
<void>
356 * Registers a worker event handler.
358 * @param event - The event.
359 * @param handler - The event handler.
361 readonly registerWorkerEventHandler
: (
363 handler
: EventHandler
<Worker
>
366 * Registers once a worker event handler.
368 * @param event - The event.
369 * @param handler - The event handler.
371 readonly registerOnceWorkerEventHandler
: (
373 handler
: EventHandler
<Worker
>
376 * Gets task function worker usage statistics.
378 * @param name - The task function name.
379 * @returns The task function worker usage statistics if the task function worker usage statistics are initialized, `undefined` otherwise.
381 readonly getTaskFunctionWorkerUsage
: (name
: string) => WorkerUsage
| undefined
383 * Deletes task function worker usage statistics.
385 * @param name - The task function name.
386 * @returns `true` if the task function worker usage statistics were deleted, `false` otherwise.
388 readonly deleteTaskFunctionWorkerUsage
: (name
: string) => boolean
392 * Worker node event detail.
396 export interface WorkerNodeEventDetail
{
398 workerNodeKey
?: number