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