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