Commit | Line | Data |
---|---|---|
2845f2a5 | 1 | import { EventEmitter } from 'node:events' |
7d91a8cd | 2 | import { type TransferListItem } from 'node:worker_threads' |
bdaf31cd JB |
3 | import type { |
4 | ErrorHandler, | |
5 | ExitHandler, | |
50e66724 | 6 | IWorker, |
4b628b48 | 7 | IWorkerNode, |
bdaf31cd | 8 | MessageHandler, |
c4855468 | 9 | OnlineHandler, |
4b628b48 | 10 | WorkerType |
f06e48d8 | 11 | } from './worker' |
da309861 JB |
12 | import type { |
13 | WorkerChoiceStrategy, | |
14 | WorkerChoiceStrategyOptions | |
15 | } from './selection-strategies/selection-strategies-types' | |
bdaf31cd | 16 | |
c4855468 | 17 | /** |
6b27d407 | 18 | * Enumeration of pool types. |
c4855468 | 19 | */ |
6b27d407 | 20 | export const PoolTypes = Object.freeze({ |
c4855468 JB |
21 | /** |
22 | * Fixed pool type. | |
23 | */ | |
6b27d407 | 24 | fixed: 'fixed', |
c4855468 JB |
25 | /** |
26 | * Dynamic pool type. | |
27 | */ | |
6b27d407 JB |
28 | dynamic: 'dynamic' |
29 | } as const) | |
30 | ||
31 | /** | |
32 | * Pool type. | |
33 | */ | |
34 | export type PoolType = keyof typeof PoolTypes | |
c4855468 | 35 | |
b4904890 JB |
36 | /** |
37 | * Pool events emitter. | |
38 | */ | |
2845f2a5 | 39 | export class PoolEmitter extends EventEmitter {} |
b4904890 | 40 | |
aee46736 JB |
41 | /** |
42 | * Enumeration of pool events. | |
43 | */ | |
44 | export const PoolEvents = Object.freeze({ | |
2431bdb4 | 45 | ready: 'ready', |
1f68cede | 46 | busy: 'busy', |
ef3891a3 JB |
47 | full: 'full', |
48 | destroy: 'destroy', | |
91ee39ed | 49 | error: 'error', |
671d5154 JB |
50 | taskError: 'taskError', |
51 | backPressure: 'backPressure' | |
aee46736 JB |
52 | } as const) |
53 | ||
54 | /** | |
55 | * Pool event. | |
56 | */ | |
57 | export type PoolEvent = keyof typeof PoolEvents | |
58 | ||
6b27d407 JB |
59 | /** |
60 | * Pool information. | |
61 | */ | |
62 | export interface PoolInfo { | |
4b628b48 JB |
63 | readonly version: string |
64 | readonly type: PoolType | |
65 | readonly worker: WorkerType | |
47352846 | 66 | readonly started: boolean |
2431bdb4 JB |
67 | readonly ready: boolean |
68 | readonly strategy: WorkerChoiceStrategy | |
4b628b48 JB |
69 | readonly minSize: number |
70 | readonly maxSize: number | |
aa9eede8 | 71 | /** Pool utilization. */ |
4b628b48 | 72 | readonly utilization?: number |
01a59f3c | 73 | /** Pool total worker nodes. */ |
4b628b48 | 74 | readonly workerNodes: number |
01a59f3c | 75 | /** Pool idle worker nodes. */ |
4b628b48 | 76 | readonly idleWorkerNodes: number |
01a59f3c | 77 | /** Pool busy worker nodes. */ |
4b628b48 JB |
78 | readonly busyWorkerNodes: number |
79 | readonly executedTasks: number | |
80 | readonly executingTasks: number | |
daf86646 JB |
81 | readonly queuedTasks?: number |
82 | readonly maxQueuedTasks?: number | |
a1763c54 | 83 | readonly backPressure?: boolean |
68cbdc84 | 84 | readonly stolenTasks?: number |
4b628b48 JB |
85 | readonly failedTasks: number |
86 | readonly runTime?: { | |
87 | readonly minimum: number | |
88 | readonly maximum: number | |
3baa0837 | 89 | readonly average?: number |
4b628b48 | 90 | readonly median?: number |
1dcf8b7b | 91 | } |
4b628b48 JB |
92 | readonly waitTime?: { |
93 | readonly minimum: number | |
94 | readonly maximum: number | |
3baa0837 | 95 | readonly average?: number |
4b628b48 | 96 | readonly median?: number |
1dcf8b7b | 97 | } |
6b27d407 JB |
98 | } |
99 | ||
7171d33f | 100 | /** |
20c6f652 | 101 | * Worker node tasks queue options. |
7171d33f JB |
102 | */ |
103 | export interface TasksQueueOptions { | |
104 | /** | |
20c6f652 JB |
105 | * Maximum tasks queue size per worker node flagging it as back pressured. |
106 | * | |
107 | * @defaultValue (pool maximum size)^2 | |
108 | */ | |
ff3f866a | 109 | readonly size?: number |
20c6f652 JB |
110 | /** |
111 | * Maximum number of tasks that can be executed concurrently on a worker node. | |
7171d33f JB |
112 | * |
113 | * @defaultValue 1 | |
114 | */ | |
eb7bf744 | 115 | readonly concurrency?: number |
47352846 | 116 | /** |
dbd73092 | 117 | * Whether to enable task stealing. |
47352846 JB |
118 | * |
119 | * @defaultValue true | |
120 | */ | |
dbd73092 | 121 | readonly taskStealing?: boolean |
47352846 JB |
122 | /** |
123 | * Whether to enable tasks stealing on back pressure. | |
124 | * | |
125 | * @defaultValue true | |
126 | */ | |
127 | readonly tasksStealingOnBackPressure?: boolean | |
7171d33f JB |
128 | } |
129 | ||
bdaf31cd JB |
130 | /** |
131 | * Options for a poolifier pool. | |
c319c66b | 132 | * |
d480d708 | 133 | * @typeParam Worker - Type of worker. |
bdaf31cd | 134 | */ |
50e66724 | 135 | export interface PoolOptions<Worker extends IWorker> { |
fd04474e JB |
136 | /** |
137 | * A function that will listen for online event on each worker. | |
68f1f531 JB |
138 | * |
139 | * @defaultValue `() => {}` | |
fd04474e JB |
140 | */ |
141 | onlineHandler?: OnlineHandler<Worker> | |
bdaf31cd JB |
142 | /** |
143 | * A function that will listen for message event on each worker. | |
68f1f531 JB |
144 | * |
145 | * @defaultValue `() => {}` | |
bdaf31cd JB |
146 | */ |
147 | messageHandler?: MessageHandler<Worker> | |
148 | /** | |
149 | * A function that will listen for error event on each worker. | |
68f1f531 JB |
150 | * |
151 | * @defaultValue `() => {}` | |
bdaf31cd JB |
152 | */ |
153 | errorHandler?: ErrorHandler<Worker> | |
bdaf31cd JB |
154 | /** |
155 | * A function that will listen for exit event on each worker. | |
68f1f531 JB |
156 | * |
157 | * @defaultValue `() => {}` | |
bdaf31cd JB |
158 | */ |
159 | exitHandler?: ExitHandler<Worker> | |
47352846 JB |
160 | /** |
161 | * Whether to start the minimum number of workers at pool initialization. | |
162 | * | |
8ff61e33 | 163 | * @defaultValue true |
47352846 JB |
164 | */ |
165 | startWorkers?: boolean | |
bdaf31cd | 166 | /** |
46e857ca | 167 | * The worker choice strategy to use in this pool. |
d29bce7c | 168 | * |
95ec6006 | 169 | * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN |
bdaf31cd JB |
170 | */ |
171 | workerChoiceStrategy?: WorkerChoiceStrategy | |
da309861 JB |
172 | /** |
173 | * The worker choice strategy options. | |
174 | */ | |
175 | workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions | |
1f68cede JB |
176 | /** |
177 | * Restart worker on error. | |
178 | */ | |
179 | restartWorkerOnError?: boolean | |
bdaf31cd JB |
180 | /** |
181 | * Pool events emission. | |
182 | * | |
38e795c1 | 183 | * @defaultValue true |
bdaf31cd JB |
184 | */ |
185 | enableEvents?: boolean | |
ff733df7 | 186 | /** |
20c6f652 | 187 | * Pool worker node tasks queue. |
ff733df7 | 188 | * |
ff733df7 JB |
189 | * @defaultValue false |
190 | */ | |
191 | enableTasksQueue?: boolean | |
7171d33f | 192 | /** |
20c6f652 | 193 | * Pool worker node tasks queue options. |
7171d33f JB |
194 | */ |
195 | tasksQueueOptions?: TasksQueueOptions | |
bdaf31cd | 196 | } |
a35560ba | 197 | |
729c563d S |
198 | /** |
199 | * Contract definition for a poolifier pool. | |
200 | * | |
c4855468 | 201 | * @typeParam Worker - Type of worker which manages this pool. |
e102732c JB |
202 | * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data. |
203 | * @typeParam Response - Type of execution response. This can only be structured-cloneable data. | |
729c563d | 204 | */ |
c4855468 JB |
205 | export interface IPool< |
206 | Worker extends IWorker, | |
207 | Data = unknown, | |
208 | Response = unknown | |
209 | > { | |
08f3f44c | 210 | /** |
6b27d407 | 211 | * Pool information. |
08f3f44c | 212 | */ |
6b27d407 | 213 | readonly info: PoolInfo |
c4855468 JB |
214 | /** |
215 | * Pool worker nodes. | |
9768f49f JB |
216 | * |
217 | * @internal | |
c4855468 | 218 | */ |
4b628b48 | 219 | readonly workerNodes: Array<IWorkerNode<Worker, Data>> |
e2b31e32 JB |
220 | /** |
221 | * Whether the worker node has back pressure (i.e. its tasks queue is full). | |
222 | * | |
223 | * @param workerNodeKey - The worker node key. | |
224 | * @returns `true` if the worker node has back pressure, `false` otherwise. | |
9768f49f | 225 | * @internal |
e2b31e32 JB |
226 | */ |
227 | readonly hasWorkerNodeBackPressure: (workerNodeKey: number) => boolean | |
b4904890 JB |
228 | /** |
229 | * Emitter on which events can be listened to. | |
230 | * | |
231 | * Events that can currently be listened to: | |
232 | * | |
d5024c00 | 233 | * - `'ready'`: Emitted when the number of workers created in the pool has reached the minimum size expected and are ready. |
a9780ad2 | 234 | * - `'busy'`: Emitted when the number of workers created in the pool has reached the maximum size expected and are executing concurrently their tasks quota. |
ef3891a3 | 235 | * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected. |
033f1776 | 236 | * - `'destroy'`: Emitted when the pool is destroyed. |
91ee39ed JB |
237 | * - `'error'`: Emitted when an uncaught error occurs. |
238 | * - `'taskError'`: Emitted when an error occurs while executing a task. | |
d92f3ddf | 239 | * - `'backPressure'`: Emitted when all worker nodes have back pressure (i.e. their tasks queue is full: queue size \>= maximum queue size). |
b4904890 JB |
240 | */ |
241 | readonly emitter?: PoolEmitter | |
729c563d | 242 | /** |
61aa11a6 | 243 | * Executes the specified function in the worker constructor with the task data input parameter. |
729c563d | 244 | * |
7d91a8cd JB |
245 | * @param data - The optional task input data for the specified task function. This can only be structured-cloneable data. |
246 | * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed. | |
247 | * @param transferList - An optional array of transferable objects to transfer ownership of. Ownership of the transferred objects is given to the pool's worker_threads worker and they should not be used in the main thread afterwards. | |
ef41a6e6 | 248 | * @returns Promise that will be fulfilled when the task is completed. |
729c563d | 249 | */ |
7d91a8cd JB |
250 | readonly execute: ( |
251 | data?: Data, | |
252 | name?: string, | |
253 | transferList?: TransferListItem[] | |
254 | ) => Promise<Response> | |
47352846 JB |
255 | /** |
256 | * Starts the minimum number of workers in this pool. | |
257 | */ | |
258 | readonly start: () => void | |
280c2a77 | 259 | /** |
aa9eede8 | 260 | * Terminates all workers in this pool. |
280c2a77 | 261 | */ |
4b628b48 | 262 | readonly destroy: () => Promise<void> |
90d7d101 JB |
263 | /** |
264 | * Lists the names of task function available in this pool. | |
265 | * | |
266 | * @returns The names of task function available in this pool. | |
267 | */ | |
268 | readonly listTaskFunctions: () => string[] | |
a35560ba | 269 | /** |
bdede008 | 270 | * Sets the worker choice strategy in this pool. |
a35560ba | 271 | * |
38e795c1 | 272 | * @param workerChoiceStrategy - The worker choice strategy. |
59219cbb | 273 | * @param workerChoiceStrategyOptions - The worker choice strategy options. |
a35560ba | 274 | */ |
4b628b48 | 275 | readonly setWorkerChoiceStrategy: ( |
59219cbb JB |
276 | workerChoiceStrategy: WorkerChoiceStrategy, |
277 | workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions | |
278 | ) => void | |
a20f0ba5 JB |
279 | /** |
280 | * Sets the worker choice strategy options in this pool. | |
281 | * | |
282 | * @param workerChoiceStrategyOptions - The worker choice strategy options. | |
283 | */ | |
4b628b48 | 284 | readonly setWorkerChoiceStrategyOptions: ( |
a20f0ba5 JB |
285 | workerChoiceStrategyOptions: WorkerChoiceStrategyOptions |
286 | ) => void | |
287 | /** | |
20c6f652 | 288 | * Enables/disables the worker node tasks queue in this pool. |
a20f0ba5 | 289 | * |
20c6f652 JB |
290 | * @param enable - Whether to enable or disable the worker node tasks queue. |
291 | * @param tasksQueueOptions - The worker node tasks queue options. | |
a20f0ba5 | 292 | */ |
4b628b48 | 293 | readonly enableTasksQueue: ( |
8f52842f JB |
294 | enable: boolean, |
295 | tasksQueueOptions?: TasksQueueOptions | |
296 | ) => void | |
a20f0ba5 | 297 | /** |
20c6f652 | 298 | * Sets the worker node tasks queue options in this pool. |
a20f0ba5 | 299 | * |
20c6f652 | 300 | * @param tasksQueueOptions - The worker node tasks queue options. |
a20f0ba5 | 301 | */ |
4b628b48 | 302 | readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void |
c97c7edb | 303 | } |