chore: v2.6.19
[poolifier.git] / src / pools / worker.ts
1 import type { MessageChannel } from 'node:worker_threads'
2 import type { CircularArray } from '../circular-array'
3 import type { Task } from '../utility-types'
4
5 /**
6 * Callback invoked if the worker has received a message.
7 */
8 export type MessageHandler<Worker extends IWorker> = (
9 this: Worker,
10 message: unknown
11 ) => void
12
13 /**
14 * Callback invoked if the worker raised an error.
15 */
16 export type ErrorHandler<Worker extends IWorker> = (
17 this: Worker,
18 error: Error
19 ) => void
20
21 /**
22 * Callback invoked when the worker has started successfully.
23 */
24 export type OnlineHandler<Worker extends IWorker> = (this: Worker) => void
25
26 /**
27 * Callback invoked when the worker exits successfully.
28 */
29 export type ExitHandler<Worker extends IWorker> = (
30 this: Worker,
31 exitCode: number
32 ) => void
33
34 /**
35 * Measurement statistics.
36 *
37 * @internal
38 */
39 export interface MeasurementStatistics {
40 /**
41 * Measurement aggregate.
42 */
43 aggregate?: number
44 /**
45 * Measurement minimum.
46 */
47 minimum?: number
48 /**
49 * Measurement maximum.
50 */
51 maximum?: number
52 /**
53 * Measurement average.
54 */
55 average?: number
56 /**
57 * Measurement median.
58 */
59 median?: number
60 /**
61 * Measurement history.
62 */
63 readonly history: CircularArray<number>
64 }
65
66 /**
67 * Event loop utilization measurement statistics.
68 *
69 * @internal
70 */
71 export interface EventLoopUtilizationMeasurementStatistics {
72 readonly idle: MeasurementStatistics
73 readonly active: MeasurementStatistics
74 utilization?: number
75 }
76
77 /**
78 * Task statistics.
79 *
80 * @internal
81 */
82 export interface TaskStatistics {
83 /**
84 * Number of executed tasks.
85 */
86 executed: number
87 /**
88 * Number of executing tasks.
89 */
90 executing: number
91 /**
92 * Number of queued tasks.
93 */
94 readonly queued: number
95 /**
96 * Maximum number of queued tasks.
97 */
98 readonly maxQueued?: number
99 /**
100 * Number of failed tasks.
101 */
102 failed: number
103 }
104
105 /**
106 * Enumeration of worker types.
107 */
108 export const WorkerTypes = Object.freeze({
109 cluster: 'cluster',
110 thread: 'thread'
111 } as const)
112
113 /**
114 * Worker type.
115 */
116 export type WorkerType = keyof typeof WorkerTypes
117
118 /**
119 * Worker information.
120 *
121 * @internal
122 */
123 export interface WorkerInfo {
124 /**
125 * Worker id.
126 */
127 readonly id: number | undefined
128 /**
129 * Worker type.
130 */
131 type: WorkerType
132 /**
133 * Dynamic flag.
134 */
135 dynamic: boolean
136 /**
137 * Ready flag.
138 */
139 ready: boolean
140 /**
141 * Message channel.
142 */
143 messageChannel?: MessageChannel
144 }
145
146 /**
147 * Worker usage statistics.
148 *
149 * @internal
150 */
151 export interface WorkerUsage {
152 /**
153 * Tasks statistics.
154 */
155 readonly tasks: TaskStatistics
156 /**
157 * Tasks runtime statistics.
158 */
159 readonly runTime: MeasurementStatistics
160 /**
161 * Tasks wait time statistics.
162 */
163 readonly waitTime: MeasurementStatistics
164 /**
165 * Tasks event loop utilization statistics.
166 */
167 readonly elu: EventLoopUtilizationMeasurementStatistics
168 }
169
170 /**
171 * Worker interface.
172 */
173 export interface IWorker {
174 /**
175 * Worker id.
176 */
177 readonly id?: number
178 readonly threadId?: number
179 /**
180 * Registers an event listener.
181 *
182 * @param event - The event.
183 * @param handler - The event handler.
184 */
185 readonly on: ((event: 'message', handler: MessageHandler<this>) => void) &
186 ((event: 'error', handler: ErrorHandler<this>) => void) &
187 ((event: 'online', handler: OnlineHandler<this>) => void) &
188 ((event: 'exit', handler: ExitHandler<this>) => void)
189 /**
190 * Registers a listener to the exit event that will only be performed once.
191 *
192 * @param event - `'exit'`.
193 * @param handler - The exit handler.
194 */
195 readonly once: (event: 'exit', handler: ExitHandler<this>) => void
196 }
197
198 /**
199 * Worker node interface.
200 *
201 * @typeParam Worker - Type of worker.
202 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
203 * @internal
204 */
205 export interface IWorkerNode<Worker extends IWorker, Data = unknown> {
206 /**
207 * Worker.
208 */
209 readonly worker: Worker
210 /**
211 * Worker info.
212 */
213 readonly info: WorkerInfo
214 /**
215 * Worker usage statistics.
216 */
217 usage: WorkerUsage
218 /**
219 * Tasks queue size.
220 *
221 * @returns The tasks queue size.
222 */
223 readonly tasksQueueSize: () => number
224 /**
225 * Enqueue task.
226 *
227 * @param task - The task to queue.
228 * @returns The task queue size.
229 */
230 readonly enqueueTask: (task: Task<Data>) => number
231 /**
232 * Dequeue task.
233 *
234 * @returns The dequeued task.
235 */
236 readonly dequeueTask: () => Task<Data> | undefined
237 /**
238 * Clears tasks queue.
239 */
240 readonly clearTasksQueue: () => void
241 /**
242 * Resets usage statistics .
243 */
244 readonly resetUsage: () => void
245 /**
246 * Close communication channel.
247 */
248 readonly closeChannel: () => void
249 /**
250 * Gets task worker usage statistics.
251 */
252 readonly getTaskWorkerUsage: (name: string) => WorkerUsage | undefined
253 }