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'
16 WorkerChoiceStrategyOptions
17 } from
'./selection-strategies/selection-strategies-types'
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({
47 taskError
: 'taskError',
48 backPressure
: 'backPressure'
54 export type PoolEvent
= keyof
typeof PoolEvents
59 export interface PoolInfo
{
60 readonly version
: string
61 readonly type: PoolType
62 readonly worker
: WorkerType
63 readonly started
: boolean
64 readonly ready
: boolean
65 readonly strategy
: WorkerChoiceStrategy
66 readonly minSize
: number
67 readonly maxSize
: number
68 /** Pool utilization. */
69 readonly utilization
?: number
70 /** Pool total worker nodes. */
71 readonly workerNodes
: number
72 /** Pool idle worker nodes. */
73 readonly idleWorkerNodes
: number
74 /** Pool busy worker nodes. */
75 readonly busyWorkerNodes
: number
76 readonly executedTasks
: number
77 readonly executingTasks
: number
78 readonly queuedTasks
?: number
79 readonly maxQueuedTasks
?: number
80 readonly backPressure
?: boolean
81 readonly stolenTasks
?: number
82 readonly failedTasks
: number
84 readonly minimum
: number
85 readonly maximum
: number
86 readonly average
?: number
87 readonly median
?: number
90 readonly minimum
: number
91 readonly maximum
: number
92 readonly average
?: number
93 readonly median
?: number
98 * Worker node tasks queue options.
100 export interface TasksQueueOptions
{
102 * Maximum tasks queue size per worker node flagging it as back pressured.
104 * @defaultValue (pool maximum size)^2
106 readonly size
?: number
108 * Maximum number of tasks that can be executed concurrently on a worker node.
112 readonly concurrency
?: number
114 * Whether to enable task stealing on idle.
118 readonly taskStealing
?: boolean
120 * Whether to enable tasks stealing under back pressure.
124 readonly tasksStealingOnBackPressure
?: boolean
128 * Options for a poolifier pool.
130 * @typeParam Worker - Type of worker.
132 export interface PoolOptions
<Worker
extends IWorker
> {
134 * A function that will listen for online event on each worker.
136 * @defaultValue `() => {}`
138 onlineHandler
?: OnlineHandler
<Worker
>
140 * A function that will listen for message event on each worker.
142 * @defaultValue `() => {}`
144 messageHandler
?: MessageHandler
<Worker
>
146 * A function that will listen for error event on each worker.
148 * @defaultValue `() => {}`
150 errorHandler
?: ErrorHandler
<Worker
>
152 * A function that will listen for exit event on each worker.
154 * @defaultValue `() => {}`
156 exitHandler
?: ExitHandler
<Worker
>
158 * Whether to start the minimum number of workers at pool initialization.
162 startWorkers
?: boolean
164 * The worker choice strategy to use in this pool.
166 * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
168 workerChoiceStrategy
?: WorkerChoiceStrategy
170 * The worker choice strategy options.
172 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
174 * Restart worker on error.
176 restartWorkerOnError
?: boolean
178 * Pool events integrated with async resource emission.
182 enableEvents
?: boolean
184 * Pool worker node tasks queue.
186 * @defaultValue false
188 enableTasksQueue
?: boolean
190 * Pool worker node tasks queue options.
192 tasksQueueOptions
?: TasksQueueOptions
196 * @see https://nodejs.org/api/worker_threads.html#new-workerfilename-options
198 workerOptions
?: WorkerOptions
200 * Key/value pairs to add to worker process environment.
202 * @see https://nodejs.org/api/cluster.html#cluster_cluster_fork_env
204 env
?: Record
<string, unknown
>
208 * @see https://nodejs.org/api/cluster.html#cluster_cluster_settings
210 settings
?: ClusterSettings
214 * Contract definition for a poolifier pool.
216 * @typeParam Worker - Type of worker which manages this pool.
217 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
218 * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
220 export interface IPool
<
221 Worker
extends IWorker
,
228 readonly info
: PoolInfo
234 readonly workerNodes
: Array<IWorkerNode
<Worker
, Data
>>
236 * Whether the worker node has back pressure (i.e. its tasks queue is full).
238 * @param workerNodeKey - The worker node key.
239 * @returns `true` if the worker node has back pressure, `false` otherwise.
242 readonly hasWorkerNodeBackPressure
: (workerNodeKey
: number) => boolean
244 * Event emitter integrated with async resource on which events can be listened to.
245 * The async tracking tooling identifier is `poolifier:<PoolType>-<WorkerType>-pool`.
247 * Events that can currently be listened to:
249 * - `'ready'`: Emitted when the number of workers created in the pool has reached the minimum size expected and are ready.
250 * - `'busy'`: Emitted when the number of workers created in the pool has reached the maximum size expected and are executing concurrently their tasks quota.
251 * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected.
252 * - `'destroy'`: Emitted when the pool is destroyed.
253 * - `'error'`: Emitted when an uncaught error occurs.
254 * - `'taskError'`: Emitted when an error occurs while executing a task.
255 * - `'backPressure'`: Emitted when all worker nodes have back pressure (i.e. their tasks queue is full: queue size \>= maximum queue size).
257 readonly emitter
?: EventEmitterAsyncResource
259 * Executes the specified function in the worker constructor with the task data input parameter.
261 * @param data - The optional task input data for the specified task function. This can only be structured-cloneable data.
262 * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed.
263 * @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.
264 * @returns Promise that will be fulfilled when the task is completed.
269 transferList
?: TransferListItem
[]
270 ) => Promise
<Response
>
272 * Starts the minimum number of workers in this pool.
274 readonly start
: () => void
276 * Terminates all workers in this pool.
278 readonly destroy
: () => Promise
<void>
280 * Whether the specified task function exists in this pool.
282 * @param name - The name of the task function.
283 * @returns `true` if the task function exists, `false` otherwise.
285 readonly hasTaskFunction
: (name
: string) => boolean
287 * Adds a task function to this pool.
288 * If a task function with the same name already exists, it will be overwritten.
290 * @param name - The name of the task function.
291 * @param fn - The task function.
292 * @returns `true` if the task function was added, `false` otherwise.
293 * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `name` parameter is not a string or an empty string.
294 * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `fn` parameter is not a function.
296 readonly addTaskFunction
: (
298 fn
: TaskFunction
<Data
, Response
>
299 ) => Promise
<boolean>
301 * Removes a task function from this pool.
303 * @param name - The name of the task function.
304 * @returns `true` if the task function was removed, `false` otherwise.
306 readonly removeTaskFunction
: (name
: string) => Promise
<boolean>
308 * Lists the names of task function available in this pool.
310 * @returns The names of task function available in this pool.
312 readonly listTaskFunctionNames
: () => string[]
314 * Sets the default task function in this pool.
316 * @param name - The name of the task function.
317 * @returns `true` if the default task function was set, `false` otherwise.
319 readonly setDefaultTaskFunction
: (name
: string) => Promise
<boolean>
321 * Sets the worker choice strategy in this pool.
323 * @param workerChoiceStrategy - The worker choice strategy.
324 * @param workerChoiceStrategyOptions - The worker choice strategy options.
326 readonly setWorkerChoiceStrategy
: (
327 workerChoiceStrategy
: WorkerChoiceStrategy
,
328 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
331 * Sets the worker choice strategy options in this pool.
333 * @param workerChoiceStrategyOptions - The worker choice strategy options.
335 readonly setWorkerChoiceStrategyOptions
: (
336 workerChoiceStrategyOptions
: WorkerChoiceStrategyOptions
339 * Enables/disables the worker node tasks queue in this pool.
341 * @param enable - Whether to enable or disable the worker node tasks queue.
342 * @param tasksQueueOptions - The worker node tasks queue options.
344 readonly enableTasksQueue
: (
346 tasksQueueOptions
?: TasksQueueOptions
349 * Sets the worker node tasks queue options in this pool.
351 * @param tasksQueueOptions - The worker node tasks queue options.
353 readonly setTasksQueueOptions
: (tasksQueueOptions
: TasksQueueOptions
) => void