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