1 import type { TransferListItem
, WorkerOptions
} from
'node:worker_threads'
2 import type { EventEmitterAsyncResource
} from
'node:events'
3 import type { ClusterSettings
} from
'node:cluster'
4 import type { TaskFunction
} from
'../worker/task-functions.js'
16 WorkerChoiceStrategyOptions
17 } from
'./selection-strategies/selection-strategies-types.js'
20 * Enumeration of pool types.
22 export const PoolTypes
= Object.freeze({
36 export type PoolType
= keyof
typeof PoolTypes
39 * Enumeration of pool events.
41 export const PoolEvents
= Object.freeze({
48 taskError
: 'taskError',
49 backPressure
: 'backPressure'
55 export type PoolEvent
= keyof
typeof PoolEvents
60 export interface PoolInfo
{
61 readonly version
: string
62 readonly type: PoolType
63 readonly worker
: WorkerType
64 readonly started
: boolean
65 readonly ready
: boolean
66 readonly strategy
: WorkerChoiceStrategy
67 readonly minSize
: number
68 readonly maxSize
: number
69 /** Pool utilization. */
70 readonly utilization
?: number
71 /** Pool total worker nodes. */
72 readonly workerNodes
: number
73 /** Pool stealing worker nodes. */
74 readonly stealingWorkerNodes
?: number
75 /** Pool idle worker nodes. */
76 readonly idleWorkerNodes
: number
77 /** Pool busy worker nodes. */
78 readonly busyWorkerNodes
: number
79 readonly executedTasks
: number
80 readonly executingTasks
: number
81 readonly queuedTasks
?: number
82 readonly maxQueuedTasks
?: number
83 readonly backPressure
?: boolean
84 readonly stolenTasks
?: number
85 readonly failedTasks
: number
87 readonly minimum
: number
88 readonly maximum
: number
89 readonly average
?: number
90 readonly median
?: number
93 readonly minimum
: number
94 readonly maximum
: number
95 readonly average
?: number
96 readonly median
?: number
101 * Worker node tasks queue options.
103 export interface TasksQueueOptions
{
105 * Maximum tasks queue size per worker node flagging it as back pressured.
107 * @defaultValue (pool maximum size)^2
109 readonly size
?: number
111 * Maximum number of tasks that can be executed concurrently on a worker node.
115 readonly concurrency
?: number
117 * Whether to enable task stealing on idle.
121 readonly taskStealing
?: boolean
123 * Whether to enable tasks stealing under back pressure.
127 readonly tasksStealingOnBackPressure
?: boolean
129 * Queued tasks finished timeout in milliseconds at worker node termination.
133 readonly tasksFinishedTimeout
?: number
137 * Options for a poolifier pool.
139 * @typeParam Worker - Type of worker.
141 export interface PoolOptions
<Worker
extends IWorker
> {
143 * A function that will listen for online event on each worker.
145 * @defaultValue `() => {}`
147 onlineHandler
?: OnlineHandler
<Worker
>
149 * A function that will listen for message event on each worker.
151 * @defaultValue `() => {}`
153 messageHandler
?: MessageHandler
<Worker
>
155 * A function that will listen for error event on each worker.
157 * @defaultValue `() => {}`
159 errorHandler
?: ErrorHandler
<Worker
>
161 * A function that will listen for exit event on each worker.
163 * @defaultValue `() => {}`
165 exitHandler
?: ExitHandler
<Worker
>
167 * Whether to start the minimum number of workers at pool initialization.
171 startWorkers
?: boolean
173 * The worker choice strategy to use in this pool.
175 * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
177 workerChoiceStrategy
?: WorkerChoiceStrategy
179 * The worker choice strategy options.
181 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
183 * Restart worker on error.
185 restartWorkerOnError
?: boolean
187 * Pool events integrated with async resource emission.
191 enableEvents
?: boolean
193 * Pool worker node tasks queue.
195 * @defaultValue false
197 enableTasksQueue
?: boolean
199 * Pool worker node tasks queue options.
201 tasksQueueOptions
?: TasksQueueOptions
205 * @see https://nodejs.org/api/worker_threads.html#new-workerfilename-options
207 workerOptions
?: WorkerOptions
209 * Key/value pairs to add to worker process environment.
211 * @see https://nodejs.org/api/cluster.html#cluster_cluster_fork_env
213 env
?: Record
<string, unknown
>
217 * @see https://nodejs.org/api/cluster.html#cluster_cluster_settings
219 settings
?: ClusterSettings
223 * Contract definition for a poolifier pool.
225 * @typeParam Worker - Type of worker which manages this pool.
226 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
227 * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
229 export interface IPool
<
230 Worker
extends IWorker
,
237 readonly info
: PoolInfo
243 readonly workerNodes
: Array<IWorkerNode
<Worker
, Data
>>
245 * Event emitter integrated with async resource on which events can be listened to.
246 * The async tracking tooling identifier is `poolifier:<PoolType>-<WorkerType>-pool`.
248 * Events that can currently be listened to:
250 * - `'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.
251 * - `'busy'`: Emitted when the number of workers created in the pool has reached the maximum size expected and are executing concurrently their tasks quota.
252 * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected.
253 * - `'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.
254 * - `'destroy'`: Emitted when the pool is destroyed.
255 * - `'error'`: Emitted when an uncaught error occurs.
256 * - `'taskError'`: Emitted when an error occurs while executing a task.
257 * - `'backPressure'`: Emitted when all worker nodes have back pressure (i.e. their tasks queue is full: queue size \>= maximum queue size).
259 readonly emitter
?: EventEmitterAsyncResource
261 * Executes the specified function in the worker constructor with the task data input parameter.
263 * @param data - The optional task input data for the specified task function. This can only be structured-cloneable data.
264 * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed.
265 * @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.
266 * @returns Promise that will be fulfilled when the task is completed.
271 transferList
?: TransferListItem
[]
272 ) => Promise
<Response
>
274 * Starts the minimum number of workers in this pool.
276 readonly start
: () => void
278 * Terminates all workers in this pool.
280 readonly destroy
: () => Promise
<void>
282 * Whether the specified task function exists in this pool.
284 * @param name - The name of the task function.
285 * @returns `true` if the task function exists, `false` otherwise.
287 readonly hasTaskFunction
: (name
: string) => boolean
289 * Adds a task function to this pool.
290 * If a task function with the same name already exists, it will be overwritten.
292 * @param name - The name of the task function.
293 * @param fn - The task function.
294 * @returns `true` if the task function was added, `false` otherwise.
295 * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `name` parameter is not a string or an empty string.
296 * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `fn` parameter is not a function.
298 readonly addTaskFunction
: (
300 fn
: TaskFunction
<Data
, Response
>
301 ) => Promise
<boolean>
303 * Removes a task function from this pool.
305 * @param name - The name of the task function.
306 * @returns `true` if the task function was removed, `false` otherwise.
308 readonly removeTaskFunction
: (name
: string) => Promise
<boolean>
310 * Lists the names of task function available in this pool.
312 * @returns The names of task function available in this pool.
314 readonly listTaskFunctionNames
: () => string[]
316 * Sets the default task function in this pool.
318 * @param name - The name of the task function.
319 * @returns `true` if the default task function was set, `false` otherwise.
321 readonly setDefaultTaskFunction
: (name
: string) => Promise
<boolean>
323 * Sets the worker choice strategy in this pool.
325 * @param workerChoiceStrategy - The worker choice strategy.
326 * @param workerChoiceStrategyOptions - The worker choice strategy options.
328 readonly setWorkerChoiceStrategy
: (
329 workerChoiceStrategy
: WorkerChoiceStrategy
,
330 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
333 * Sets the worker choice strategy options in this pool.
335 * @param workerChoiceStrategyOptions - The worker choice strategy options.
337 readonly setWorkerChoiceStrategyOptions
: (
338 workerChoiceStrategyOptions
: WorkerChoiceStrategyOptions
341 * Enables/disables the worker node tasks queue in this pool.
343 * @param enable - Whether to enable or disable the worker node tasks queue.
344 * @param tasksQueueOptions - The worker node tasks queue options.
346 readonly enableTasksQueue
: (
348 tasksQueueOptions
?: TasksQueueOptions
351 * Sets the worker node tasks queue options in this pool.
353 * @param tasksQueueOptions - The worker node tasks queue options.
355 readonly setTasksQueueOptions
: (tasksQueueOptions
: TasksQueueOptions
) => void