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