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