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. | |
138 | */ | |
139 | onlineHandler?: OnlineHandler<Worker> | |
bdaf31cd JB |
140 | /** |
141 | * A function that will listen for message event on each worker. | |
142 | */ | |
143 | messageHandler?: MessageHandler<Worker> | |
144 | /** | |
145 | * A function that will listen for error event on each worker. | |
146 | */ | |
147 | errorHandler?: ErrorHandler<Worker> | |
bdaf31cd JB |
148 | /** |
149 | * A function that will listen for exit event on each worker. | |
150 | */ | |
151 | exitHandler?: ExitHandler<Worker> | |
47352846 JB |
152 | /** |
153 | * Whether to start the minimum number of workers at pool initialization. | |
154 | * | |
155 | * @defaultValue false | |
156 | */ | |
157 | startWorkers?: boolean | |
bdaf31cd | 158 | /** |
46e857ca | 159 | * The worker choice strategy to use in this pool. |
d29bce7c | 160 | * |
95ec6006 | 161 | * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN |
bdaf31cd JB |
162 | */ |
163 | workerChoiceStrategy?: WorkerChoiceStrategy | |
da309861 JB |
164 | /** |
165 | * The worker choice strategy options. | |
166 | */ | |
167 | workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions | |
1f68cede JB |
168 | /** |
169 | * Restart worker on error. | |
170 | */ | |
171 | restartWorkerOnError?: boolean | |
bdaf31cd JB |
172 | /** |
173 | * Pool events emission. | |
174 | * | |
38e795c1 | 175 | * @defaultValue true |
bdaf31cd JB |
176 | */ |
177 | enableEvents?: boolean | |
ff733df7 | 178 | /** |
20c6f652 | 179 | * Pool worker node tasks queue. |
ff733df7 | 180 | * |
ff733df7 JB |
181 | * @defaultValue false |
182 | */ | |
183 | enableTasksQueue?: boolean | |
7171d33f | 184 | /** |
20c6f652 | 185 | * Pool worker node tasks queue options. |
7171d33f JB |
186 | */ |
187 | tasksQueueOptions?: TasksQueueOptions | |
bdaf31cd | 188 | } |
a35560ba | 189 | |
729c563d S |
190 | /** |
191 | * Contract definition for a poolifier pool. | |
192 | * | |
c4855468 | 193 | * @typeParam Worker - Type of worker which manages this pool. |
e102732c JB |
194 | * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data. |
195 | * @typeParam Response - Type of execution response. This can only be structured-cloneable data. | |
729c563d | 196 | */ |
c4855468 JB |
197 | export interface IPool< |
198 | Worker extends IWorker, | |
199 | Data = unknown, | |
200 | Response = unknown | |
201 | > { | |
08f3f44c | 202 | /** |
6b27d407 | 203 | * Pool information. |
08f3f44c | 204 | */ |
6b27d407 | 205 | readonly info: PoolInfo |
c4855468 JB |
206 | /** |
207 | * Pool worker nodes. | |
9768f49f JB |
208 | * |
209 | * @internal | |
c4855468 | 210 | */ |
4b628b48 | 211 | readonly workerNodes: Array<IWorkerNode<Worker, Data>> |
e2b31e32 JB |
212 | /** |
213 | * Whether the worker node has back pressure (i.e. its tasks queue is full). | |
214 | * | |
215 | * @param workerNodeKey - The worker node key. | |
216 | * @returns `true` if the worker node has back pressure, `false` otherwise. | |
9768f49f | 217 | * @internal |
e2b31e32 JB |
218 | */ |
219 | readonly hasWorkerNodeBackPressure: (workerNodeKey: number) => boolean | |
b4904890 JB |
220 | /** |
221 | * Emitter on which events can be listened to. | |
222 | * | |
223 | * Events that can currently be listened to: | |
224 | * | |
d5024c00 | 225 | * - `'ready'`: Emitted when the number of workers created in the pool has reached the minimum size expected and are ready. |
a9780ad2 | 226 | * - `'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 | 227 | * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected. |
033f1776 | 228 | * - `'destroy'`: Emitted when the pool is destroyed. |
91ee39ed JB |
229 | * - `'error'`: Emitted when an uncaught error occurs. |
230 | * - `'taskError'`: Emitted when an error occurs while executing a task. | |
d92f3ddf | 231 | * - `'backPressure'`: Emitted when all worker nodes have back pressure (i.e. their tasks queue is full: queue size \>= maximum queue size). |
b4904890 JB |
232 | */ |
233 | readonly emitter?: PoolEmitter | |
729c563d | 234 | /** |
61aa11a6 | 235 | * Executes the specified function in the worker constructor with the task data input parameter. |
729c563d | 236 | * |
7d91a8cd JB |
237 | * @param data - The optional task input data for the specified task function. This can only be structured-cloneable data. |
238 | * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed. | |
239 | * @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 | 240 | * @returns Promise that will be fulfilled when the task is completed. |
729c563d | 241 | */ |
7d91a8cd JB |
242 | readonly execute: ( |
243 | data?: Data, | |
244 | name?: string, | |
245 | transferList?: TransferListItem[] | |
246 | ) => Promise<Response> | |
47352846 JB |
247 | /** |
248 | * Starts the minimum number of workers in this pool. | |
249 | */ | |
250 | readonly start: () => void | |
280c2a77 | 251 | /** |
aa9eede8 | 252 | * Terminates all workers in this pool. |
280c2a77 | 253 | */ |
4b628b48 | 254 | readonly destroy: () => Promise<void> |
90d7d101 JB |
255 | /** |
256 | * Lists the names of task function available in this pool. | |
257 | * | |
258 | * @returns The names of task function available in this pool. | |
259 | */ | |
260 | readonly listTaskFunctions: () => string[] | |
a35560ba | 261 | /** |
bdede008 | 262 | * Sets the worker choice strategy in this pool. |
a35560ba | 263 | * |
38e795c1 | 264 | * @param workerChoiceStrategy - The worker choice strategy. |
59219cbb | 265 | * @param workerChoiceStrategyOptions - The worker choice strategy options. |
a35560ba | 266 | */ |
4b628b48 | 267 | readonly setWorkerChoiceStrategy: ( |
59219cbb JB |
268 | workerChoiceStrategy: WorkerChoiceStrategy, |
269 | workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions | |
270 | ) => void | |
a20f0ba5 JB |
271 | /** |
272 | * Sets the worker choice strategy options in this pool. | |
273 | * | |
274 | * @param workerChoiceStrategyOptions - The worker choice strategy options. | |
275 | */ | |
4b628b48 | 276 | readonly setWorkerChoiceStrategyOptions: ( |
a20f0ba5 JB |
277 | workerChoiceStrategyOptions: WorkerChoiceStrategyOptions |
278 | ) => void | |
279 | /** | |
20c6f652 | 280 | * Enables/disables the worker node tasks queue in this pool. |
a20f0ba5 | 281 | * |
20c6f652 JB |
282 | * @param enable - Whether to enable or disable the worker node tasks queue. |
283 | * @param tasksQueueOptions - The worker node tasks queue options. | |
a20f0ba5 | 284 | */ |
4b628b48 | 285 | readonly enableTasksQueue: ( |
8f52842f JB |
286 | enable: boolean, |
287 | tasksQueueOptions?: TasksQueueOptions | |
288 | ) => void | |
a20f0ba5 | 289 | /** |
20c6f652 | 290 | * Sets the worker node tasks queue options in this pool. |
a20f0ba5 | 291 | * |
20c6f652 | 292 | * @param tasksQueueOptions - The worker node tasks queue options. |
a20f0ba5 | 293 | */ |
4b628b48 | 294 | readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void |
c97c7edb | 295 | } |