1 import type { MessageChannel
} 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
158 * Task function names.
160 taskFunctionNames
?: string[]
164 * Worker usage statistics.
168 export interface WorkerUsage
{
172 readonly tasks
: TaskStatistics
174 * Tasks runtime statistics.
176 readonly runTime
: MeasurementStatistics
178 * Tasks wait time statistics.
180 readonly waitTime
: MeasurementStatistics
182 * Tasks event loop utilization statistics.
184 readonly elu
: EventLoopUtilizationMeasurementStatistics
188 * Worker choice strategy data.
192 export interface StrategyData
{
193 virtualTaskEndTimestamp
?: number
199 export interface IWorker
{
204 readonly threadId
?: number
206 * Registers an event listener.
208 * @param event - The event.
209 * @param handler - The event handler.
211 readonly on
: ((event
: 'online', handler
: OnlineHandler
<this>) => void) &
212 ((event
: 'message', handler
: MessageHandler
<this>) => void) &
213 ((event
: 'error', handler
: ErrorHandler
<this>) => void) &
214 ((event
: 'exit', handler
: ExitHandler
<this>) => void)
216 * Registers a listener to the exit event that will only be performed once.
218 * @param event - The `'exit'` event.
219 * @param handler - The exit handler.
221 readonly once
: (event
: 'exit', handler
: ExitHandler
<this>) => void
225 * Worker node event detail.
229 export interface WorkerNodeEventDetail
{
231 workerNodeKey
?: number
235 * Worker node interface.
237 * @typeParam Worker - Type of worker.
238 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
241 export interface IWorkerNode
<Worker
extends IWorker
, Data
= unknown
>
242 extends EventEmitter
{
246 readonly worker
: Worker
250 readonly info
: WorkerInfo
252 * Worker usage statistics.
254 readonly usage
: WorkerUsage
256 * Worker choice strategy data.
257 * This is used to store data that are specific to the worker choice strategy.
259 strategyData
?: StrategyData
261 * Message channel (worker_threads only).
263 readonly messageChannel
?: MessageChannel
265 * Tasks queue back pressure size.
266 * This is the number of tasks that can be enqueued before the worker node has back pressure.
268 tasksQueueBackPressureSize
: number
272 * @returns The tasks queue size.
274 readonly tasksQueueSize
: () => number
278 * @param task - The task to queue.
279 * @returns The tasks queue size.
281 readonly enqueueTask
: (task
: Task
<Data
>) => number
283 * Prepends a task to the tasks queue.
285 * @param task - The task to prepend.
286 * @returns The tasks queue size.
288 readonly unshiftTask
: (task
: Task
<Data
>) => number
292 * @returns The dequeued task.
294 readonly dequeueTask
: () => Task
<Data
> | undefined
296 * Pops a task from the tasks queue.
298 * @returns The popped task.
300 readonly popTask
: () => Task
<Data
> | undefined
302 * Clears tasks queue.
304 readonly clearTasksQueue
: () => void
306 * Whether the worker node has back pressure (i.e. its tasks queue is full).
308 * @returns `true` if the worker node has back pressure, `false` otherwise.
310 readonly hasBackPressure
: () => boolean
312 * Resets usage statistics.
314 readonly resetUsage
: () => void
316 * Closes communication channel.
318 readonly closeChannel
: () => void
320 * Gets task function worker usage statistics.
322 * @param name - The task function name.
323 * @returns The task function worker usage statistics if the task function worker usage statistics are initialized, `undefined` otherwise.
325 readonly getTaskFunctionWorkerUsage
: (name
: string) => WorkerUsage
| undefined
327 * Deletes task function worker usage statistics.
329 * @param name - The task function name.
330 * @returns `true` if the task function worker usage statistics were deleted, `false` otherwise.
332 readonly deleteTaskFunctionWorkerUsage
: (name
: string) => boolean