src/pools/worker.ts

   1 import type { CircularArray } from '../circular-array'
   2
   3 /**
   4  * Callback invoked if the worker has received a message.
   5  */
   6 export 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  */
  14 export 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  */
  22 export type OnlineHandler<Worker extends IWorker> = (this: Worker) => void
  23
  24 /**
  25  * Callback invoked when the worker exits successfully.
  26  */
  27 export 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  */
  38 export 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  */
  66 export 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  */
  98 export interface EventLoopUtilizationMeasurementStatistics {
  99   readonly idle: MeasurementStatistics
 100   readonly active: MeasurementStatistics
 101   utilization?: number
 102 }
 103
 104 /**
 105  * Task statistics.
 106  *
 107  * @internal
 108  */
 109 export 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  */
 135 export const WorkerTypes = Object.freeze({
 136   cluster: 'cluster',
 137   thread: 'thread'
 138 } as const)
 139
 140 /**
 141  * Worker type.
 142  */
 143 export type WorkerType = keyof typeof WorkerTypes
 144
 145 /**
 146  * Worker information.
 147  *
 148  * @internal
 149  */
 150 export 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  */
 174 export 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  */
 196 export 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  */
 228 export interface IWorkerNode<Worker extends IWorker, Data = unknown> {
 229   /**
 230    * Worker node worker.
 231    */
 232   readonly worker: Worker
 233   /**
 234    * Worker node worker info.
 235    */
 236   readonly info: WorkerInfo
 237   /**
 238    * Worker node worker usage statistics.
 239    */
 240   usage: WorkerUsage
 241   /**
 242    * Worker node tasks queue size.
 243    *
 244    * @returns The tasks queue size.
 245    */
 246   readonly tasksQueueSize: () => number
 247   /**
 248    * Worker node 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    * Worker node dequeue task.
 256    *
 257    * @returns The dequeued task.
 258    */
 259   readonly dequeueTask: () => Task<Data> | undefined
 260   /**
 261    * Worker node clear tasks queue.
 262    */
 263   readonly clearTasksQueue: () => void
 264   /**
 265    * Worker node reset usage statistics .
 266    */
 267   readonly resetUsage: () => void
 268   /**
 269    * Worker node get tasks usage statistics.
 270    */
 271   readonly getTasksWorkerUsage: (name: string) => WorkerUsage | undefined
 272 }