Merge branch 'master' into feature/task-functions
[poolifier.git] / src / pools / worker.ts
CommitLineData
85aeb3f3 1import type { MessageChannel } from 'node:worker_threads'
f06e48d8 2import type { CircularArray } from '../circular-array'
5c4d16da 3import type { Task } from '../utility-types'
f06e48d8 4
671d5154
JB
5/**
6 * Callback invoked when the worker has started successfully.
7 */
8export type OnlineHandler<Worker extends IWorker> = (this: Worker) => void
9
bdaf31cd
JB
10/**
11 * Callback invoked if the worker has received a message.
12 */
50e66724
JB
13export type MessageHandler<Worker extends IWorker> = (
14 this: Worker,
e102732c 15 message: unknown
50e66724 16) => void
bdaf31cd
JB
17
18/**
19 * Callback invoked if the worker raised an error.
20 */
50e66724
JB
21export type ErrorHandler<Worker extends IWorker> = (
22 this: Worker,
e102732c 23 error: Error
50e66724 24) => void
bdaf31cd 25
bdaf31cd
JB
26/**
27 * Callback invoked when the worker exits successfully.
28 */
50e66724
JB
29export type ExitHandler<Worker extends IWorker> = (
30 this: Worker,
e102732c 31 exitCode: number
50e66724 32) => void
bdaf31cd 33
f06e48d8 34/**
cd4d348a 35 * Measurement statistics.
f9b4bbf8
JB
36 *
37 * @internal
f06e48d8 38 */
cd4d348a 39export interface MeasurementStatistics {
02706357 40 /**
932fc8be 41 * Measurement aggregate.
02706357 42 */
71514351 43 aggregate?: number
f7510105
JB
44 /**
45 * Measurement minimum.
46 */
71514351 47 minimum?: number
f7510105
JB
48 /**
49 * Measurement maximum.
50 */
71514351 51 maximum?: number
02706357 52 /**
cd4d348a 53 * Measurement average.
02706357 54 */
71514351 55 average?: number
02706357 56 /**
cd4d348a 57 * Measurement median.
02706357 58 */
71514351 59 median?: number
02706357 60 /**
cd4d348a 61 * Measurement history.
02706357 62 */
eb7bf744 63 readonly history: CircularArray<number>
a4e07f72
JB
64}
65
5df69fab
JB
66/**
67 * Event loop utilization measurement statistics.
68 *
69 * @internal
70 */
71export interface EventLoopUtilizationMeasurementStatistics {
eb7bf744
JB
72 readonly idle: MeasurementStatistics
73 readonly active: MeasurementStatistics
f7510105 74 utilization?: number
5df69fab
JB
75}
76
a4e07f72
JB
77/**
78 * Task statistics.
79 *
80 * @internal
81 */
a4e07f72 82export interface TaskStatistics {
02706357 83 /**
9a0613e9 84 * Number of executed tasks.
02706357 85 */
a4e07f72 86 executed: number
02706357 87 /**
9a0613e9 88 * Number of executing tasks.
02706357 89 */
a4e07f72 90 executing: number
0567595a 91 /**
9a0613e9 92 * Number of queued tasks.
0567595a 93 */
8604aaab 94 readonly queued: number
df593701
JB
95 /**
96 * Maximum number of queued tasks.
97 */
b25a42cd 98 readonly maxQueued?: number
68cbdc84
JB
99 /**
100 * Number of stolen tasks.
101 */
102 stolen: number
0567595a 103 /**
9a0613e9 104 * Number of failed tasks.
0567595a 105 */
a4e07f72
JB
106 failed: number
107}
108
4b628b48
JB
109/**
110 * Enumeration of worker types.
111 */
112export const WorkerTypes = Object.freeze({
149fdbb9
JB
113 thread: 'thread',
114 cluster: 'cluster'
4b628b48
JB
115} as const)
116
117/**
118 * Worker type.
119 */
120export type WorkerType = keyof typeof WorkerTypes
121
f59e1027
JB
122/**
123 * Worker information.
124 *
125 * @internal
126 */
127export interface WorkerInfo {
128 /**
83fa0a36 129 * Worker id.
f59e1027 130 */
eb7bf744 131 readonly id: number | undefined
4b628b48
JB
132 /**
133 * Worker type.
134 */
5b49e864 135 readonly type: WorkerType
8a1260a3
JB
136 /**
137 * Dynamic flag.
138 */
139 dynamic: boolean
f59e1027 140 /**
7c8381eb 141 * Ready flag.
f59e1027 142 */
7c8381eb 143 ready: boolean
b558f6b5
JB
144 /**
145 * Task function names.
146 */
6703b9f4 147 taskFunctionNames?: string[]
f59e1027
JB
148}
149
a4e07f72
JB
150/**
151 * Worker usage statistics.
152 *
153 * @internal
154 */
155export interface WorkerUsage {
0567595a 156 /**
a4e07f72 157 * Tasks statistics.
0567595a 158 */
eb7bf744 159 readonly tasks: TaskStatistics
0567595a 160 /**
a4e07f72 161 * Tasks runtime statistics.
0567595a 162 */
eb7bf744 163 readonly runTime: MeasurementStatistics
02706357 164 /**
a4e07f72 165 * Tasks wait time statistics.
02706357 166 */
eb7bf744 167 readonly waitTime: MeasurementStatistics
62c15a68 168 /**
5df69fab 169 * Tasks event loop utilization statistics.
62c15a68 170 */
eb7bf744 171 readonly elu: EventLoopUtilizationMeasurementStatistics
f06e48d8
JB
172}
173
f3a91bac 174/**
9df180cb 175 * Worker choice strategy data.
57a29f75
JB
176 *
177 * @internal
f3a91bac
JB
178 */
179export interface StrategyData {
180 virtualTaskEndTimestamp?: number
181}
182
f06e48d8
JB
183/**
184 * Worker interface.
185 */
186export interface IWorker {
f59e1027 187 /**
83fa0a36 188 * Worker id.
f59e1027 189 */
aecc6e48
JB
190 readonly id?: number
191 readonly threadId?: number
bdaf31cd 192 /**
64383951 193 * Registers an event listener.
bdaf31cd 194 *
38e795c1 195 * @param event - The event.
48ef9107 196 * @param handler - The event handler.
bdaf31cd 197 */
fd04474e
JB
198 readonly on: ((event: 'online', handler: OnlineHandler<this>) => void) &
199 ((event: 'message', handler: MessageHandler<this>) => void) &
78cea37e 200 ((event: 'error', handler: ErrorHandler<this>) => void) &
78cea37e 201 ((event: 'exit', handler: ExitHandler<this>) => void)
bdaf31cd 202 /**
64383951 203 * Registers a listener to the exit event that will only be performed once.
bdaf31cd 204 *
9ece5893 205 * @param event - The `'exit'` event.
38e795c1 206 * @param handler - The exit handler.
bdaf31cd 207 */
4b628b48 208 readonly once: (event: 'exit', handler: ExitHandler<this>) => void
bdaf31cd 209}
f06e48d8 210
5b49e864
JB
211/**
212 * Worker node event callback.
213 *
214 * @param workerId - The worker id.
215 * @internal
216 */
a9780ad2 217export type WorkerNodeEventCallback = (workerId: number) => void
ec287edf 218
f06e48d8
JB
219/**
220 * Worker node interface.
c319c66b
JB
221 *
222 * @typeParam Worker - Type of worker.
e102732c 223 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
c319c66b 224 * @internal
f06e48d8 225 */
4b628b48 226export interface IWorkerNode<Worker extends IWorker, Data = unknown> {
c319c66b 227 /**
ccd73e07 228 * Worker.
c319c66b 229 */
02706357 230 readonly worker: Worker
f59e1027 231 /**
ccd73e07 232 * Worker info.
f59e1027 233 */
eb7bf744 234 readonly info: WorkerInfo
c319c66b 235 /**
ccd73e07 236 * Worker usage statistics.
c319c66b 237 */
5b49e864 238 readonly usage: WorkerUsage
f3a91bac 239 /**
9df180cb 240 * Worker choice strategy data.
f3a91bac
JB
241 * This is used to store data that is specific to the worker choice strategy.
242 */
243 strategyData?: StrategyData
26fb3c18
JB
244 /**
245 * Message channel (worker_threads only).
246 */
247 readonly messageChannel?: MessageChannel
20c6f652
JB
248 /**
249 * Tasks queue back pressure size.
250 * This is the number of tasks that can be enqueued before the worker node has back pressure.
251 */
252 tasksQueueBackPressureSize: number
72695f86
JB
253 /**
254 * Callback invoked when worker node tasks queue is back pressured.
72695f86 255 */
a9780ad2 256 onBackPressure?: WorkerNodeEventCallback
dd951876
JB
257 /**
258 * Callback invoked when worker node tasks queue is empty.
dd951876 259 */
a9780ad2 260 onEmptyQueue?: WorkerNodeEventCallback
c319c66b 261 /**
ccd73e07 262 * Tasks queue size.
4b628b48
JB
263 *
264 * @returns The tasks queue size.
265 */
266 readonly tasksQueueSize: () => number
267 /**
ccd73e07 268 * Enqueue task.
4b628b48
JB
269 *
270 * @param task - The task to queue.
a1763c54 271 * @returns The tasks queue size.
4b628b48
JB
272 */
273 readonly enqueueTask: (task: Task<Data>) => number
72695f86
JB
274 /**
275 * Prepends a task to the tasks queue.
276 *
277 * @param task - The task to prepend.
278 * @returns The tasks queue size.
279 */
280 readonly unshiftTask: (task: Task<Data>) => number
4b628b48 281 /**
ccd73e07 282 * Dequeue task.
4b628b48
JB
283 *
284 * @returns The dequeued task.
285 */
286 readonly dequeueTask: () => Task<Data> | undefined
72695f86
JB
287 /**
288 * Pops a task from the tasks queue.
289 *
290 * @returns The popped task.
291 */
292 readonly popTask: () => Task<Data> | undefined
4b628b48 293 /**
ccd73e07 294 * Clears tasks queue.
4b628b48
JB
295 */
296 readonly clearTasksQueue: () => void
671d5154 297 /**
e2b31e32 298 * Whether the worker node has back pressure (i.e. its tasks queue is full).
671d5154
JB
299 *
300 * @returns `true` if the worker node has back pressure, `false` otherwise.
301 */
302 readonly hasBackPressure: () => boolean
4b628b48 303 /**
ff469b0e 304 * Resets usage statistics.
c319c66b 305 */
4b628b48 306 readonly resetUsage: () => void
3f09ed9f 307 /**
a5d15204 308 * Closes communication channel.
3f09ed9f
JB
309 */
310 readonly closeChannel: () => void
ff128cc9 311 /**
2809112e
JB
312 * Gets task function worker usage statistics.
313 *
314 * @param name - The task function name.
315 * @returns The task function worker usage statistics if the task function worker usage statistics are initialized, `undefined` otherwise.
ff128cc9 316 */
db0e38ee 317 readonly getTaskFunctionWorkerUsage: (name: string) => WorkerUsage | undefined
f06e48d8 318}