17088559a32620f48175cb273bf709f6af817a90
[poolifier.git] / src / pools / pool.ts
1 import EventEmitter from 'node:events'
2 import type {
3 ErrorHandler,
4 ExitHandler,
5 IWorker,
6 MessageHandler,
7 OnlineHandler,
8 WorkerNode
9 } from './worker'
10 import type {
11 WorkerChoiceStrategy,
12 WorkerChoiceStrategyOptions
13 } from './selection-strategies/selection-strategies-types'
14
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
31 /**
32 * Pool events emitter.
33 */
34 export class PoolEmitter extends EventEmitter {}
35
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
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
61 /**
62 * Options for a poolifier pool.
63 *
64 * @typeParam Worker - The worker type.
65 */
66 export interface PoolOptions<Worker extends IWorker> {
67 /**
68 * A function that will listen for message event on each worker.
69 */
70 messageHandler?: MessageHandler<Worker>
71 /**
72 * A function that will listen for error event on each worker.
73 */
74 errorHandler?: ErrorHandler<Worker>
75 /**
76 * A function that will listen for online event on each worker.
77 */
78 onlineHandler?: OnlineHandler<Worker>
79 /**
80 * A function that will listen for exit event on each worker.
81 */
82 exitHandler?: ExitHandler<Worker>
83 /**
84 * The worker choice strategy to use in this pool.
85 */
86 workerChoiceStrategy?: WorkerChoiceStrategy
87 /**
88 * The worker choice strategy options.
89 */
90 workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
91 /**
92 * Pool events emission.
93 *
94 * @defaultValue true
95 */
96 enableEvents?: boolean
97 /**
98 * Pool worker tasks queue.
99 *
100 * @experimental
101 * @defaultValue false
102 */
103 enableTasksQueue?: boolean
104 /**
105 * Pool worker tasks queue options.
106 *
107 * @experimental
108 */
109 tasksQueueOptions?: TasksQueueOptions
110 }
111
112 /**
113 * Contract definition for a poolifier pool.
114 *
115 * @typeParam Worker - Type of worker which manages this pool.
116 * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
117 * @typeParam Response - Type of response of execution. This can only be serializable data.
118 */
119 export interface IPool<
120 Worker extends IWorker,
121 Data = unknown,
122 Response = unknown
123 > {
124 /**
125 * Pool type.
126 *
127 * If it is `'dynamic'`, it provides the `max` property.
128 */
129 readonly type: PoolType
130 /**
131 * Pool worker nodes.
132 */
133 readonly workerNodes: Array<WorkerNode<Worker, Data>>
134 /**
135 * Emitter on which events can be listened to.
136 *
137 * Events that can currently be listened to:
138 *
139 * - `'full'`: Emitted when the pool is dynamic and full.
140 * - `'busy'`: Emitted when the pool is busy.
141 */
142 readonly emitter?: PoolEmitter
143 /**
144 * Finds a free worker node key based on the number of tasks the worker has applied.
145 *
146 * If a worker is found with `0` running tasks, it is detected as free and its worker node key is returned.
147 *
148 * If no free worker is found, `-1` is returned.
149 *
150 * @returns A worker node key if there is one, `-1` otherwise.
151 */
152 findFreeWorkerNodeKey: () => number
153 /**
154 * Performs the task specified in the constructor with the data parameter.
155 *
156 * @param data - The input for the specified task. This can only be serializable data.
157 * @returns Promise that will be resolved when the task is successfully completed.
158 */
159 execute: (data: Data) => Promise<Response>
160 /**
161 * Shutdowns every current worker in this pool.
162 */
163 destroy: () => Promise<void>
164 /**
165 * Sets the worker choice strategy in this pool.
166 *
167 * @param workerChoiceStrategy - The worker choice strategy.
168 */
169 setWorkerChoiceStrategy: (workerChoiceStrategy: WorkerChoiceStrategy) => void
170 }