Commit | Line | Data |
---|---|---|
e1c2dba7 | 1 | import type { EventEmitter } from 'node:events' |
ded253e2 JB |
2 | import type { MessageChannel, WorkerOptions } from 'node:worker_threads' |
3 | ||
d35e5717 JB |
4 | import type { CircularArray } from '../circular-array.js' |
5 | import 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 | */ |
12 | export 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 |
19 | export 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 |
29 | export 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 |
39 | export 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 | */ | |
49 | export 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 | 60 | export 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 | */ | |
92 | export 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 | 103 | export 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 | */ | |
137 | export const WorkerTypes = Object.freeze({ | |
149fdbb9 JB |
138 | thread: 'thread', |
139 | cluster: 'cluster' | |
4b628b48 JB |
140 | } as const) |
141 | ||
142 | /** | |
143 | * Worker type. | |
144 | */ | |
145 | export type WorkerType = keyof typeof WorkerTypes | |
146 | ||
f59e1027 JB |
147 | /** |
148 | * Worker information. | |
149 | * | |
150 | * @internal | |
151 | */ | |
152 | export interface WorkerInfo { | |
153 | /** | |
83fa0a36 | 154 | * Worker id. |
f59e1027 | 155 | */ |
eb7bf744 | 156 | readonly id: number | undefined |
4b628b48 JB |
157 | /** |
158 | * Worker type. | |
159 | */ | |
5b49e864 | 160 | readonly type: WorkerType |
8a1260a3 JB |
161 | /** |
162 | * Dynamic flag. | |
163 | */ | |
164 | dynamic: boolean | |
f59e1027 | 165 | /** |
7c8381eb | 166 | * Ready flag. |
f59e1027 | 167 | */ |
7c8381eb | 168 | ready: boolean |
5eb72b9e JB |
169 | /** |
170 | * Stealing flag. | |
171 | * This flag is set to `true` when worker node is stealing tasks from another worker node. | |
172 | */ | |
173 | stealing: boolean | |
b558f6b5 JB |
174 | /** |
175 | * Task function names. | |
176 | */ | |
6703b9f4 | 177 | taskFunctionNames?: string[] |
f59e1027 JB |
178 | } |
179 | ||
a4e07f72 JB |
180 | /** |
181 | * Worker usage statistics. | |
182 | * | |
183 | * @internal | |
184 | */ | |
185 | export interface WorkerUsage { | |
0567595a | 186 | /** |
a4e07f72 | 187 | * Tasks statistics. |
0567595a | 188 | */ |
eb7bf744 | 189 | readonly tasks: TaskStatistics |
0567595a | 190 | /** |
a4e07f72 | 191 | * Tasks runtime statistics. |
0567595a | 192 | */ |
eb7bf744 | 193 | readonly runTime: MeasurementStatistics |
02706357 | 194 | /** |
a4e07f72 | 195 | * Tasks wait time statistics. |
02706357 | 196 | */ |
eb7bf744 | 197 | readonly waitTime: MeasurementStatistics |
62c15a68 | 198 | /** |
5df69fab | 199 | * Tasks event loop utilization statistics. |
62c15a68 | 200 | */ |
eb7bf744 | 201 | readonly elu: EventLoopUtilizationMeasurementStatistics |
f06e48d8 JB |
202 | } |
203 | ||
f3a91bac | 204 | /** |
9df180cb | 205 | * Worker choice strategy data. |
57a29f75 JB |
206 | * |
207 | * @internal | |
f3a91bac JB |
208 | */ |
209 | export interface StrategyData { | |
210 | virtualTaskEndTimestamp?: number | |
211 | } | |
212 | ||
f06e48d8 JB |
213 | /** |
214 | * Worker interface. | |
215 | */ | |
a4791fb1 | 216 | export interface IWorker extends EventEmitter { |
f59e1027 | 217 | /** |
07e0c9e5 | 218 | * Cluster worker id. |
f59e1027 | 219 | */ |
aecc6e48 | 220 | readonly id?: number |
07e0c9e5 JB |
221 | /** |
222 | * Worker thread worker id. | |
223 | */ | |
aecc6e48 | 224 | readonly threadId?: number |
bdaf31cd | 225 | /** |
88af9bf1 | 226 | * Registers an event handler. |
bdaf31cd | 227 | * |
38e795c1 | 228 | * @param event - The event. |
48ef9107 | 229 | * @param handler - The event handler. |
bdaf31cd | 230 | */ |
a4791fb1 | 231 | readonly on: (event: string, handler: EventHandler<this>) => this |
c3719753 | 232 | /** |
88af9bf1 | 233 | * Registers once an event handler. |
bdaf31cd | 234 | * |
c3719753 JB |
235 | * @param event - The event. |
236 | * @param handler - The event handler. | |
bdaf31cd | 237 | */ |
a4791fb1 | 238 | readonly once: (event: string, handler: EventHandler<this>) => this |
d20cde84 JB |
239 | /** |
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. | |
242 | * @since v10.5.0 | |
243 | */ | |
244 | readonly unref?: () => void | |
07e0c9e5 JB |
245 | /** |
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. | |
248 | */ | |
249 | readonly terminate?: () => Promise<number> | |
250 | /** | |
251 | * Cluster worker disconnect. | |
252 | */ | |
253 | readonly disconnect?: () => void | |
254 | /** | |
255 | * Cluster worker kill. | |
256 | */ | |
257 | readonly kill?: (signal?: string) => void | |
bdaf31cd | 258 | } |
f06e48d8 | 259 | |
5b49e864 | 260 | /** |
c3719753 | 261 | * Worker node options. |
5b49e864 | 262 | * |
5b49e864 JB |
263 | * @internal |
264 | */ | |
c3719753 JB |
265 | export interface WorkerNodeOptions { |
266 | workerOptions?: WorkerOptions | |
267 | env?: Record<string, unknown> | |
c63a35a0 | 268 | tasksQueueBackPressureSize: number | undefined |
9f95d5eb | 269 | } |
ec287edf | 270 | |
f06e48d8 JB |
271 | /** |
272 | * Worker node interface. | |
c319c66b JB |
273 | * |
274 | * @typeParam Worker - Type of worker. | |
e102732c | 275 | * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data. |
c319c66b | 276 | * @internal |
f06e48d8 | 277 | */ |
9f95d5eb | 278 | export interface IWorkerNode<Worker extends IWorker, Data = unknown> |
e1c2dba7 | 279 | extends EventEmitter { |
c319c66b | 280 | /** |
ccd73e07 | 281 | * Worker. |
c319c66b | 282 | */ |
02706357 | 283 | readonly worker: Worker |
f59e1027 | 284 | /** |
ccd73e07 | 285 | * Worker info. |
f59e1027 | 286 | */ |
eb7bf744 | 287 | readonly info: WorkerInfo |
c319c66b | 288 | /** |
ccd73e07 | 289 | * Worker usage statistics. |
c319c66b | 290 | */ |
5b49e864 | 291 | readonly usage: WorkerUsage |
f3a91bac | 292 | /** |
9df180cb | 293 | * Worker choice strategy data. |
ae3ab61d | 294 | * This is used to store data that are specific to the worker choice strategy. |
f3a91bac JB |
295 | */ |
296 | strategyData?: StrategyData | |
26fb3c18 | 297 | /** |
07e0c9e5 | 298 | * Message channel (worker thread only). |
26fb3c18 JB |
299 | */ |
300 | readonly messageChannel?: MessageChannel | |
20c6f652 JB |
301 | /** |
302 | * Tasks queue back pressure size. | |
303 | * This is the number of tasks that can be enqueued before the worker node has back pressure. | |
304 | */ | |
305 | tasksQueueBackPressureSize: number | |
c319c66b | 306 | /** |
ccd73e07 | 307 | * Tasks queue size. |
4b628b48 JB |
308 | * |
309 | * @returns The tasks queue size. | |
310 | */ | |
311 | readonly tasksQueueSize: () => number | |
312 | /** | |
ccd73e07 | 313 | * Enqueue task. |
4b628b48 JB |
314 | * |
315 | * @param task - The task to queue. | |
a1763c54 | 316 | * @returns The tasks queue size. |
4b628b48 JB |
317 | */ |
318 | readonly enqueueTask: (task: Task<Data>) => number | |
72695f86 JB |
319 | /** |
320 | * Prepends a task to the tasks queue. | |
321 | * | |
322 | * @param task - The task to prepend. | |
323 | * @returns The tasks queue size. | |
324 | */ | |
325 | readonly unshiftTask: (task: Task<Data>) => number | |
4b628b48 | 326 | /** |
ccd73e07 | 327 | * Dequeue task. |
4b628b48 JB |
328 | * |
329 | * @returns The dequeued task. | |
330 | */ | |
331 | readonly dequeueTask: () => Task<Data> | undefined | |
72695f86 JB |
332 | /** |
333 | * Pops a task from the tasks queue. | |
334 | * | |
335 | * @returns The popped task. | |
336 | */ | |
337 | readonly popTask: () => Task<Data> | undefined | |
4b628b48 | 338 | /** |
ccd73e07 | 339 | * Clears tasks queue. |
4b628b48 JB |
340 | */ |
341 | readonly clearTasksQueue: () => void | |
671d5154 | 342 | /** |
e2b31e32 | 343 | * Whether the worker node has back pressure (i.e. its tasks queue is full). |
671d5154 JB |
344 | * |
345 | * @returns `true` if the worker node has back pressure, `false` otherwise. | |
346 | */ | |
347 | readonly hasBackPressure: () => boolean | |
4b628b48 | 348 | /** |
ff469b0e | 349 | * Resets usage statistics. |
c319c66b | 350 | */ |
4b628b48 | 351 | readonly resetUsage: () => void |
3f09ed9f | 352 | /** |
07e0c9e5 | 353 | * Terminates the worker node. |
3f09ed9f | 354 | */ |
07e0c9e5 | 355 | readonly terminate: () => Promise<void> |
c3719753 JB |
356 | /** |
357 | * Registers a worker event handler. | |
358 | * | |
359 | * @param event - The event. | |
88af9bf1 | 360 | * @param handler - The event handler. |
c3719753 JB |
361 | */ |
362 | readonly registerWorkerEventHandler: ( | |
363 | event: string, | |
3bcbd4c5 | 364 | handler: EventHandler<Worker> |
c3719753 JB |
365 | ) => void |
366 | /** | |
367 | * Registers once a worker event handler. | |
368 | * | |
369 | * @param event - The event. | |
88af9bf1 | 370 | * @param handler - The event handler. |
c3719753 JB |
371 | */ |
372 | readonly registerOnceWorkerEventHandler: ( | |
373 | event: string, | |
3bcbd4c5 | 374 | handler: EventHandler<Worker> |
c3719753 | 375 | ) => void |
ff128cc9 | 376 | /** |
2809112e JB |
377 | * Gets task function worker usage statistics. |
378 | * | |
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. | |
ff128cc9 | 381 | */ |
db0e38ee | 382 | readonly getTaskFunctionWorkerUsage: (name: string) => WorkerUsage | undefined |
adee6053 JB |
383 | /** |
384 | * Deletes task function worker usage statistics. | |
385 | * | |
386 | * @param name - The task function name. | |
387 | * @returns `true` if the task function worker usage statistics were deleted, `false` otherwise. | |
388 | */ | |
389 | readonly deleteTaskFunctionWorkerUsage: (name: string) => boolean | |
f06e48d8 | 390 | } |
c3719753 JB |
391 | |
392 | /** | |
393 | * Worker node event detail. | |
394 | * | |
395 | * @internal | |
396 | */ | |
397 | export interface WorkerNodeEventDetail { | |
3a20a1a1 | 398 | workerId?: number |
c3719753 JB |
399 | workerNodeKey?: number |
400 | } |