Commit | Line | Data |
---|---|---|
85aeb3f3 | 1 | import type { MessageChannel } from 'node:worker_threads' |
f06e48d8 | 2 | import type { CircularArray } from '../circular-array' |
5c4d16da | 3 | import type { Task } from '../utility-types' |
f06e48d8 | 4 | |
671d5154 JB |
5 | /** |
6 | * Callback invoked when the worker has started successfully. | |
7 | */ | |
8 | export 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 |
13 | export 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 |
21 | export 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 |
29 | export 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 | 39 | export 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 | */ | |
71 | export 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 | 82 | export 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 | */ | |
112 | export const WorkerTypes = Object.freeze({ | |
149fdbb9 JB |
113 | thread: 'thread', |
114 | cluster: 'cluster' | |
4b628b48 JB |
115 | } as const) |
116 | ||
117 | /** | |
118 | * Worker type. | |
119 | */ | |
120 | export type WorkerType = keyof typeof WorkerTypes | |
121 | ||
f59e1027 JB |
122 | /** |
123 | * Worker information. | |
124 | * | |
125 | * @internal | |
126 | */ | |
127 | export interface WorkerInfo { | |
128 | /** | |
83fa0a36 | 129 | * Worker id. |
f59e1027 | 130 | */ |
eb7bf744 | 131 | readonly id: number | undefined |
4b628b48 JB |
132 | /** |
133 | * Worker type. | |
134 | */ | |
135 | 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 | */ | |
147 | taskFunctions?: string[] | |
f59e1027 JB |
148 | } |
149 | ||
a4e07f72 JB |
150 | /** |
151 | * Worker usage statistics. | |
152 | * | |
153 | * @internal | |
154 | */ | |
155 | export 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 | ||
174 | /** | |
175 | * Worker interface. | |
176 | */ | |
177 | export interface IWorker { | |
f59e1027 | 178 | /** |
83fa0a36 | 179 | * Worker id. |
f59e1027 | 180 | */ |
aecc6e48 JB |
181 | readonly id?: number |
182 | readonly threadId?: number | |
bdaf31cd | 183 | /** |
64383951 | 184 | * Registers an event listener. |
bdaf31cd | 185 | * |
38e795c1 | 186 | * @param event - The event. |
48ef9107 | 187 | * @param handler - The event handler. |
bdaf31cd | 188 | */ |
fd04474e JB |
189 | readonly on: ((event: 'online', handler: OnlineHandler<this>) => void) & |
190 | ((event: 'message', handler: MessageHandler<this>) => void) & | |
78cea37e | 191 | ((event: 'error', handler: ErrorHandler<this>) => void) & |
78cea37e | 192 | ((event: 'exit', handler: ExitHandler<this>) => void) |
bdaf31cd | 193 | /** |
64383951 | 194 | * Registers a listener to the exit event that will only be performed once. |
bdaf31cd | 195 | * |
9ece5893 | 196 | * @param event - The `'exit'` event. |
38e795c1 | 197 | * @param handler - The exit handler. |
bdaf31cd | 198 | */ |
4b628b48 | 199 | readonly once: (event: 'exit', handler: ExitHandler<this>) => void |
bdaf31cd | 200 | } |
f06e48d8 JB |
201 | |
202 | /** | |
203 | * Worker node interface. | |
c319c66b JB |
204 | * |
205 | * @typeParam Worker - Type of worker. | |
e102732c | 206 | * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data. |
c319c66b | 207 | * @internal |
f06e48d8 | 208 | */ |
4b628b48 | 209 | export interface IWorkerNode<Worker extends IWorker, Data = unknown> { |
c319c66b | 210 | /** |
ccd73e07 | 211 | * Worker. |
c319c66b | 212 | */ |
02706357 | 213 | readonly worker: Worker |
f59e1027 | 214 | /** |
ccd73e07 | 215 | * Worker info. |
f59e1027 | 216 | */ |
eb7bf744 | 217 | readonly info: WorkerInfo |
7884d183 | 218 | /** |
336e91c4 | 219 | * Message channel (worker_threads only). |
7884d183 JB |
220 | */ |
221 | readonly messageChannel?: MessageChannel | |
c319c66b | 222 | /** |
ccd73e07 | 223 | * Worker usage statistics. |
c319c66b | 224 | */ |
f59e1027 | 225 | usage: WorkerUsage |
20c6f652 JB |
226 | /** |
227 | * Tasks queue back pressure size. | |
228 | * This is the number of tasks that can be enqueued before the worker node has back pressure. | |
229 | */ | |
230 | tasksQueueBackPressureSize: number | |
72695f86 JB |
231 | /** |
232 | * Callback invoked when worker node tasks queue is back pressured. | |
233 | * | |
234 | * @param workerId - The worker id. | |
235 | */ | |
236 | onBackPressure?: (workerId: number) => void | |
dd951876 JB |
237 | /** |
238 | * Callback invoked when worker node tasks queue is empty. | |
239 | * | |
240 | * @param workerId - The worker id. | |
241 | */ | |
242 | onEmptyQueue?: (workerId: number) => void | |
c319c66b | 243 | /** |
ccd73e07 | 244 | * Tasks queue size. |
4b628b48 JB |
245 | * |
246 | * @returns The tasks queue size. | |
247 | */ | |
248 | readonly tasksQueueSize: () => number | |
249 | /** | |
ccd73e07 | 250 | * Enqueue task. |
4b628b48 JB |
251 | * |
252 | * @param task - The task to queue. | |
a1763c54 | 253 | * @returns The tasks queue size. |
4b628b48 JB |
254 | */ |
255 | readonly enqueueTask: (task: Task<Data>) => number | |
72695f86 JB |
256 | /** |
257 | * Prepends a task to the tasks queue. | |
258 | * | |
259 | * @param task - The task to prepend. | |
260 | * @returns The tasks queue size. | |
261 | */ | |
262 | readonly unshiftTask: (task: Task<Data>) => number | |
4b628b48 | 263 | /** |
ccd73e07 | 264 | * Dequeue task. |
4b628b48 JB |
265 | * |
266 | * @returns The dequeued task. | |
267 | */ | |
268 | readonly dequeueTask: () => Task<Data> | undefined | |
72695f86 JB |
269 | /** |
270 | * Pops a task from the tasks queue. | |
271 | * | |
272 | * @returns The popped task. | |
273 | */ | |
274 | readonly popTask: () => Task<Data> | undefined | |
4b628b48 | 275 | /** |
ccd73e07 | 276 | * Clears tasks queue. |
4b628b48 JB |
277 | */ |
278 | readonly clearTasksQueue: () => void | |
671d5154 | 279 | /** |
e2b31e32 | 280 | * Whether the worker node has back pressure (i.e. its tasks queue is full). |
671d5154 JB |
281 | * |
282 | * @returns `true` if the worker node has back pressure, `false` otherwise. | |
283 | */ | |
284 | readonly hasBackPressure: () => boolean | |
4b628b48 | 285 | /** |
ff469b0e | 286 | * Resets usage statistics. |
c319c66b | 287 | */ |
4b628b48 | 288 | readonly resetUsage: () => void |
3f09ed9f | 289 | /** |
a5d15204 | 290 | * Closes communication channel. |
3f09ed9f JB |
291 | */ |
292 | readonly closeChannel: () => void | |
ff128cc9 | 293 | /** |
2809112e JB |
294 | * Gets task function worker usage statistics. |
295 | * | |
296 | * @param name - The task function name. | |
297 | * @returns The task function worker usage statistics if the task function worker usage statistics are initialized, `undefined` otherwise. | |
ff128cc9 | 298 | */ |
db0e38ee | 299 | readonly getTaskFunctionWorkerUsage: (name: string) => WorkerUsage | undefined |
f06e48d8 | 300 | } |