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