Merge branch 'master' of github.com:poolifier/poolifier
[poolifier.git] / src / pools / pool.ts
CommitLineData
fc3e6586 1import EventEmitter from 'node:events'
bdaf31cd
JB
2import type {
3 ErrorHandler,
4 ExitHandler,
50e66724 5 IWorker,
bdaf31cd 6 MessageHandler,
c4855468
JB
7 OnlineHandler,
8 WorkerNode
f06e48d8 9} from './worker'
da309861
JB
10import type {
11 WorkerChoiceStrategy,
12 WorkerChoiceStrategyOptions
13} from './selection-strategies/selection-strategies-types'
bdaf31cd 14
c4855468
JB
15/**
16 * Pool types.
17 *
18 * @enum
19 */
20export 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 */
34export class PoolEmitter extends EventEmitter {}
35
aee46736
JB
36/**
37 * Enumeration of pool events.
38 */
39export const PoolEvents = Object.freeze({
40 full: 'full',
41 busy: 'busy'
42} as const)
43
44/**
45 * Pool event.
46 */
47export type PoolEvent = keyof typeof PoolEvents
48
7171d33f
JB
49/**
50 * Worker tasks queue options.
51 */
52export 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 64export 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
117export 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}