refactor: cleanup variables namespace
[poolifier.git] / src / pools / worker.ts
1 import type { CircularArray } from '../circular-array'
2 import type { Queue } from '../queue'
3
4 /**
5 * Callback invoked if the worker has received a message.
6 */
7 export type MessageHandler<Worker extends IWorker> = (
8 this: Worker,
9 m: 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 e: 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 code: number
31 ) => void
32
33 /**
34 * Message object that is passed as a task between main worker and worker.
35 *
36 * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
37 * @internal
38 */
39 export interface Task<Data = unknown> {
40 /**
41 * Task name.
42 */
43 readonly name?: string
44 /**
45 * Task input data that will be passed to the worker.
46 */
47 readonly data?: Data
48 /**
49 * Timestamp.
50 */
51 readonly timestamp?: number
52 /**
53 * Message UUID.
54 */
55 readonly id?: string
56 }
57
58 /**
59 * Measurement statistics.
60 *
61 * @internal
62 */
63 export interface MeasurementStatistics {
64 /**
65 * Measurement aggregate.
66 */
67 aggregate: number
68 /**
69 * Measurement average.
70 */
71 average: number
72 /**
73 * Measurement median.
74 */
75 median: number
76 /**
77 * Measurement history.
78 */
79 history: CircularArray<number>
80 }
81
82 /**
83 * Event loop utilization measurement statistics.
84 *
85 * @internal
86 */
87 export interface EventLoopUtilizationMeasurementStatistics {
88 idle: MeasurementStatistics
89 active: MeasurementStatistics
90 utilization: number
91 }
92
93 /**
94 * Task statistics.
95 *
96 * @internal
97 */
98 export interface TaskStatistics {
99 /**
100 * Number of executed tasks.
101 */
102 executed: number
103 /**
104 * Number of executing tasks.
105 */
106 executing: number
107 /**
108 * Number of queued tasks.
109 */
110 readonly queued: number
111 /**
112 * Number of failed tasks.
113 */
114 failed: number
115 }
116
117 /**
118 * Worker usage statistics.
119 *
120 * @internal
121 */
122 export interface WorkerUsage {
123 /**
124 * Tasks statistics.
125 */
126 tasks: TaskStatistics
127 /**
128 * Tasks runtime statistics.
129 */
130 runTime: MeasurementStatistics
131 /**
132 * Tasks wait time statistics.
133 */
134 waitTime: MeasurementStatistics
135 /**
136 * Tasks event loop utilization statistics.
137 */
138 elu: EventLoopUtilizationMeasurementStatistics
139 }
140
141 /**
142 * Worker interface.
143 */
144 export interface IWorker {
145 /**
146 * Register an event listener.
147 *
148 * @param event - The event.
149 * @param handler - The event handler.
150 */
151 on: ((event: 'message', handler: MessageHandler<this>) => void) &
152 ((event: 'error', handler: ErrorHandler<this>) => void) &
153 ((event: 'online', handler: OnlineHandler<this>) => void) &
154 ((event: 'exit', handler: ExitHandler<this>) => void)
155 /**
156 * Register a listener to the exit event that will only be performed once.
157 *
158 * @param event - `'exit'`.
159 * @param handler - The exit handler.
160 */
161 once: (event: 'exit', handler: ExitHandler<this>) => void
162 }
163
164 /**
165 * Worker node interface.
166 *
167 * @typeParam Worker - Type of worker.
168 * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
169 * @internal
170 */
171 export interface WorkerNode<Worker extends IWorker, Data = unknown> {
172 /**
173 * Worker node worker.
174 */
175 readonly worker: Worker
176 /**
177 * Worker node worker usage statistics.
178 */
179 workerUsage: WorkerUsage
180 /**
181 * Worker node tasks queue.
182 */
183 readonly tasksQueue: Queue<Task<Data>>
184 }