1 import type { MessageChannel
, WorkerOptions
} from
'node:worker_threads'
2 import type { EventEmitter
} from
'node:events'
3 import type { CircularArray
} from
'../circular-array'
4 import type { Task
} from
'../utility-types'
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 * Measurement statistics.
48 export interface MeasurementStatistics
{
50 * Measurement aggregate.
54 * Measurement minimum.
58 * Measurement maximum.
62 * Measurement average.
70 * Measurement history.
72 readonly history
: CircularArray
<number>
76 * Event loop utilization measurement statistics.
80 export interface EventLoopUtilizationMeasurementStatistics
{
81 readonly idle
: MeasurementStatistics
82 readonly active
: MeasurementStatistics
91 export interface TaskStatistics
{
93 * Number of executed tasks.
97 * Number of executing tasks.
101 * Number of queued tasks.
103 readonly queued
: number
105 * Maximum number of queued tasks.
107 readonly maxQueued
?: number
109 * Number of sequentially stolen tasks.
111 sequentiallyStolen
: number
113 * Number of stolen tasks.
117 * Number of failed tasks.
123 * Enumeration of worker types.
125 export const WorkerTypes
= Object.freeze({
133 export type WorkerType
= keyof
typeof WorkerTypes
136 * Worker information.
140 export interface WorkerInfo
{
144 readonly id
: number | undefined
148 readonly type: WorkerType
159 * This flag is set to `true` when worker node is stealing tasks from another worker node.
163 * Task function names.
165 taskFunctionNames
?: string[]
169 * Worker usage statistics.
173 export interface WorkerUsage
{
177 readonly tasks
: TaskStatistics
179 * Tasks runtime statistics.
181 readonly runTime
: MeasurementStatistics
183 * Tasks wait time statistics.
185 readonly waitTime
: MeasurementStatistics
187 * Tasks event loop utilization statistics.
189 readonly elu
: EventLoopUtilizationMeasurementStatistics
193 * Worker choice strategy data.
197 export interface StrategyData
{
198 virtualTaskEndTimestamp
?: number
204 export interface IWorker
{
210 * Worker thread worker id.
212 readonly threadId
?: number
214 * Registers an event handler.
216 * @param event - The event.
217 * @param handler - The event handler.
222 | OnlineHandler
<this>
223 | MessageHandler
<this>
228 * Registers once an event handler.
230 * @param event - The event.
231 * @param handler - The event handler.
236 | OnlineHandler
<this>
237 | MessageHandler
<this>
242 * Stop all JavaScript execution in the worker thread as soon as possible.
243 * Returns a Promise for the exit code that is fulfilled when the `'exit' event` is emitted.
245 readonly terminate
?: () => Promise
<number>
247 * Cluster worker disconnect.
249 readonly disconnect
?: () => void
251 * Cluster worker kill.
253 readonly kill
?: (signal
?: string) => void
257 * Worker node options.
261 export interface WorkerNodeOptions
{
262 workerOptions
?: WorkerOptions
263 env
?: Record
<string, unknown
>
264 tasksQueueBackPressureSize
: number
268 * Worker node interface.
270 * @typeParam Worker - Type of worker.
271 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
274 export interface IWorkerNode
<Worker
extends IWorker
, Data
= unknown
>
275 extends EventEmitter
{
279 readonly worker
: Worker
283 readonly info
: WorkerInfo
285 * Worker usage statistics.
287 readonly usage
: WorkerUsage
289 * Worker choice strategy data.
290 * This is used to store data that are specific to the worker choice strategy.
292 strategyData
?: StrategyData
294 * Message channel (worker thread only).
296 readonly messageChannel
?: MessageChannel
298 * Tasks queue back pressure size.
299 * This is the number of tasks that can be enqueued before the worker node has back pressure.
301 tasksQueueBackPressureSize
: number
305 * @returns The tasks queue size.
307 readonly tasksQueueSize
: () => number
311 * @param task - The task to queue.
312 * @returns The tasks queue size.
314 readonly enqueueTask
: (task
: Task
<Data
>) => number
316 * Prepends a task to the tasks queue.
318 * @param task - The task to prepend.
319 * @returns The tasks queue size.
321 readonly unshiftTask
: (task
: Task
<Data
>) => number
325 * @returns The dequeued task.
327 readonly dequeueTask
: () => Task
<Data
> | undefined
329 * Pops a task from the tasks queue.
331 * @returns The popped task.
333 readonly popTask
: () => Task
<Data
> | undefined
335 * Clears tasks queue.
337 readonly clearTasksQueue
: () => void
339 * Whether the worker node has back pressure (i.e. its tasks queue is full).
341 * @returns `true` if the worker node has back pressure, `false` otherwise.
343 readonly hasBackPressure
: () => boolean
345 * Resets usage statistics.
347 readonly resetUsage
: () => void
349 * Terminates the worker node.
351 readonly terminate
: () => Promise
<void>
353 * Registers a worker event handler.
355 * @param event - The event.
356 * @param handler - The event handler.
358 readonly registerWorkerEventHandler
: (
361 | OnlineHandler
<Worker
>
362 | MessageHandler
<Worker
>
363 | ErrorHandler
<Worker
>
364 | ExitHandler
<Worker
>
367 * Registers once a worker event handler.
369 * @param event - The event.
370 * @param handler - The event handler.
372 readonly registerOnceWorkerEventHandler
: (
375 | OnlineHandler
<Worker
>
376 | MessageHandler
<Worker
>
377 | ErrorHandler
<Worker
>
378 | ExitHandler
<Worker
>
381 * Gets task function worker usage statistics.
383 * @param name - The task function name.
384 * @returns The task function worker usage statistics if the task function worker usage statistics are initialized, `undefined` otherwise.
386 readonly getTaskFunctionWorkerUsage
: (name
: string) => WorkerUsage
| undefined
388 * Deletes task function worker usage statistics.
390 * @param name - The task function name.
391 * @returns `true` if the task function worker usage statistics were deleted, `false` otherwise.
393 readonly deleteTaskFunctionWorkerUsage
: (name
: string) => boolean
397 * Worker node event detail.
401 export interface WorkerNodeEventDetail
{
403 workerNodeKey
?: number