feat: add worker kill handler success or failure reporting
[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
bdaf31cd
JB
5/**
6 * Callback invoked if the worker has received a message.
7 */
50e66724
JB
8export type MessageHandler<Worker extends IWorker> = (
9 this: Worker,
e102732c 10 message: unknown
50e66724 11) => void
bdaf31cd
JB
12
13/**
14 * Callback invoked if the worker raised an error.
15 */
50e66724
JB
16export type ErrorHandler<Worker extends IWorker> = (
17 this: Worker,
e102732c 18 error: Error
50e66724 19) => void
bdaf31cd
JB
20
21/**
22 * Callback invoked when the worker has started successfully.
23 */
50e66724 24export type OnlineHandler<Worker extends IWorker> = (this: Worker) => void
bdaf31cd
JB
25
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
85aeb3f3
JB
140 /**
141 * Message channel.
142 */
143 messageChannel?: MessageChannel
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 */
4b628b48 185 readonly on: ((event: 'message', handler: MessageHandler<this>) => void) &
78cea37e
JB
186 ((event: 'error', handler: ErrorHandler<this>) => void) &
187 ((event: 'online', handler: OnlineHandler<this>) => void) &
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
c319c66b 214 /**
ccd73e07 215 * Worker usage statistics.
c319c66b 216 */
f59e1027 217 usage: WorkerUsage
c319c66b 218 /**
ccd73e07 219 * Tasks queue size.
4b628b48
JB
220 *
221 * @returns The tasks queue size.
222 */
223 readonly tasksQueueSize: () => number
224 /**
ccd73e07 225 * Enqueue task.
4b628b48
JB
226 *
227 * @param task - The task to queue.
228 * @returns The task queue size.
229 */
230 readonly enqueueTask: (task: Task<Data>) => number
231 /**
ccd73e07 232 * Dequeue task.
4b628b48
JB
233 *
234 * @returns The dequeued task.
235 */
236 readonly dequeueTask: () => Task<Data> | undefined
237 /**
ccd73e07 238 * Clears tasks queue.
4b628b48
JB
239 */
240 readonly clearTasksQueue: () => void
241 /**
ccd73e07 242 * Resets usage statistics .
c319c66b 243 */
4b628b48 244 readonly resetUsage: () => void
3f09ed9f
JB
245 /**
246 * Close communication channel.
247 */
248 readonly closeChannel: () => void
ff128cc9 249 /**
20016c79 250 * Gets task worker usage statistics.
ff128cc9 251 */
ce1b31be 252 readonly getTaskWorkerUsage: (name: string) => WorkerUsage | undefined
f06e48d8 253}