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
119 * Worker node tasks queue options.
121 export interface TasksQueueOptions
{
123 * Maximum tasks queue size per worker node flagging it as back pressured.
125 * @defaultValue (pool maximum size)^2
127 readonly size
?: number
129 * Maximum number of tasks that can be executed concurrently on a worker node.
133 readonly concurrency
?: number
135 * Whether to enable task stealing on idle.
139 readonly taskStealing
?: boolean
141 * Whether to enable tasks stealing under back pressure.
143 * @defaultValue false
145 readonly tasksStealingOnBackPressure
?: boolean
147 * Queued tasks finished timeout in milliseconds at worker node termination.
151 readonly tasksFinishedTimeout
?: number
155 * Options for a poolifier pool.
157 * @typeParam Worker - Type of worker.
159 export interface PoolOptions
<Worker
extends IWorker
> {
161 * A function that will listen for online event on each worker.
163 * @defaultValue `() => {}`
165 onlineHandler
?: OnlineHandler
<Worker
>
167 * A function that will listen for message event on each worker.
169 * @defaultValue `() => {}`
171 messageHandler
?: MessageHandler
<Worker
>
173 * A function that will listen for error event on each worker.
175 * @defaultValue `() => {}`
177 errorHandler
?: ErrorHandler
<Worker
>
179 * A function that will listen for exit event on each worker.
181 * @defaultValue `() => {}`
183 exitHandler
?: ExitHandler
<Worker
>
185 * Whether to start the minimum number of workers at pool initialization.
189 startWorkers
?: boolean
191 * The default worker choice strategy to use in this pool.
193 * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
195 workerChoiceStrategy
?: WorkerChoiceStrategy
197 * The worker choice strategy options.
199 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
201 * Restart worker on error.
203 restartWorkerOnError
?: boolean
205 * Pool events integrated with async resource emission.
209 enableEvents
?: boolean
211 * Pool worker node tasks queue.
213 * @defaultValue false
215 enableTasksQueue
?: boolean
217 * Pool worker node tasks queue options.
219 tasksQueueOptions
?: TasksQueueOptions
223 * @see https://nodejs.org/api/worker_threads.html#new-workerfilename-options
225 workerOptions
?: WorkerOptions
227 * Key/value pairs to add to worker process environment.
229 * @see https://nodejs.org/api/cluster.html#cluster_cluster_fork_env
231 env
?: Record
<string, unknown
>
235 * @see https://nodejs.org/api/cluster.html#cluster_cluster_settings
237 settings
?: ClusterSettings
241 * 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
261 readonly workerNodes
: Array<IWorkerNode
<Worker
, Data
>>
263 * Pool event emitter integrated with async resource.
264 * The async tracking tooling identifier is `poolifier:<PoolType>-<WorkerType>-pool`.
266 * Events that can currently be listened to:
268 * - `'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.
269 * - `'busy'`: Emitted when the number of workers created in the pool has reached the maximum size expected and are executing concurrently their tasks quota.
270 * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected.
271 * - `'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.
272 * - `'destroy'`: Emitted when the pool is destroyed.
273 * - `'error'`: Emitted when an uncaught error occurs.
274 * - `'taskError'`: Emitted when an error occurs while executing a task.
275 * - `'backPressure'`: Emitted when all worker nodes have back pressure (i.e. their tasks queue is full: queue size \>= maximum queue size).
277 readonly emitter
?: EventEmitterAsyncResource
279 * Executes the specified function in the worker constructor with the task data input parameter.
281 * @param data - The optional task input data for the specified task function. This can only be structured-cloneable data.
282 * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed.
283 * @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.
284 * @returns Promise that will be fulfilled when the task is completed.
289 transferList
?: readonly TransferListItem
[]
290 ) => Promise
<Response
>
292 * Starts the minimum number of workers in this pool.
294 readonly start
: () => void
296 * Terminates all workers in this pool.
298 readonly destroy
: () => Promise
<void>
300 * Whether the specified task function exists in this pool.
302 * @param name - The name of the task function.
303 * @returns `true` if the task function exists, `false` otherwise.
305 readonly hasTaskFunction
: (name
: string) => boolean
307 * Adds a task function to this pool.
308 * If a task function with the same name already exists, it will be overwritten.
310 * @param name - The name of the task function.
311 * @param fn - The task function.
312 * @returns `true` if the task function was added, `false` otherwise.
313 * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `name` parameter is not a string or an empty string.
314 * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `fn` parameter is not a function or task function object.
316 readonly addTaskFunction
: (
318 fn
: TaskFunction
<Data
, Response
> | TaskFunctionObject
<Data
, Response
>
319 ) => Promise
<boolean>
321 * Removes a task function from this pool.
323 * @param name - The name of the task function.
324 * @returns `true` if the task function was removed, `false` otherwise.
326 readonly removeTaskFunction
: (name
: string) => Promise
<boolean>
328 * Lists the properties of task functions available in this pool.
330 * @returns The properties of task functions available in this pool.
332 readonly listTaskFunctionsProperties
: () => TaskFunctionProperties
[]
334 * Sets the default task function in this pool.
336 * @param name - The name of the task function.
337 * @returns `true` if the default task function was set, `false` otherwise.
339 readonly setDefaultTaskFunction
: (name
: string) => Promise
<boolean>
341 * Sets the default worker choice strategy in this pool.
343 * @param workerChoiceStrategy - The default worker choice strategy.
344 * @param workerChoiceStrategyOptions - The worker choice strategy options.
346 readonly setWorkerChoiceStrategy
: (
347 workerChoiceStrategy
: WorkerChoiceStrategy
,
348 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
351 * Sets the worker choice strategy options in this pool.
353 * @param workerChoiceStrategyOptions - The worker choice strategy options.
354 * @returns `true` if the worker choice strategy options were set, `false` otherwise.
356 readonly setWorkerChoiceStrategyOptions
: (
357 workerChoiceStrategyOptions
: WorkerChoiceStrategyOptions
360 * Enables/disables the worker node tasks queue in this pool.
362 * @param enable - Whether to enable or disable the worker node tasks queue.
363 * @param tasksQueueOptions - The worker node tasks queue options.
365 readonly enableTasksQueue
: (
367 tasksQueueOptions
?: TasksQueueOptions
370 * Sets the worker node tasks queue options in this pool.
372 * @param tasksQueueOptions - The worker node tasks queue options.
374 readonly setTasksQueueOptions
: (tasksQueueOptions
: TasksQueueOptions
) => void