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