refactor: remove unused queue code
[poolifier.git] / src / pools / worker.ts
CommitLineData
85aeb3f3 1import type { MessageChannel } from 'node:worker_threads'
f06e48d8 2import type { CircularArray } from '../circular-array'
5c4d16da 3import type { Task } from '../utility-types'
f06e48d8 4
671d5154
JB
5/**
6 * Callback invoked when the worker has started successfully.
7 */
8export type OnlineHandler<Worker extends IWorker> = (this: Worker) => void
9
bdaf31cd
JB
10/**
11 * Callback invoked if the worker has received a message.
12 */
50e66724
JB
13export type MessageHandler<Worker extends IWorker> = (
14 this: Worker,
e102732c 15 message: unknown
50e66724 16) => void
bdaf31cd
JB
17
18/**
19 * Callback invoked if the worker raised an error.
20 */
50e66724
JB
21export type ErrorHandler<Worker extends IWorker> = (
22 this: Worker,
e102732c 23 error: Error
50e66724 24) => void
bdaf31cd 25
bdaf31cd
JB
26/**
27 * Callback invoked when the worker exits successfully.
28 */
50e66724
JB
29export type ExitHandler<Worker extends IWorker> = (
30 this: Worker,
e102732c 31 exitCode: number
50e66724 32) => void
bdaf31cd 33
f06e48d8 34/**
cd4d348a 35 * Measurement statistics.
f9b4bbf8
JB
36 *
37 * @internal
f06e48d8 38 */
cd4d348a 39export interface MeasurementStatistics {
02706357 40 /**
932fc8be 41 * Measurement aggregate.
02706357 42 */
71514351 43 aggregate?: number
f7510105
JB
44 /**
45 * Measurement minimum.
46 */
71514351 47 minimum?: number
f7510105
JB
48 /**
49 * Measurement maximum.
50 */
71514351 51 maximum?: number
02706357 52 /**
cd4d348a 53 * Measurement average.
02706357 54 */
71514351 55 average?: number
02706357 56 /**
cd4d348a 57 * Measurement median.
02706357 58 */
71514351 59 median?: number
02706357 60 /**
cd4d348a 61 * Measurement history.
02706357 62 */
eb7bf744 63 readonly history: CircularArray<number>
a4e07f72
JB
64}
65
5df69fab
JB
66/**
67 * Event loop utilization measurement statistics.
68 *
69 * @internal
70 */
71export interface EventLoopUtilizationMeasurementStatistics {
eb7bf744
JB
72 readonly idle: MeasurementStatistics
73 readonly active: MeasurementStatistics
f7510105 74 utilization?: number
5df69fab
JB
75}
76
a4e07f72
JB
77/**
78 * Task statistics.
79 *
80 * @internal
81 */
a4e07f72 82export interface TaskStatistics {
02706357 83 /**
9a0613e9 84 * Number of executed tasks.
02706357 85 */
a4e07f72 86 executed: number
02706357 87 /**
9a0613e9 88 * Number of executing tasks.
02706357 89 */
a4e07f72 90 executing: number
0567595a 91 /**
9a0613e9 92 * Number of queued tasks.
0567595a 93 */
8604aaab 94 readonly queued: number
df593701
JB
95 /**
96 * Maximum number of queued tasks.
97 */
b25a42cd 98 readonly maxQueued?: number
0567595a 99 /**
9a0613e9 100 * Number of failed tasks.
0567595a 101 */
a4e07f72
JB
102 failed: number
103}
104
4b628b48
JB
105/**
106 * Enumeration of worker types.
107 */
108export const WorkerTypes = Object.freeze({
149fdbb9
JB
109 thread: 'thread',
110 cluster: 'cluster'
4b628b48
JB
111} as const)
112
113/**
114 * Worker type.
115 */
116export type WorkerType = keyof typeof WorkerTypes
117
f59e1027
JB
118/**
119 * Worker information.
120 *
121 * @internal
122 */
123export interface WorkerInfo {
124 /**
83fa0a36 125 * Worker id.
f59e1027 126 */
eb7bf744 127 readonly id: number | undefined
4b628b48
JB
128 /**
129 * Worker type.
130 */
131 type: WorkerType
8a1260a3
JB
132 /**
133 * Dynamic flag.
134 */
135 dynamic: boolean
f59e1027 136 /**
7c8381eb 137 * Ready flag.
f59e1027 138 */
7c8381eb 139 ready: boolean
b558f6b5
JB
140 /**
141 * Task function names.
142 */
143 taskFunctions?: string[]
f59e1027
JB
144}
145
a4e07f72
JB
146/**
147 * Worker usage statistics.
148 *
149 * @internal
150 */
151export interface WorkerUsage {
0567595a 152 /**
a4e07f72 153 * Tasks statistics.
0567595a 154 */
eb7bf744 155 readonly tasks: TaskStatistics
0567595a 156 /**
a4e07f72 157 * Tasks runtime statistics.
0567595a 158 */
eb7bf744 159 readonly runTime: MeasurementStatistics
02706357 160 /**
a4e07f72 161 * Tasks wait time statistics.
02706357 162 */
eb7bf744 163 readonly waitTime: MeasurementStatistics
62c15a68 164 /**
5df69fab 165 * Tasks event loop utilization statistics.
62c15a68 166 */
eb7bf744 167 readonly elu: EventLoopUtilizationMeasurementStatistics
f06e48d8
JB
168}
169
170/**
171 * Worker interface.
172 */
173export interface IWorker {
f59e1027 174 /**
83fa0a36 175 * Worker id.
f59e1027 176 */
aecc6e48
JB
177 readonly id?: number
178 readonly threadId?: number
bdaf31cd 179 /**
64383951 180 * Registers an event listener.
bdaf31cd 181 *
38e795c1 182 * @param event - The event.
48ef9107 183 * @param handler - The event handler.
bdaf31cd 184 */
fd04474e
JB
185 readonly on: ((event: 'online', handler: OnlineHandler<this>) => void) &
186 ((event: 'message', handler: MessageHandler<this>) => void) &
78cea37e 187 ((event: 'error', handler: ErrorHandler<this>) => void) &
78cea37e 188 ((event: 'exit', handler: ExitHandler<this>) => void)
bdaf31cd 189 /**
64383951 190 * Registers a listener to the exit event that will only be performed once.
bdaf31cd 191 *
38e795c1
JB
192 * @param event - `'exit'`.
193 * @param handler - The exit handler.
bdaf31cd 194 */
4b628b48 195 readonly once: (event: 'exit', handler: ExitHandler<this>) => void
bdaf31cd 196}
f06e48d8
JB
197
198/**
199 * Worker node interface.
c319c66b
JB
200 *
201 * @typeParam Worker - Type of worker.
e102732c 202 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
c319c66b 203 * @internal
f06e48d8 204 */
4b628b48 205export interface IWorkerNode<Worker extends IWorker, Data = unknown> {
c319c66b 206 /**
ccd73e07 207 * Worker.
c319c66b 208 */
02706357 209 readonly worker: Worker
f59e1027 210 /**
ccd73e07 211 * Worker info.
f59e1027 212 */
eb7bf744 213 readonly info: WorkerInfo
7884d183 214 /**
336e91c4 215 * Message channel (worker_threads only).
7884d183
JB
216 */
217 readonly messageChannel?: MessageChannel
c319c66b 218 /**
ccd73e07 219 * Worker usage statistics.
c319c66b 220 */
f59e1027 221 usage: WorkerUsage
20c6f652
JB
222 /**
223 * Tasks queue back pressure size.
224 * This is the number of tasks that can be enqueued before the worker node has back pressure.
225 */
226 tasksQueueBackPressureSize: number
72695f86
JB
227 /**
228 * Callback invoked when worker node tasks queue is back pressured.
229 *
230 * @param workerId - The worker id.
231 */
232 onBackPressure?: (workerId: number) => void
c319c66b 233 /**
ccd73e07 234 * Tasks queue size.
4b628b48
JB
235 *
236 * @returns The tasks queue size.
237 */
238 readonly tasksQueueSize: () => number
239 /**
ccd73e07 240 * Enqueue task.
4b628b48
JB
241 *
242 * @param task - The task to queue.
a1763c54 243 * @returns The tasks queue size.
4b628b48
JB
244 */
245 readonly enqueueTask: (task: Task<Data>) => number
72695f86
JB
246 /**
247 * Prepends a task to the tasks queue.
248 *
249 * @param task - The task to prepend.
250 * @returns The tasks queue size.
251 */
252 readonly unshiftTask: (task: Task<Data>) => number
4b628b48 253 /**
ccd73e07 254 * Dequeue task.
4b628b48
JB
255 *
256 * @returns The dequeued task.
257 */
258 readonly dequeueTask: () => Task<Data> | undefined
72695f86
JB
259 /**
260 * Pops a task from the tasks queue.
261 *
262 * @returns The popped task.
263 */
264 readonly popTask: () => Task<Data> | undefined
4b628b48 265 /**
ccd73e07 266 * Clears tasks queue.
4b628b48
JB
267 */
268 readonly clearTasksQueue: () => void
671d5154 269 /**
e2b31e32 270 * Whether the worker node has back pressure (i.e. its tasks queue is full).
671d5154
JB
271 *
272 * @returns `true` if the worker node has back pressure, `false` otherwise.
273 */
274 readonly hasBackPressure: () => boolean
4b628b48 275 /**
ff469b0e 276 * Resets usage statistics.
c319c66b 277 */
4b628b48 278 readonly resetUsage: () => void
3f09ed9f 279 /**
a5d15204 280 * Closes communication channel.
3f09ed9f
JB
281 */
282 readonly closeChannel: () => void
ff128cc9 283 /**
2809112e
JB
284 * Gets task function worker usage statistics.
285 *
286 * @param name - The task function name.
287 * @returns The task function worker usage statistics if the task function worker usage statistics are initialized, `undefined` otherwise.
ff128cc9 288 */
db0e38ee 289 readonly getTaskFunctionWorkerUsage: (name: string) => WorkerUsage | undefined
f06e48d8 290}