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