1 import type { ClusterSettings
} from
'node:cluster'
2 import type { EventEmitterAsyncResource
} from
'node:events'
3 import type { TransferListItem
, WorkerOptions
} from
'node:worker_threads'
5 import type { TaskFunctionProperties
} from
'../utility-types.js'
9 } from
'../worker/task-functions.js'
12 WorkerChoiceStrategyOptions
,
13 } from
'./selection-strategies/selection-strategies-types.js'
25 * Enumeration of pool types.
27 export const PoolTypes
: Readonly
<{
44 export type PoolType
= keyof
typeof PoolTypes
47 * Enumeration of pool events.
49 export const PoolEvents
: Readonly
<{
56 taskError
: 'taskError'
57 backPressure
: 'backPressure'
65 taskError
: 'taskError',
66 backPressure
: 'backPressure',
72 export type PoolEvent
= keyof
typeof PoolEvents
77 export interface PoolInfo
{
78 readonly version
: string
79 readonly type: PoolType
80 readonly worker
: WorkerType
81 readonly started
: boolean
82 readonly ready
: boolean
83 readonly defaultStrategy
: WorkerChoiceStrategy
84 readonly strategyRetries
: number
85 readonly minSize
: number
86 readonly maxSize
: number
87 /** Pool utilization. */
88 readonly utilization
?: number
89 /** Pool total worker nodes. */
90 readonly workerNodes
: number
91 /** Pool stealing worker nodes. */
92 readonly stealingWorkerNodes
?: number
93 /** Pool idle worker nodes. */
94 readonly idleWorkerNodes
: number
95 /** Pool busy worker nodes. */
96 readonly busyWorkerNodes
: number
97 readonly executedTasks
: number
98 readonly executingTasks
: number
99 readonly queuedTasks
?: number
100 readonly maxQueuedTasks
?: number
101 readonly backPressure
?: boolean
102 readonly stolenTasks
?: number
103 readonly failedTasks
: number
105 readonly minimum
: number
106 readonly maximum
: number
107 readonly average
?: number
108 readonly median
?: number
110 readonly waitTime
?: {
111 readonly minimum
: number
112 readonly maximum
: number
113 readonly average
?: number
114 readonly median
?: number
118 readonly minimum
: number
119 readonly maximum
: number
120 readonly average
?: number
121 readonly median
?: number
124 readonly minimum
: number
125 readonly maximum
: number
126 readonly average
?: number
127 readonly median
?: number
130 readonly average
?: number
131 readonly median
?: number
137 * Worker node tasks queue options.
139 export interface TasksQueueOptions
{
141 * Maximum tasks queue size per worker node flagging it as back pressured.
142 * @defaultValue (pool maximum size)^2
144 readonly size
?: number
146 * Maximum number of tasks that can be executed concurrently on a worker node.
149 readonly concurrency
?: number
151 * Whether to enable task stealing on idle.
154 readonly taskStealing
?: boolean
156 * Whether to enable tasks stealing under back pressure.
157 * @defaultValue false
159 readonly tasksStealingOnBackPressure
?: boolean
161 * Queued tasks finished timeout in milliseconds at worker node termination.
164 readonly tasksFinishedTimeout
?: number
168 * Options for a poolifier pool.
169 * @typeParam Worker - Type of worker.
171 export interface PoolOptions
<Worker
extends IWorker
> {
173 * A function that will listen for online event on each worker.
174 * @defaultValue `() => {}`
176 onlineHandler
?: OnlineHandler
<Worker
>
178 * A function that will listen for message event on each worker.
179 * @defaultValue `() => {}`
181 messageHandler
?: MessageHandler
<Worker
>
183 * A function that will listen for error event on each worker.
184 * @defaultValue `() => {}`
186 errorHandler
?: ErrorHandler
<Worker
>
188 * A function that will listen for exit event on each worker.
189 * @defaultValue `() => {}`
191 exitHandler
?: ExitHandler
<Worker
>
193 * Whether to start the minimum number of workers at pool initialization.
196 startWorkers
?: boolean
198 * The default worker choice strategy to use in this pool.
199 * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
201 workerChoiceStrategy
?: WorkerChoiceStrategy
203 * The worker choice strategy options.
205 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
207 * Restart worker on error.
209 restartWorkerOnError
?: boolean
211 * Pool events integrated with async resource emission.
214 enableEvents
?: boolean
216 * Pool worker node tasks queue.
217 * @defaultValue false
219 enableTasksQueue
?: boolean
221 * Pool worker node tasks queue options.
223 tasksQueueOptions
?: TasksQueueOptions
226 * @see https://nodejs.org/api/worker_threads.html#new-workerfilename-options
228 workerOptions
?: WorkerOptions
230 * Key/value pairs to add to worker process environment.
231 * @see https://nodejs.org/api/cluster.html#cluster_cluster_fork_env
233 env
?: Record
<string, unknown
>
236 * @see https://nodejs.org/api/cluster.html#cluster_cluster_settings
238 settings
?: ClusterSettings
242 * Contract definition for a poolifier pool.
243 * @typeParam Worker - Type of worker which manages this pool.
244 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
245 * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
247 export interface IPool
<
248 Worker
extends IWorker
,
255 readonly info
: PoolInfo
260 readonly workerNodes
: IWorkerNode
<Worker
, Data
>[]
262 * Pool event emitter integrated with async resource.
263 * The async tracking tooling identifier is `poolifier:<PoolType>-<WorkerType>-pool`.
265 * Events that can currently be listened to:
267 * - `'ready'`: Emitted when the number of workers created in the pool has reached the minimum size expected and are ready. If the pool is dynamic with a minimum number of workers is set to zero, this event is emitted when at least one dynamic worker is ready.
268 * - `'busy'`: Emitted when the number of workers created in the pool has reached the maximum size expected and are executing concurrently their tasks quota.
269 * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected.
270 * - `'empty'`: Emitted when the pool is dynamic with a minimum number of workers set to zero and the number of workers has reached the minimum size expected.
271 * - `'destroy'`: Emitted when the pool is destroyed.
272 * - `'error'`: Emitted when an uncaught error occurs.
273 * - `'taskError'`: Emitted when an error occurs while executing a task.
274 * - `'backPressure'`: Emitted when all worker nodes have back pressure (i.e. their tasks queue is full: queue size \>= maximum queue size).
276 readonly emitter
?: EventEmitterAsyncResource
278 * Executes the specified function in the worker constructor with the task data input parameter.
279 * @param data - The optional task input data for the specified task function. This can only be structured-cloneable data.
280 * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed.
281 * @param transferList - An optional array of transferable objects to transfer ownership of. Ownership of the transferred objects is given to the chosen pool's worker_threads worker and they should not be used in the main thread afterwards.
282 * @returns Promise with a task function response that will be fulfilled when the task is completed.
287 transferList
?: readonly TransferListItem
[]
288 ) => Promise
<Response
>
290 * Executes the specified function in the worker constructor with the tasks data iterable input parameter.
291 * @param data - The tasks iterable input data for the specified task function. This can only be an iterable of structured-cloneable data.
292 * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed.
293 * @param transferList - An optional array of transferable objects to transfer ownership of. Ownership of the transferred objects is given to the chosen pool's worker_threads worker and they should not be used in the main thread afterwards.
294 * @returns Promise with an array of task function responses that will be fulfilled when the tasks are completed.
296 readonly mapExecute
: (
297 data
: Iterable
<Data
>,
299 transferList
?: readonly TransferListItem
[]
300 ) => Promise
<Response
[]>
302 * Starts the minimum number of workers in this pool.
304 readonly start
: () => void
306 * Terminates all workers in this pool.
308 readonly destroy
: () => Promise
<void>
310 * Whether the specified task function exists in this pool.
311 * @param name - The name of the task function.
312 * @returns `true` if the task function exists, `false` otherwise.
314 readonly hasTaskFunction
: (name
: string) => boolean
316 * Adds a task function to this pool.
317 * If a task function with the same name already exists, it will be overwritten.
318 * @param name - The name of the task function.
319 * @param fn - The task function.
320 * @returns `true` if the task function was added, `false` otherwise.
321 * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `name` parameter is not a string or an empty string.
322 * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `fn` parameter is not a function or task function object.
324 readonly addTaskFunction
: (
326 fn
: TaskFunction
<Data
, Response
> | TaskFunctionObject
<Data
, Response
>
327 ) => Promise
<boolean>
329 * Removes a task function from this pool.
330 * @param name - The name of the task function.
331 * @returns `true` if the task function was removed, `false` otherwise.
333 readonly removeTaskFunction
: (name
: string) => Promise
<boolean>
335 * Lists the properties of task functions available in this pool.
336 * @returns The properties of task functions available in this pool.
338 readonly listTaskFunctionsProperties
: () => TaskFunctionProperties
[]
340 * Sets the default task function in this pool.
341 * @param name - The name of the task function.
342 * @returns `true` if the default task function was set, `false` otherwise.
344 readonly setDefaultTaskFunction
: (name
: string) => Promise
<boolean>
346 * Sets the default worker choice strategy in this pool.
347 * @param workerChoiceStrategy - The default worker choice strategy.
348 * @param workerChoiceStrategyOptions - The worker choice strategy options.
350 readonly setWorkerChoiceStrategy
: (
351 workerChoiceStrategy
: WorkerChoiceStrategy
,
352 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
355 * Sets the worker choice strategy options in this pool.
356 * @param workerChoiceStrategyOptions - The worker choice strategy options.
357 * @returns `true` if the worker choice strategy options were set, `false` otherwise.
359 readonly setWorkerChoiceStrategyOptions
: (
360 workerChoiceStrategyOptions
: WorkerChoiceStrategyOptions
363 * Enables/disables the worker node tasks queue in this pool.
364 * @param enable - Whether to enable or disable the worker node tasks queue.
365 * @param tasksQueueOptions - The worker node tasks queue options.
367 readonly enableTasksQueue
: (
369 tasksQueueOptions
?: TasksQueueOptions
372 * Sets the worker node tasks queue options in this pool.
373 * @param tasksQueueOptions - The worker node tasks queue options.
375 readonly setTasksQueueOptions
: (tasksQueueOptions
: TasksQueueOptions
) => void