chore: v3.1.7
[poolifier.git] / src / pools / worker.ts
CommitLineData
51280f9b 1import type { MessageChannel, WorkerOptions } from 'node:worker_threads'
e1c2dba7 2import type { EventEmitter } from 'node:events'
f06e48d8 3import type { CircularArray } from '../circular-array'
5c4d16da 4import type { Task } from '../utility-types'
f06e48d8 5
671d5154
JB
6/**
7 * Callback invoked when the worker has started successfully.
09b75fef
JB
8 *
9 * @typeParam Worker - Type of worker.
671d5154
JB
10 */
11export type OnlineHandler<Worker extends IWorker> = (this: Worker) => void
12
bdaf31cd
JB
13/**
14 * Callback invoked if the worker has received a message.
09b75fef
JB
15 *
16 * @typeParam Worker - Type of worker.
bdaf31cd 17 */
50e66724
JB
18export type MessageHandler<Worker extends IWorker> = (
19 this: Worker,
e102732c 20 message: unknown
50e66724 21) => void
bdaf31cd
JB
22
23/**
24 * Callback invoked if the worker raised an error.
09b75fef
JB
25 *
26 * @typeParam Worker - Type of worker.
bdaf31cd 27 */
50e66724
JB
28export type ErrorHandler<Worker extends IWorker> = (
29 this: Worker,
e102732c 30 error: Error
50e66724 31) => void
bdaf31cd 32
bdaf31cd
JB
33/**
34 * Callback invoked when the worker exits successfully.
09b75fef
JB
35 *
36 * @typeParam Worker - Type of worker.
bdaf31cd 37 */
50e66724
JB
38export type ExitHandler<Worker extends IWorker> = (
39 this: Worker,
e102732c 40 exitCode: number
50e66724 41) => void
bdaf31cd 42
f06e48d8 43/**
cd4d348a 44 * Measurement statistics.
f9b4bbf8
JB
45 *
46 * @internal
f06e48d8 47 */
cd4d348a 48export interface MeasurementStatistics {
02706357 49 /**
932fc8be 50 * Measurement aggregate.
02706357 51 */
71514351 52 aggregate?: number
f7510105
JB
53 /**
54 * Measurement minimum.
55 */
71514351 56 minimum?: number
f7510105
JB
57 /**
58 * Measurement maximum.
59 */
71514351 60 maximum?: number
02706357 61 /**
cd4d348a 62 * Measurement average.
02706357 63 */
71514351 64 average?: number
02706357 65 /**
cd4d348a 66 * Measurement median.
02706357 67 */
71514351 68 median?: number
02706357 69 /**
cd4d348a 70 * Measurement history.
02706357 71 */
eb7bf744 72 readonly history: CircularArray<number>
a4e07f72
JB
73}
74
5df69fab
JB
75/**
76 * Event loop utilization measurement statistics.
77 *
78 * @internal
79 */
80export interface EventLoopUtilizationMeasurementStatistics {
eb7bf744
JB
81 readonly idle: MeasurementStatistics
82 readonly active: MeasurementStatistics
f7510105 83 utilization?: number
5df69fab
JB
84}
85
a4e07f72
JB
86/**
87 * Task statistics.
88 *
89 * @internal
90 */
a4e07f72 91export interface TaskStatistics {
02706357 92 /**
9a0613e9 93 * Number of executed tasks.
02706357 94 */
a4e07f72 95 executed: number
02706357 96 /**
9a0613e9 97 * Number of executing tasks.
02706357 98 */
a4e07f72 99 executing: number
0567595a 100 /**
9a0613e9 101 * Number of queued tasks.
0567595a 102 */
8604aaab 103 readonly queued: number
df593701
JB
104 /**
105 * Maximum number of queued tasks.
106 */
b25a42cd 107 readonly maxQueued?: number
463226a4
JB
108 /**
109 * Number of sequentially stolen tasks.
110 */
111 sequentiallyStolen: number
68cbdc84
JB
112 /**
113 * Number of stolen tasks.
114 */
115 stolen: number
0567595a 116 /**
9a0613e9 117 * Number of failed tasks.
0567595a 118 */
a4e07f72
JB
119 failed: number
120}
121
4b628b48
JB
122/**
123 * Enumeration of worker types.
124 */
125export const WorkerTypes = Object.freeze({
149fdbb9
JB
126 thread: 'thread',
127 cluster: 'cluster'
4b628b48
JB
128} as const)
129
130/**
131 * Worker type.
132 */
133export type WorkerType = keyof typeof WorkerTypes
134
f59e1027
JB
135/**
136 * Worker information.
137 *
138 * @internal
139 */
140export interface WorkerInfo {
141 /**
83fa0a36 142 * Worker id.
f59e1027 143 */
eb7bf744 144 readonly id: number | undefined
4b628b48
JB
145 /**
146 * Worker type.
147 */
5b49e864 148 readonly type: WorkerType
8a1260a3
JB
149 /**
150 * Dynamic flag.
151 */
152 dynamic: boolean
f59e1027 153 /**
7c8381eb 154 * Ready flag.
f59e1027 155 */
7c8381eb 156 ready: boolean
b558f6b5
JB
157 /**
158 * Task function names.
159 */
6703b9f4 160 taskFunctionNames?: string[]
f59e1027
JB
161}
162
a4e07f72
JB
163/**
164 * Worker usage statistics.
165 *
166 * @internal
167 */
168export interface WorkerUsage {
0567595a 169 /**
a4e07f72 170 * Tasks statistics.
0567595a 171 */
eb7bf744 172 readonly tasks: TaskStatistics
0567595a 173 /**
a4e07f72 174 * Tasks runtime statistics.
0567595a 175 */
eb7bf744 176 readonly runTime: MeasurementStatistics
02706357 177 /**
a4e07f72 178 * Tasks wait time statistics.
02706357 179 */
eb7bf744 180 readonly waitTime: MeasurementStatistics
62c15a68 181 /**
5df69fab 182 * Tasks event loop utilization statistics.
62c15a68 183 */
eb7bf744 184 readonly elu: EventLoopUtilizationMeasurementStatistics
f06e48d8
JB
185}
186
f3a91bac 187/**
9df180cb 188 * Worker choice strategy data.
57a29f75
JB
189 *
190 * @internal
f3a91bac
JB
191 */
192export interface StrategyData {
193 virtualTaskEndTimestamp?: number
194}
195
f06e48d8
JB
196/**
197 * Worker interface.
198 */
199export interface IWorker {
f59e1027 200 /**
07e0c9e5 201 * Cluster worker id.
f59e1027 202 */
aecc6e48 203 readonly id?: number
07e0c9e5
JB
204 /**
205 * Worker thread worker id.
206 */
aecc6e48 207 readonly threadId?: number
bdaf31cd 208 /**
88af9bf1 209 * Registers an event handler.
bdaf31cd 210 *
38e795c1 211 * @param event - The event.
48ef9107 212 * @param handler - The event handler.
bdaf31cd 213 */
c3719753
JB
214 readonly on: (
215 event: string,
216 handler:
217 | OnlineHandler<this>
218 | MessageHandler<this>
219 | ErrorHandler<this>
220 | ExitHandler<this>
221 ) => void
222 /**
88af9bf1 223 * Registers once an event handler.
bdaf31cd 224 *
c3719753
JB
225 * @param event - The event.
226 * @param handler - The event handler.
bdaf31cd 227 */
c3719753
JB
228 readonly once: (
229 event: string,
230 handler:
231 | OnlineHandler<this>
232 | MessageHandler<this>
233 | ErrorHandler<this>
234 | ExitHandler<this>
235 ) => void
07e0c9e5
JB
236 /**
237 * Stop all JavaScript execution in the worker thread as soon as possible.
238 * Returns a Promise for the exit code that is fulfilled when the `'exit' event` is emitted.
239 */
240 readonly terminate?: () => Promise<number>
241 /**
242 * Cluster worker disconnect.
243 */
244 readonly disconnect?: () => void
245 /**
246 * Cluster worker kill.
247 */
248 readonly kill?: (signal?: string) => void
bdaf31cd 249}
f06e48d8 250
5b49e864 251/**
c3719753 252 * Worker node options.
5b49e864 253 *
5b49e864
JB
254 * @internal
255 */
c3719753
JB
256export interface WorkerNodeOptions {
257 workerOptions?: WorkerOptions
258 env?: Record<string, unknown>
259 tasksQueueBackPressureSize: number
9f95d5eb 260}
ec287edf 261
f06e48d8
JB
262/**
263 * Worker node interface.
c319c66b
JB
264 *
265 * @typeParam Worker - Type of worker.
e102732c 266 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
c319c66b 267 * @internal
f06e48d8 268 */
9f95d5eb 269export interface IWorkerNode<Worker extends IWorker, Data = unknown>
e1c2dba7 270 extends EventEmitter {
c319c66b 271 /**
ccd73e07 272 * Worker.
c319c66b 273 */
02706357 274 readonly worker: Worker
f59e1027 275 /**
ccd73e07 276 * Worker info.
f59e1027 277 */
eb7bf744 278 readonly info: WorkerInfo
c319c66b 279 /**
ccd73e07 280 * Worker usage statistics.
c319c66b 281 */
5b49e864 282 readonly usage: WorkerUsage
f3a91bac 283 /**
9df180cb 284 * Worker choice strategy data.
ae3ab61d 285 * This is used to store data that are specific to the worker choice strategy.
f3a91bac
JB
286 */
287 strategyData?: StrategyData
26fb3c18 288 /**
07e0c9e5 289 * Message channel (worker thread only).
26fb3c18
JB
290 */
291 readonly messageChannel?: MessageChannel
20c6f652
JB
292 /**
293 * Tasks queue back pressure size.
294 * This is the number of tasks that can be enqueued before the worker node has back pressure.
295 */
296 tasksQueueBackPressureSize: number
c319c66b 297 /**
ccd73e07 298 * Tasks queue size.
4b628b48
JB
299 *
300 * @returns The tasks queue size.
301 */
302 readonly tasksQueueSize: () => number
303 /**
ccd73e07 304 * Enqueue task.
4b628b48
JB
305 *
306 * @param task - The task to queue.
a1763c54 307 * @returns The tasks queue size.
4b628b48
JB
308 */
309 readonly enqueueTask: (task: Task<Data>) => number
72695f86
JB
310 /**
311 * Prepends a task to the tasks queue.
312 *
313 * @param task - The task to prepend.
314 * @returns The tasks queue size.
315 */
316 readonly unshiftTask: (task: Task<Data>) => number
4b628b48 317 /**
ccd73e07 318 * Dequeue task.
4b628b48
JB
319 *
320 * @returns The dequeued task.
321 */
322 readonly dequeueTask: () => Task<Data> | undefined
72695f86
JB
323 /**
324 * Pops a task from the tasks queue.
325 *
326 * @returns The popped task.
327 */
328 readonly popTask: () => Task<Data> | undefined
4b628b48 329 /**
ccd73e07 330 * Clears tasks queue.
4b628b48
JB
331 */
332 readonly clearTasksQueue: () => void
671d5154 333 /**
e2b31e32 334 * Whether the worker node has back pressure (i.e. its tasks queue is full).
671d5154
JB
335 *
336 * @returns `true` if the worker node has back pressure, `false` otherwise.
337 */
338 readonly hasBackPressure: () => boolean
4b628b48 339 /**
ff469b0e 340 * Resets usage statistics.
c319c66b 341 */
4b628b48 342 readonly resetUsage: () => void
3f09ed9f 343 /**
07e0c9e5 344 * Terminates the worker node.
3f09ed9f 345 */
07e0c9e5 346 readonly terminate: () => Promise<void>
c3719753
JB
347 /**
348 * Registers a worker event handler.
349 *
350 * @param event - The event.
88af9bf1 351 * @param handler - The event handler.
c3719753
JB
352 */
353 readonly registerWorkerEventHandler: (
354 event: string,
88af9bf1 355 handler:
c3719753
JB
356 | OnlineHandler<Worker>
357 | MessageHandler<Worker>
358 | ErrorHandler<Worker>
359 | ExitHandler<Worker>
360 ) => void
361 /**
362 * Registers once a worker event handler.
363 *
364 * @param event - The event.
88af9bf1 365 * @param handler - The event handler.
c3719753
JB
366 */
367 readonly registerOnceWorkerEventHandler: (
368 event: string,
88af9bf1 369 handler:
c3719753
JB
370 | OnlineHandler<Worker>
371 | MessageHandler<Worker>
372 | ErrorHandler<Worker>
373 | ExitHandler<Worker>
374 ) => void
ff128cc9 375 /**
2809112e
JB
376 * Gets task function worker usage statistics.
377 *
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.
ff128cc9 380 */
db0e38ee 381 readonly getTaskFunctionWorkerUsage: (name: string) => WorkerUsage | undefined
adee6053
JB
382 /**
383 * Deletes task function worker usage statistics.
384 *
385 * @param name - The task function name.
386 * @returns `true` if the task function worker usage statistics were deleted, `false` otherwise.
387 */
388 readonly deleteTaskFunctionWorkerUsage: (name: string) => boolean
f06e48d8 389}
c3719753
JB
390
391/**
392 * Worker node event detail.
393 *
394 * @internal
395 */
396export interface WorkerNodeEventDetail {
397 workerId: number
398 workerNodeKey?: number
399}