Commit | Line | Data |
---|---|---|
ded253e2 | 1 | import type { AsyncResource } from 'node:async_hooks' |
62c15a68 | 2 | import type { EventLoopUtilization } from 'node:perf_hooks' |
7d91a8cd | 3 | import type { MessagePort, TransferListItem } from 'node:worker_threads' |
ded253e2 | 4 | |
31847469 | 5 | import type { WorkerChoiceStrategy } from './pools/selection-strategies/selection-strategies-types.js' |
d35e5717 | 6 | import type { KillBehavior } from './worker/worker-options.js' |
838898f1 | 7 | |
213e817d | 8 | /** |
6703b9f4 | 9 | * Worker error. |
e102732c | 10 | * @typeParam Data - Type of data sent to the worker triggering an error. This can only be structured-cloneable data. |
213e817d | 11 | */ |
6703b9f4 | 12 | export interface WorkerError<Data = unknown> { |
ff128cc9 | 13 | /** |
6703b9f4 | 14 | * Task function name triggering the error. |
ff128cc9 JB |
15 | */ |
16 | readonly name: string | |
82f36766 JB |
17 | /** |
18 | * Error message. | |
19 | */ | |
eb7bf744 | 20 | readonly message: string |
82f36766 | 21 | /** |
ff128cc9 | 22 | * Data triggering the error. |
82f36766 | 23 | */ |
eb7bf744 | 24 | readonly data?: Data |
82f36766 JB |
25 | } |
26 | ||
d715b7bc JB |
27 | /** |
28 | * Task performance. | |
f03062df | 29 | * @internal |
d715b7bc JB |
30 | */ |
31 | export interface TaskPerformance { | |
197b4aa5 JB |
32 | /** |
33 | * Task name. | |
34 | */ | |
35 | readonly name: string | |
d715b7bc JB |
36 | /** |
37 | * Task performance timestamp. | |
38 | */ | |
eb7bf744 | 39 | readonly timestamp: number |
d715b7bc JB |
40 | /** |
41 | * Task runtime. | |
42 | */ | |
eb7bf744 | 43 | readonly runTime?: number |
d715b7bc JB |
44 | /** |
45 | * Task event loop utilization. | |
46 | */ | |
eb7bf744 | 47 | readonly elu?: EventLoopUtilization |
d715b7bc JB |
48 | } |
49 | ||
b6b32453 | 50 | /** |
5b49e864 | 51 | * Worker task performance statistics computation settings. |
f03062df | 52 | * @internal |
b6b32453 JB |
53 | */ |
54 | export interface WorkerStatistics { | |
5b49e864 JB |
55 | /** |
56 | * Whether the worker computes the task runtime or not. | |
57 | */ | |
58 | readonly runTime: boolean | |
59 | /** | |
60 | * Whether the worker computes the task event loop utilization (ELU) or not. | |
61 | */ | |
62 | readonly elu: boolean | |
b6b32453 JB |
63 | } |
64 | ||
31847469 JB |
65 | /** |
66 | * Task function properties. | |
31847469 JB |
67 | */ |
68 | export interface TaskFunctionProperties { | |
69 | /** | |
70 | * Task function name. | |
71 | */ | |
2be9b405 | 72 | readonly name: string |
31847469 JB |
73 | /** |
74 | * Task function priority. Lower values have higher priority. | |
75 | */ | |
2be9b405 | 76 | readonly priority?: number |
31847469 JB |
77 | /** |
78 | * Task function worker choice strategy. | |
79 | */ | |
2be9b405 | 80 | readonly strategy?: WorkerChoiceStrategy |
31847469 JB |
81 | } |
82 | ||
5c4d16da JB |
83 | /** |
84 | * Message object that is passed as a task between main worker and worker. | |
5c4d16da JB |
85 | * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data. |
86 | * @internal | |
87 | */ | |
88 | export interface Task<Data = unknown> { | |
5c4d16da JB |
89 | /** |
90 | * Task name. | |
91 | */ | |
92 | readonly name?: string | |
93 | /** | |
94 | * Task input data that will be passed to the worker. | |
95 | */ | |
96 | readonly data?: Data | |
95d1a734 JB |
97 | /** |
98 | * Task priority. Lower values have higher priority. | |
95d1a734 JB |
99 | * @defaultValue 0 |
100 | */ | |
101 | readonly priority?: number | |
102 | /** | |
103 | * Task worker choice strategy. | |
104 | */ | |
105 | readonly strategy?: WorkerChoiceStrategy | |
7d91a8cd JB |
106 | /** |
107 | * Array of transferable objects. | |
108 | */ | |
6a3ecc50 | 109 | readonly transferList?: readonly TransferListItem[] |
5c4d16da JB |
110 | /** |
111 | * Timestamp. | |
112 | */ | |
113 | readonly timestamp?: number | |
114 | /** | |
7629bdf1 | 115 | * Task UUID. |
5c4d16da | 116 | */ |
95d1a734 | 117 | readonly taskId?: `${string}-${string}-${string}-${string}-${string}` |
5c4d16da JB |
118 | } |
119 | ||
729c563d | 120 | /** |
02706357 | 121 | * Message object that is passed between main worker and worker. |
e102732c JB |
122 | * @typeParam Data - Type of data sent to the worker or execution response. This can only be structured-cloneable data. |
123 | * @typeParam ErrorData - Type of data sent to the worker triggering an error. This can only be structured-cloneable data. | |
71ebe93b | 124 | * @internal |
729c563d | 125 | */ |
6677a3d3 JB |
126 | export interface MessageValue<Data = unknown, ErrorData = unknown> |
127 | extends Task<Data> { | |
7379799c JB |
128 | /** |
129 | * Worker id. | |
130 | */ | |
131 | readonly workerId?: number | |
729c563d S |
132 | /** |
133 | * Kill code. | |
134 | */ | |
1e3214b6 | 135 | readonly kill?: KillBehavior | true | 'success' | 'failure' |
729c563d | 136 | /** |
6703b9f4 | 137 | * Worker error. |
729c563d | 138 | */ |
6703b9f4 | 139 | readonly workerError?: WorkerError<ErrorData> |
bf9549ae | 140 | /** |
d715b7bc | 141 | * Task performance. |
62c15a68 | 142 | */ |
d715b7bc | 143 | readonly taskPerformance?: TaskPerformance |
6703b9f4 JB |
144 | /** |
145 | * Task function operation: | |
6703b9f4 | 146 | * - `'add'` - Add a task function. |
16248b23 | 147 | * - `'remove'` - Remove a task function. |
6703b9f4 JB |
148 | * - `'default'` - Set a task function as default. |
149 | */ | |
edbc15c6 JB |
150 | readonly taskFunctionOperation?: 'add' | 'remove' | 'default' |
151 | /** | |
152 | * Whether the task function operation is successful or not. | |
153 | */ | |
6703b9f4 JB |
154 | readonly taskFunctionOperationStatus?: boolean |
155 | /** | |
31847469 | 156 | * Task function properties. |
6703b9f4 | 157 | */ |
31847469 | 158 | readonly taskFunctionProperties?: TaskFunctionProperties |
6703b9f4 | 159 | /** |
31847469 | 160 | * Task function serialized to string. |
6703b9f4 | 161 | */ |
31847469 | 162 | readonly taskFunction?: string |
90d7d101 | 163 | /** |
31847469 | 164 | * Task functions properties. |
90d7d101 | 165 | */ |
31847469 | 166 | readonly taskFunctionsProperties?: TaskFunctionProperties[] |
b6b32453 | 167 | /** |
f59e1027 | 168 | * Whether the worker computes the given statistics or not. |
b6b32453 JB |
169 | */ |
170 | readonly statistics?: WorkerStatistics | |
f59e1027 | 171 | /** |
7c8381eb | 172 | * Whether the worker is ready or not. |
f59e1027 | 173 | */ |
7c8381eb | 174 | readonly ready?: boolean |
75d3401a | 175 | /** |
b0a4db63 | 176 | * Whether the worker starts or stops its activity check. |
75d3401a | 177 | */ |
b0a4db63 | 178 | readonly checkActive?: boolean |
85aeb3f3 JB |
179 | /** |
180 | * Message port. | |
181 | */ | |
182 | readonly port?: MessagePort | |
325f50bc | 183 | } |
be0676b3 APA |
184 | |
185 | /** | |
e5d3809a | 186 | * An object holding the task execution response promise resolve/reject callbacks. |
e102732c | 187 | * @typeParam Response - Type of execution response. This can only be structured-cloneable data. |
c319c66b | 188 | * @internal |
be0676b3 | 189 | */ |
501aea93 | 190 | export interface PromiseResponseWrapper<Response = unknown> { |
be0676b3 APA |
191 | /** |
192 | * Resolve callback to fulfill the promise. | |
193 | */ | |
d2c73f82 | 194 | readonly resolve: (value: Response | PromiseLike<Response>) => void |
be0676b3 APA |
195 | /** |
196 | * Reject callback to reject the promise. | |
197 | */ | |
d2c73f82 | 198 | readonly reject: (reason?: unknown) => void |
be0676b3 | 199 | /** |
e5d3809a | 200 | * The worker node key executing the task. |
be0676b3 | 201 | */ |
501aea93 | 202 | readonly workerNodeKey: number |
f18fd12b JB |
203 | /** |
204 | * The asynchronous resource used to track the task execution. | |
205 | */ | |
206 | readonly asyncResource?: AsyncResource | |
be0676b3 | 207 | } |
ff3f866a | 208 | |
097dea68 JB |
209 | /** |
210 | * Remove readonly modifier from all properties of T. | |
211 | * @typeParam T - Type to remove readonly modifier. | |
212 | * @internal | |
213 | */ | |
ff3f866a | 214 | export type Writable<T> = { -readonly [P in keyof T]: T[P] } |
097dea68 JB |
215 | |
216 | /** | |
217 | * Default queue size. | |
218 | * @internal | |
219 | */ | |
220 | export const defaultQueueSize = 2048 | |
221 | ||
222 | /** | |
223 | * Fixed queue node. | |
224 | * @typeParam T - Type of fixed queue node data. | |
225 | * @internal | |
226 | */ | |
227 | export interface FixedQueueNode<T> { | |
228 | data: T | |
229 | priority: number | |
230 | } | |
231 | ||
232 | /** | |
233 | * Fixed queue. | |
234 | * @typeParam T - Type of fixed queue data. | |
235 | * @internal | |
236 | */ | |
237 | export interface IFixedQueue<T> { | |
238 | /** The fixed queue capacity. */ | |
239 | readonly capacity: number | |
240 | /** The fixed queue size. */ | |
241 | readonly size: number | |
242 | /** The fixed queue node array. */ | |
243 | nodeArray: FixedQueueNode<T>[] | |
244 | /** | |
245 | * Checks if the fixed queue is empty. | |
246 | * @returns `true` if the fixed queue is empty, `false` otherwise. | |
247 | */ | |
9183b880 | 248 | empty: () => boolean |
097dea68 JB |
249 | /** |
250 | * Checks if the fixed queue is full. | |
251 | * @returns `true` if the fixed queue is full, `false` otherwise. | |
252 | */ | |
9183b880 | 253 | full: () => boolean |
097dea68 JB |
254 | /** |
255 | * Enqueue data into the fixed queue. | |
256 | * @param data - Data to enqueue. | |
257 | * @param priority - Priority of the data. Lower values have higher priority. | |
258 | * @returns The new size of the fixed queue. | |
259 | * @throws If the fixed queue is full. | |
260 | */ | |
9183b880 | 261 | enqueue: (data: T, priority?: number) => number |
097dea68 JB |
262 | /** |
263 | * Gets data from the fixed queue. | |
264 | * @param index - The index of the data to get. | |
265 | * @returns The data at the index or `undefined` if the fixed queue is empty or the index is out of bounds. | |
266 | */ | |
9183b880 | 267 | get: (index: number) => T | undefined |
097dea68 JB |
268 | /** |
269 | * Dequeue data from the fixed queue. | |
270 | * @returns The dequeued data or `undefined` if the fixed queue is empty. | |
271 | */ | |
9183b880 | 272 | dequeue: () => T | undefined |
097dea68 JB |
273 | /** |
274 | * Clears the fixed queue. | |
275 | */ | |
9183b880 | 276 | clear: () => void |
097dea68 JB |
277 | /** |
278 | * Returns an iterator for the fixed queue. | |
279 | * @returns An iterator for the fixed queue. | |
280 | * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols | |
281 | */ | |
9183b880 | 282 | [Symbol.iterator]: () => Iterator<T> |
097dea68 JB |
283 | } |
284 | ||
285 | /** | |
286 | * Default bucket size. | |
287 | * @internal | |
288 | */ | |
289 | export const defaultBucketSize = 2048 | |
290 | ||
291 | /** | |
292 | * Priority queue node. | |
293 | * @typeParam T - Type of priority queue node data. | |
294 | * @internal | |
295 | */ | |
296 | export interface PriorityQueueNode<T> extends IFixedQueue<T> { | |
297 | next?: IFixedQueue<T> | |
298 | } |