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