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