Commit | Line | Data |
---|---|---|
9e45c2c4 | 1 | import EventEmitterAsyncResource 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 JB |
15 | /** |
16 | * Pool types. | |
17 | * | |
18 | * @enum | |
71ebe93b | 19 | * @internal |
c4855468 JB |
20 | */ |
21 | export enum PoolType { | |
22 | /** | |
23 | * Fixed pool type. | |
24 | */ | |
25 | FIXED = 'fixed', | |
26 | /** | |
27 | * Dynamic pool type. | |
28 | */ | |
29 | DYNAMIC = 'dynamic' | |
30 | } | |
31 | ||
b4904890 JB |
32 | /** |
33 | * Pool events emitter. | |
34 | */ | |
9e45c2c4 | 35 | export class PoolEmitter extends EventEmitterAsyncResource {} |
b4904890 | 36 | |
aee46736 JB |
37 | /** |
38 | * Enumeration of pool events. | |
39 | */ | |
40 | export const PoolEvents = Object.freeze({ | |
41 | full: 'full', | |
1f68cede JB |
42 | busy: 'busy', |
43 | error: 'error' | |
aee46736 JB |
44 | } as const) |
45 | ||
46 | /** | |
47 | * Pool event. | |
48 | */ | |
49 | export type PoolEvent = keyof typeof PoolEvents | |
50 | ||
7171d33f JB |
51 | /** |
52 | * Worker tasks queue options. | |
53 | */ | |
54 | export interface TasksQueueOptions { | |
55 | /** | |
56 | * Maximum number of tasks that can be executed concurrently on a worker. | |
57 | * | |
58 | * @defaultValue 1 | |
59 | */ | |
60 | concurrency?: number | |
61 | } | |
62 | ||
bdaf31cd JB |
63 | /** |
64 | * Options for a poolifier pool. | |
c319c66b | 65 | * |
d480d708 | 66 | * @typeParam Worker - Type of worker. |
bdaf31cd | 67 | */ |
50e66724 | 68 | export interface PoolOptions<Worker extends IWorker> { |
bdaf31cd JB |
69 | /** |
70 | * A function that will listen for message event on each worker. | |
71 | */ | |
72 | messageHandler?: MessageHandler<Worker> | |
73 | /** | |
74 | * A function that will listen for error event on each worker. | |
75 | */ | |
76 | errorHandler?: ErrorHandler<Worker> | |
77 | /** | |
78 | * A function that will listen for online event on each worker. | |
79 | */ | |
80 | onlineHandler?: OnlineHandler<Worker> | |
81 | /** | |
82 | * A function that will listen for exit event on each worker. | |
83 | */ | |
84 | exitHandler?: ExitHandler<Worker> | |
85 | /** | |
46e857ca | 86 | * The worker choice strategy to use in this pool. |
d29bce7c | 87 | * |
95ec6006 | 88 | * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN |
bdaf31cd JB |
89 | */ |
90 | workerChoiceStrategy?: WorkerChoiceStrategy | |
da309861 JB |
91 | /** |
92 | * The worker choice strategy options. | |
93 | */ | |
94 | workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions | |
1f68cede JB |
95 | /** |
96 | * Restart worker on error. | |
97 | */ | |
98 | restartWorkerOnError?: boolean | |
bdaf31cd JB |
99 | /** |
100 | * Pool events emission. | |
101 | * | |
38e795c1 | 102 | * @defaultValue true |
bdaf31cd JB |
103 | */ |
104 | enableEvents?: boolean | |
ff733df7 JB |
105 | /** |
106 | * Pool worker tasks queue. | |
107 | * | |
ff733df7 JB |
108 | * @defaultValue false |
109 | */ | |
110 | enableTasksQueue?: boolean | |
7171d33f JB |
111 | /** |
112 | * Pool worker tasks queue options. | |
7171d33f JB |
113 | */ |
114 | tasksQueueOptions?: TasksQueueOptions | |
bdaf31cd | 115 | } |
a35560ba | 116 | |
729c563d S |
117 | /** |
118 | * Contract definition for a poolifier pool. | |
119 | * | |
c4855468 | 120 | * @typeParam Worker - Type of worker which manages this pool. |
38e795c1 | 121 | * @typeParam Data - Type of data sent to the worker. This can only be serializable data. |
02706357 | 122 | * @typeParam Response - Type of execution response. This can only be serializable data. |
729c563d | 123 | */ |
c4855468 JB |
124 | export interface IPool< |
125 | Worker extends IWorker, | |
126 | Data = unknown, | |
127 | Response = unknown | |
128 | > { | |
129 | /** | |
130 | * Pool type. | |
131 | * | |
132 | * If it is `'dynamic'`, it provides the `max` property. | |
133 | */ | |
134 | readonly type: PoolType | |
08f3f44c JB |
135 | /** |
136 | * Pool maximum size. | |
137 | */ | |
138 | readonly size: number | |
c4855468 JB |
139 | /** |
140 | * Pool worker nodes. | |
141 | */ | |
142 | readonly workerNodes: Array<WorkerNode<Worker, Data>> | |
b4904890 JB |
143 | /** |
144 | * Emitter on which events can be listened to. | |
145 | * | |
146 | * Events that can currently be listened to: | |
147 | * | |
164d950a JB |
148 | * - `'full'`: Emitted when the pool is dynamic and full. |
149 | * - `'busy'`: Emitted when the pool is busy. | |
1f68cede | 150 | * - `'error'`: Emitted when an error occurs. |
b4904890 JB |
151 | */ |
152 | readonly emitter?: PoolEmitter | |
729c563d | 153 | /** |
61aa11a6 | 154 | * Executes the specified function in the worker constructor with the task data input parameter. |
729c563d | 155 | * |
ef41a6e6 | 156 | * @param data - The task input data for the specified worker function. This can only be serializable data. |
a86b6df1 | 157 | * @param name - The name of the worker function to execute. If not specified, the default worker function will be executed. |
ef41a6e6 | 158 | * @returns Promise that will be fulfilled when the task is completed. |
729c563d | 159 | */ |
a86b6df1 | 160 | execute: (data?: Data, name?: string) => Promise<Response> |
280c2a77 | 161 | /** |
675bb809 | 162 | * Shutdowns every current worker in this pool. |
280c2a77 | 163 | */ |
78cea37e | 164 | destroy: () => Promise<void> |
a35560ba | 165 | /** |
bdede008 | 166 | * Sets the worker choice strategy in this pool. |
a35560ba | 167 | * |
38e795c1 | 168 | * @param workerChoiceStrategy - The worker choice strategy. |
59219cbb | 169 | * @param workerChoiceStrategyOptions - The worker choice strategy options. |
a35560ba | 170 | */ |
59219cbb JB |
171 | setWorkerChoiceStrategy: ( |
172 | workerChoiceStrategy: WorkerChoiceStrategy, | |
173 | workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions | |
174 | ) => void | |
a20f0ba5 JB |
175 | /** |
176 | * Sets the worker choice strategy options in this pool. | |
177 | * | |
178 | * @param workerChoiceStrategyOptions - The worker choice strategy options. | |
179 | */ | |
180 | setWorkerChoiceStrategyOptions: ( | |
181 | workerChoiceStrategyOptions: WorkerChoiceStrategyOptions | |
182 | ) => void | |
183 | /** | |
184 | * Enables/disables the worker tasks queue in this pool. | |
185 | * | |
186 | * @param enable - Whether to enable or disable the worker tasks queue. | |
187 | * @param tasksQueueOptions - The worker tasks queue options. | |
188 | */ | |
8f52842f JB |
189 | enableTasksQueue: ( |
190 | enable: boolean, | |
191 | tasksQueueOptions?: TasksQueueOptions | |
192 | ) => void | |
a20f0ba5 JB |
193 | /** |
194 | * Sets the worker tasks queue options in this pool. | |
195 | * | |
196 | * @param tasksQueueOptions - The worker tasks queue options. | |
197 | */ | |
198 | setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void | |
c97c7edb | 199 | } |