1 import type { MessageChannel
} from
'node:worker_threads'
2 import type { CircularArray
} from
'../circular-array'
3 import type { Task
} from
'../utility-types'
6 * Callback invoked when the worker has started successfully.
8 export type OnlineHandler
<Worker
extends IWorker
> = (this: Worker
) => void
11 * Callback invoked if the worker has received a message.
13 export type MessageHandler
<Worker
extends IWorker
> = (
19 * Callback invoked if the worker raised an error.
21 export type ErrorHandler
<Worker
extends IWorker
> = (
27 * Callback invoked when the worker exits successfully.
29 export type ExitHandler
<Worker
extends IWorker
> = (
35 * Measurement statistics.
39 export interface MeasurementStatistics
{
41 * Measurement aggregate.
45 * Measurement minimum.
49 * Measurement maximum.
53 * Measurement average.
61 * Measurement history.
63 readonly history
: CircularArray
<number>
67 * Event loop utilization measurement statistics.
71 export interface EventLoopUtilizationMeasurementStatistics
{
72 readonly idle
: MeasurementStatistics
73 readonly active
: MeasurementStatistics
82 export interface TaskStatistics
{
84 * Number of executed tasks.
88 * Number of executing tasks.
92 * Number of queued tasks.
94 readonly queued
: number
96 * Maximum number of queued tasks.
98 readonly maxQueued
?: number
100 * Number of stolen tasks.
104 * Number of failed tasks.
110 * Enumeration of worker types.
112 export const WorkerTypes
= Object.freeze({
120 export type WorkerType
= keyof
typeof WorkerTypes
123 * Worker information.
127 export interface WorkerInfo
{
131 readonly id
: number | undefined
135 readonly type: WorkerType
145 * Task function names.
147 taskFunctions
?: string[]
151 * Worker usage statistics.
155 export interface WorkerUsage
{
159 readonly tasks
: TaskStatistics
161 * Tasks runtime statistics.
163 readonly runTime
: MeasurementStatistics
165 * Tasks wait time statistics.
167 readonly waitTime
: MeasurementStatistics
169 * Tasks event loop utilization statistics.
171 readonly elu
: EventLoopUtilizationMeasurementStatistics
175 * Worker choice strategy data.
177 export interface StrategyData
{
178 virtualTaskEndTimestamp
?: number
184 export interface IWorker
{
189 readonly threadId
?: number
191 * Registers an event listener.
193 * @param event - The event.
194 * @param handler - The event handler.
196 readonly on
: ((event
: 'online', handler
: OnlineHandler
<this>) => void) &
197 ((event
: 'message', handler
: MessageHandler
<this>) => void) &
198 ((event
: 'error', handler
: ErrorHandler
<this>) => void) &
199 ((event
: 'exit', handler
: ExitHandler
<this>) => void)
201 * Registers a listener to the exit event that will only be performed once.
203 * @param event - The `'exit'` event.
204 * @param handler - The exit handler.
206 readonly once
: (event
: 'exit', handler
: ExitHandler
<this>) => void
210 * Worker node event callback.
212 * @param workerId - The worker id.
215 export type WorkerNodeEventCallback
= (workerId
: number) => void
218 * Worker node interface.
220 * @typeParam Worker - Type of worker.
221 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
224 export interface IWorkerNode
<Worker
extends IWorker
, Data
= unknown
> {
228 readonly worker
: Worker
232 readonly info
: WorkerInfo
234 * Worker usage statistics.
236 readonly usage
: WorkerUsage
238 * Worker choice strategy data.
239 * This is used to store data that is specific to the worker choice strategy.
241 strategyData
?: StrategyData
243 * Message channel (worker_threads only).
245 readonly messageChannel
?: MessageChannel
247 * Tasks queue back pressure size.
248 * This is the number of tasks that can be enqueued before the worker node has back pressure.
250 tasksQueueBackPressureSize
: number
252 * Callback invoked when worker node tasks queue is back pressured.
254 onBackPressure
?: WorkerNodeEventCallback
256 * Callback invoked when worker node tasks queue is empty.
258 onEmptyQueue
?: WorkerNodeEventCallback
262 * @returns The tasks queue size.
264 readonly tasksQueueSize
: () => number
268 * @param task - The task to queue.
269 * @returns The tasks queue size.
271 readonly enqueueTask
: (task
: Task
<Data
>) => number
273 * Prepends a task to the tasks queue.
275 * @param task - The task to prepend.
276 * @returns The tasks queue size.
278 readonly unshiftTask
: (task
: Task
<Data
>) => number
282 * @returns The dequeued task.
284 readonly dequeueTask
: () => Task
<Data
> | undefined
286 * Pops a task from the tasks queue.
288 * @returns The popped task.
290 readonly popTask
: () => Task
<Data
> | undefined
292 * Clears tasks queue.
294 readonly clearTasksQueue
: () => void
296 * Whether the worker node has back pressure (i.e. its tasks queue is full).
298 * @returns `true` if the worker node has back pressure, `false` otherwise.
300 readonly hasBackPressure
: () => boolean
302 * Resets usage statistics.
304 readonly resetUsage
: () => void
306 * Closes communication channel.
308 readonly closeChannel
: () => void
310 * Gets task function worker usage statistics.
312 * @param name - The task function name.
313 * @returns The task function worker usage statistics if the task function worker usage statistics are initialized, `undefined` otherwise.
315 readonly getTaskFunctionWorkerUsage
: (name
: string) => WorkerUsage
| undefined