1 import type { EventEmitter
} from
'node:events'
2 import type { MessageChannel
, WorkerOptions
} from
'node:worker_threads'
4 import type { CircularArray
} from
'../circular-array.js'
5 import type { Task
} from
'../utility-types.js'
8 * Callback invoked when the worker has started successfully.
10 * @typeParam Worker - Type of worker.
12 export type OnlineHandler
<Worker
extends IWorker
> = (this: Worker
) => void
15 * Callback invoked if the worker has received a message.
17 * @typeParam Worker - Type of worker.
19 export type MessageHandler
<Worker
extends IWorker
> = (
25 * Callback invoked if the worker raised an error.
27 * @typeParam Worker - Type of worker.
29 export type ErrorHandler
<Worker
extends IWorker
> = (
35 * Callback invoked when the worker exits successfully.
37 * @typeParam Worker - Type of worker.
39 export type ExitHandler
<Worker
extends IWorker
> = (
45 * Worker event handler.
47 * @typeParam Worker - Type of worker.
49 export type EventHandler
<Worker
extends IWorker
> =
50 | OnlineHandler
<Worker
>
51 | MessageHandler
<Worker
>
52 | ErrorHandler
<Worker
>
56 * Measurement statistics.
60 export interface MeasurementStatistics
{
62 * Measurement aggregate.
66 * Measurement minimum.
70 * Measurement maximum.
74 * Measurement average.
82 * Measurement history.
84 readonly history
: CircularArray
<number>
88 * Event loop utilization measurement statistics.
92 export interface EventLoopUtilizationMeasurementStatistics
{
93 readonly idle
: MeasurementStatistics
94 readonly active
: MeasurementStatistics
103 export interface TaskStatistics
{
105 * Number of executed tasks.
109 * Number of executing tasks.
113 * Number of queued tasks.
115 readonly queued
: number
117 * Maximum number of queued tasks.
119 readonly maxQueued
?: number
121 * Number of sequentially stolen tasks.
123 sequentiallyStolen
: number
125 * Number of stolen tasks.
129 * Number of failed tasks.
135 * Enumeration of worker types.
137 export const WorkerTypes
= Object.freeze({
145 export type WorkerType
= keyof
typeof WorkerTypes
148 * Worker information.
152 export interface WorkerInfo
{
156 readonly id
: number | undefined
160 readonly type: WorkerType
171 * This flag is set to `true` when worker node is stealing tasks from another worker node.
175 * Task function names.
177 taskFunctionNames
?: string[]
181 * Worker usage statistics.
185 export interface WorkerUsage
{
189 readonly tasks
: TaskStatistics
191 * Tasks runtime statistics.
193 readonly runTime
: MeasurementStatistics
195 * Tasks wait time statistics.
197 readonly waitTime
: MeasurementStatistics
199 * Tasks event loop utilization statistics.
201 readonly elu
: EventLoopUtilizationMeasurementStatistics
205 * Worker choice strategy data.
209 export interface StrategyData
{
210 virtualTaskEndTimestamp
?: number
216 export interface IWorker
extends EventEmitter
{
222 * Worker thread worker id.
224 readonly threadId
?: number
226 * Registers an event handler.
228 * @param event - The event.
229 * @param handler - The event handler.
231 readonly on
: (event
: string, handler
: EventHandler
<this>) => this
233 * Registers once an event handler.
235 * @param event - The event.
236 * @param handler - The event handler.
238 readonly once
: (event
: string, handler
: EventHandler
<this>) => this
240 * Calling `unref()` on a worker allows the thread to exit if this is the only
241 * active handle in the event system. If the worker is already `unref()`ed calling`unref()` again has no effect.
244 readonly unref
?: () => void
246 * Stop all JavaScript execution in the worker thread as soon as possible.
247 * Returns a Promise for the exit code that is fulfilled when the `'exit' event` is emitted.
249 readonly terminate
?: () => Promise
<number>
251 * Cluster worker disconnect.
253 readonly disconnect
?: () => void
255 * Cluster worker kill.
257 readonly kill
?: (signal
?: string) => void
261 * Worker node options.
265 export interface WorkerNodeOptions
{
266 workerOptions
?: WorkerOptions
267 env
?: Record
<string, unknown
>
268 tasksQueueBackPressureSize
: number | undefined
272 * Worker node interface.
274 * @typeParam Worker - Type of worker.
275 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
278 export interface IWorkerNode
<Worker
extends IWorker
, Data
= unknown
>
279 extends EventEmitter
{
283 readonly worker
: Worker
287 readonly info
: WorkerInfo
289 * Worker usage statistics.
291 readonly usage
: WorkerUsage
293 * Worker choice strategy data.
294 * This is used to store data that are specific to the worker choice strategy.
296 strategyData
?: StrategyData
298 * Message channel (worker thread only).
300 readonly messageChannel
?: MessageChannel
302 * Tasks queue back pressure size.
303 * This is the number of tasks that can be enqueued before the worker node has back pressure.
305 tasksQueueBackPressureSize
: number
309 * @returns The tasks queue size.
311 readonly tasksQueueSize
: () => number
315 * @param task - The task to queue.
316 * @returns The tasks queue size.
318 readonly enqueueTask
: (task
: Task
<Data
>) => number
320 * Prepends a task to the tasks queue.
322 * @param task - The task to prepend.
323 * @returns The tasks queue size.
325 readonly unshiftTask
: (task
: Task
<Data
>) => number
329 * @returns The dequeued task.
331 readonly dequeueTask
: () => Task
<Data
> | undefined
333 * Pops a task from the tasks queue.
335 * @returns The popped task.
337 readonly popTask
: () => Task
<Data
> | undefined
339 * Clears tasks queue.
341 readonly clearTasksQueue
: () => void
343 * Whether the worker node has back pressure (i.e. its tasks queue is full).
345 * @returns `true` if the worker node has back pressure, `false` otherwise.
347 readonly hasBackPressure
: () => boolean
349 * Resets usage statistics.
351 readonly resetUsage
: () => void
353 * Terminates the worker node.
355 readonly terminate
: () => Promise
<void>
357 * Registers a worker event handler.
359 * @param event - The event.
360 * @param handler - The event handler.
362 readonly registerWorkerEventHandler
: (
364 handler
: EventHandler
<Worker
>
367 * Registers once a worker event handler.
369 * @param event - The event.
370 * @param handler - The event handler.
372 readonly registerOnceWorkerEventHandler
: (
374 handler
: EventHandler
<Worker
>
377 * Gets task function worker usage statistics.
379 * @param name - The task function name.
380 * @returns The task function worker usage statistics if the task function worker usage statistics are initialized, `undefined` otherwise.
382 readonly getTaskFunctionWorkerUsage
: (name
: string) => WorkerUsage
| undefined
384 * Deletes task function worker usage statistics.
386 * @param name - The task function name.
387 * @returns `true` if the task function worker usage statistics were deleted, `false` otherwise.
389 readonly deleteTaskFunctionWorkerUsage
: (name
: string) => boolean
393 * Worker node event detail.
397 export interface WorkerNodeEventDetail
{
399 workerNodeKey
?: number