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