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