1 import { EventEmitter
} from
'node:events'
2 import { type TransferListItem
} from
'node:worker_threads'
14 WorkerChoiceStrategyOptions
15 } from
'./selection-strategies/selection-strategies-types'
18 * Enumeration of pool types.
20 export const PoolTypes
= Object.freeze({
34 export type PoolType
= keyof
typeof PoolTypes
37 * Pool events emitter.
39 export class PoolEmitter
extends EventEmitter
{}
42 * Enumeration of pool events.
44 export const PoolEvents
= Object.freeze({
50 taskError
: 'taskError',
51 backPressure
: 'backPressure'
57 export type PoolEvent
= keyof
typeof PoolEvents
62 export interface PoolInfo
{
63 readonly version
: string
64 readonly type: PoolType
65 readonly worker
: WorkerType
66 readonly ready
: boolean
67 readonly strategy
: WorkerChoiceStrategy
68 readonly minSize
: number
69 readonly maxSize
: number
70 /** Pool utilization. */
71 readonly utilization
?: number
72 /** Pool total worker nodes. */
73 readonly workerNodes
: number
74 /** Pool idle worker nodes. */
75 readonly idleWorkerNodes
: number
76 /** Pool busy worker nodes. */
77 readonly busyWorkerNodes
: number
78 readonly executedTasks
: number
79 readonly executingTasks
: number
80 readonly queuedTasks
?: number
81 readonly maxQueuedTasks
?: 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 tasks queue options.
100 export interface TasksQueueOptions
{
102 * Maximum number of tasks that can be executed concurrently on a worker.
106 readonly concurrency
?: number
110 * Options for a poolifier pool.
112 * @typeParam Worker - Type of worker.
114 export interface PoolOptions
<Worker
extends IWorker
> {
116 * A function that will listen for online event on each worker.
118 onlineHandler
?: OnlineHandler
<Worker
>
120 * A function that will listen for message event on each worker.
122 messageHandler
?: MessageHandler
<Worker
>
124 * A function that will listen for error event on each worker.
126 errorHandler
?: ErrorHandler
<Worker
>
128 * A function that will listen for exit event on each worker.
130 exitHandler
?: ExitHandler
<Worker
>
132 * The worker choice strategy to use in this pool.
134 * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
136 workerChoiceStrategy
?: WorkerChoiceStrategy
138 * The worker choice strategy options.
140 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
142 * Restart worker on error.
144 restartWorkerOnError
?: boolean
146 * Pool events emission.
150 enableEvents
?: boolean
152 * Pool worker tasks queue.
154 * @defaultValue false
156 enableTasksQueue
?: boolean
158 * Pool worker tasks queue options.
160 tasksQueueOptions
?: TasksQueueOptions
164 * Contract definition for a poolifier pool.
166 * @typeParam Worker - Type of worker which manages this pool.
167 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
168 * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
170 export interface IPool
<
171 Worker
extends IWorker
,
178 readonly info
: PoolInfo
182 readonly workerNodes
: Array<IWorkerNode
<Worker
, Data
>>
184 * Emitter on which events can be listened to.
186 * Events that can currently be listened to:
188 * - `'ready'`: Emitted when the number of workers created in the pool has reached the minimum size expected and are ready.
189 * - `'busy'`: Emitted when the number of workers created in the pool has reached the maximum size expected and are executing at least one task.
190 * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected.
191 * - '`destroy`': Emitted when the pool is destroyed.
192 * - `'error'`: Emitted when an uncaught error occurs.
193 * - `'taskError'`: Emitted when an error occurs while executing a task.
195 readonly emitter
?: PoolEmitter
197 * Executes the specified function in the worker constructor with the task data input parameter.
199 * @param data - The optional task input data for the specified task function. This can only be structured-cloneable data.
200 * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed.
201 * @param transferList - An optional array of transferable objects to transfer ownership of. Ownership of the transferred objects is given to the pool's worker_threads worker and they should not be used in the main thread afterwards.
202 * @returns Promise that will be fulfilled when the task is completed.
207 transferList
?: TransferListItem
[]
208 ) => Promise
<Response
>
210 * Terminates all workers in this pool.
212 readonly destroy
: () => Promise
<void>
214 * Lists the names of task function available in this pool.
216 * @returns The names of task function available in this pool.
218 readonly listTaskFunctions
: () => string[]
220 * Sets the worker choice strategy in this pool.
222 * @param workerChoiceStrategy - The worker choice strategy.
223 * @param workerChoiceStrategyOptions - The worker choice strategy options.
225 readonly setWorkerChoiceStrategy
: (
226 workerChoiceStrategy
: WorkerChoiceStrategy
,
227 workerChoiceStrategyOptions
?: WorkerChoiceStrategyOptions
230 * Sets the worker choice strategy options in this pool.
232 * @param workerChoiceStrategyOptions - The worker choice strategy options.
234 readonly setWorkerChoiceStrategyOptions
: (
235 workerChoiceStrategyOptions
: WorkerChoiceStrategyOptions
238 * Enables/disables the worker tasks queue in this pool.
240 * @param enable - Whether to enable or disable the worker tasks queue.
241 * @param tasksQueueOptions - The worker tasks queue options.
243 readonly enableTasksQueue
: (
245 tasksQueueOptions
?: TasksQueueOptions
248 * Sets the worker tasks queue options in this pool.
250 * @param tasksQueueOptions - The worker tasks queue options.
252 readonly setTasksQueueOptions
: (tasksQueueOptions
: TasksQueueOptions
) => void