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