fix: ensure pool workers are properly initialized
[poolifier.git] / src / pools / pool.ts
CommitLineData
2845f2a5 1import { EventEmitter } from 'node:events'
7d91a8cd 2import { type TransferListItem } from 'node:worker_threads'
bdaf31cd
JB
3import type {
4 ErrorHandler,
5 ExitHandler,
50e66724 6 IWorker,
4b628b48 7 IWorkerNode,
bdaf31cd 8 MessageHandler,
c4855468 9 OnlineHandler,
4b628b48 10 WorkerType
f06e48d8 11} from './worker'
da309861
JB
12import type {
13 WorkerChoiceStrategy,
14 WorkerChoiceStrategyOptions
15} from './selection-strategies/selection-strategies-types'
bdaf31cd 16
c4855468 17/**
6b27d407 18 * Enumeration of pool types.
c4855468 19 */
6b27d407 20export const PoolTypes = Object.freeze({
c4855468
JB
21 /**
22 * Fixed pool type.
23 */
6b27d407 24 fixed: 'fixed',
c4855468
JB
25 /**
26 * Dynamic pool type.
27 */
6b27d407
JB
28 dynamic: 'dynamic'
29} as const)
30
31/**
32 * Pool type.
33 */
34export type PoolType = keyof typeof PoolTypes
c4855468 35
b4904890
JB
36/**
37 * Pool events emitter.
38 */
2845f2a5 39export class PoolEmitter extends EventEmitter {}
b4904890 40
aee46736
JB
41/**
42 * Enumeration of pool events.
43 */
44export const PoolEvents = Object.freeze({
2431bdb4 45 ready: 'ready',
1f68cede 46 busy: 'busy',
ef3891a3
JB
47 full: 'full',
48 destroy: 'destroy',
91ee39ed
JB
49 error: 'error',
50 taskError: 'taskError'
aee46736
JB
51} as const)
52
53/**
54 * Pool event.
55 */
56export type PoolEvent = keyof typeof PoolEvents
57
6b27d407
JB
58/**
59 * Pool information.
60 */
61export interface PoolInfo {
4b628b48
JB
62 readonly version: string
63 readonly type: PoolType
64 readonly worker: WorkerType
2431bdb4
JB
65 readonly ready: boolean
66 readonly strategy: WorkerChoiceStrategy
4b628b48
JB
67 readonly minSize: number
68 readonly maxSize: number
aa9eede8 69 /** Pool utilization. */
4b628b48 70 readonly utilization?: number
01a59f3c 71 /** Pool total worker nodes. */
4b628b48 72 readonly workerNodes: number
01a59f3c 73 /** Pool idle worker nodes. */
4b628b48 74 readonly idleWorkerNodes: number
01a59f3c 75 /** Pool busy worker nodes. */
4b628b48
JB
76 readonly busyWorkerNodes: number
77 readonly executedTasks: number
78 readonly executingTasks: number
daf86646
JB
79 readonly queuedTasks?: number
80 readonly maxQueuedTasks?: number
4b628b48
JB
81 readonly failedTasks: number
82 readonly runTime?: {
83 readonly minimum: number
84 readonly maximum: number
85 readonly average: number
86 readonly median?: number
1dcf8b7b 87 }
4b628b48
JB
88 readonly waitTime?: {
89 readonly minimum: number
90 readonly maximum: number
91 readonly average: number
92 readonly median?: number
1dcf8b7b 93 }
6b27d407
JB
94}
95
7171d33f
JB
96/**
97 * Worker tasks queue options.
98 */
99export interface TasksQueueOptions {
100 /**
101 * Maximum number of tasks that can be executed concurrently on a worker.
102 *
103 * @defaultValue 1
104 */
eb7bf744 105 readonly concurrency?: number
7171d33f
JB
106}
107
bdaf31cd
JB
108/**
109 * Options for a poolifier pool.
c319c66b 110 *
d480d708 111 * @typeParam Worker - Type of worker.
bdaf31cd 112 */
50e66724 113export interface PoolOptions<Worker extends IWorker> {
fd04474e
JB
114 /**
115 * A function that will listen for online event on each worker.
116 */
117 onlineHandler?: OnlineHandler<Worker>
bdaf31cd
JB
118 /**
119 * A function that will listen for message event on each worker.
120 */
121 messageHandler?: MessageHandler<Worker>
122 /**
123 * A function that will listen for error event on each worker.
124 */
125 errorHandler?: ErrorHandler<Worker>
bdaf31cd
JB
126 /**
127 * A function that will listen for exit event on each worker.
128 */
129 exitHandler?: ExitHandler<Worker>
130 /**
46e857ca 131 * The worker choice strategy to use in this pool.
d29bce7c 132 *
95ec6006 133 * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
bdaf31cd
JB
134 */
135 workerChoiceStrategy?: WorkerChoiceStrategy
da309861
JB
136 /**
137 * The worker choice strategy options.
138 */
139 workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
1f68cede
JB
140 /**
141 * Restart worker on error.
142 */
143 restartWorkerOnError?: boolean
bdaf31cd
JB
144 /**
145 * Pool events emission.
146 *
38e795c1 147 * @defaultValue true
bdaf31cd
JB
148 */
149 enableEvents?: boolean
ff733df7
JB
150 /**
151 * Pool worker tasks queue.
152 *
ff733df7
JB
153 * @defaultValue false
154 */
155 enableTasksQueue?: boolean
7171d33f
JB
156 /**
157 * Pool worker tasks queue options.
7171d33f
JB
158 */
159 tasksQueueOptions?: TasksQueueOptions
bdaf31cd 160}
a35560ba 161
729c563d
S
162/**
163 * Contract definition for a poolifier pool.
164 *
c4855468 165 * @typeParam Worker - Type of worker which manages this pool.
e102732c
JB
166 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
167 * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
729c563d 168 */
c4855468
JB
169export interface IPool<
170 Worker extends IWorker,
171 Data = unknown,
172 Response = unknown
173> {
08f3f44c 174 /**
6b27d407 175 * Pool information.
08f3f44c 176 */
6b27d407 177 readonly info: PoolInfo
c4855468
JB
178 /**
179 * Pool worker nodes.
180 */
4b628b48 181 readonly workerNodes: Array<IWorkerNode<Worker, Data>>
b4904890
JB
182 /**
183 * Emitter on which events can be listened to.
184 *
185 * Events that can currently be listened to:
186 *
d5024c00 187 * - `'ready'`: Emitted when the number of workers created in the pool has reached the minimum size expected and are ready.
2431bdb4 188 * - `'busy'`: Emitted when the number of workers created in the pool has reached the maximum size expected and are executing at least one task.
ef3891a3
JB
189 * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected.
190 * - '`destroy`': Emitted when the pool is destroyed.
91ee39ed
JB
191 * - `'error'`: Emitted when an uncaught error occurs.
192 * - `'taskError'`: Emitted when an error occurs while executing a task.
b4904890
JB
193 */
194 readonly emitter?: PoolEmitter
729c563d 195 /**
61aa11a6 196 * Executes the specified function in the worker constructor with the task data input parameter.
729c563d 197 *
7d91a8cd
JB
198 * @param data - The optional task input data for the specified task function. This can only be structured-cloneable data.
199 * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed.
200 * @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.
ef41a6e6 201 * @returns Promise that will be fulfilled when the task is completed.
729c563d 202 */
7d91a8cd
JB
203 readonly execute: (
204 data?: Data,
205 name?: string,
206 transferList?: TransferListItem[]
207 ) => Promise<Response>
280c2a77 208 /**
aa9eede8 209 * Terminates all workers in this pool.
280c2a77 210 */
4b628b48 211 readonly destroy: () => Promise<void>
90d7d101
JB
212 /**
213 * Lists the names of task function available in this pool.
214 *
215 * @returns The names of task function available in this pool.
216 */
217 readonly listTaskFunctions: () => string[]
a35560ba 218 /**
bdede008 219 * Sets the worker choice strategy in this pool.
a35560ba 220 *
38e795c1 221 * @param workerChoiceStrategy - The worker choice strategy.
59219cbb 222 * @param workerChoiceStrategyOptions - The worker choice strategy options.
a35560ba 223 */
4b628b48 224 readonly setWorkerChoiceStrategy: (
59219cbb
JB
225 workerChoiceStrategy: WorkerChoiceStrategy,
226 workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
227 ) => void
a20f0ba5
JB
228 /**
229 * Sets the worker choice strategy options in this pool.
230 *
231 * @param workerChoiceStrategyOptions - The worker choice strategy options.
232 */
4b628b48 233 readonly setWorkerChoiceStrategyOptions: (
a20f0ba5
JB
234 workerChoiceStrategyOptions: WorkerChoiceStrategyOptions
235 ) => void
236 /**
237 * Enables/disables the worker tasks queue in this pool.
238 *
239 * @param enable - Whether to enable or disable the worker tasks queue.
240 * @param tasksQueueOptions - The worker tasks queue options.
241 */
4b628b48 242 readonly enableTasksQueue: (
8f52842f
JB
243 enable: boolean,
244 tasksQueueOptions?: TasksQueueOptions
245 ) => void
a20f0ba5
JB
246 /**
247 * Sets the worker tasks queue options in this pool.
248 *
249 * @param tasksQueueOptions - The worker tasks queue options.
250 */
4b628b48 251 readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void
c97c7edb 252}