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   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  * 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 structured-cloneable 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 minimum.
  70    */
  71   minimum: number
  72   /**
  73    * Measurement maximum.
  74    */
  75   maximum: number
  76   /**
  77    * Measurement average.
  78    */
  79   average: number
  80   /**
  81    * Measurement median.
  82    */
  83   median: number
  84   /**
  85    * Measurement history.
  86    */
  87   readonly history: CircularArray<number>
  88 }
  89
  90 /**
  91  * Event loop utilization measurement statistics.
  92  *
  93  * @internal
  94  */
  95 export interface EventLoopUtilizationMeasurementStatistics {
  96   readonly idle: MeasurementStatistics
  97   readonly active: MeasurementStatistics
  98   utilization?: number
  99 }
 100
 101 /**
 102  * Task statistics.
 103  *
 104  * @internal
 105  */
 106 export interface TaskStatistics {
 107   /**
 108    * Number of executed tasks.
 109    */
 110   executed: number
 111   /**
 112    * Number of executing tasks.
 113    */
 114   executing: number
 115   /**
 116    * Number of queued tasks.
 117    */
 118   readonly queued: number
 119   /**
 120    * Maximum number of queued tasks.
 121    */
 122   readonly maxQueued: number
 123   /**
 124    * Number of failed tasks.
 125    */
 126   failed: number
 127 }
 128
 129 /**
 130  * Worker information.
 131  *
 132  * @internal
 133  */
 134 export interface WorkerInfo {
 135   /**
 136    * Worker id.
 137    */
 138   readonly id: number | undefined
 139   /**
 140    * Dynamic flag.
 141    */
 142   dynamic: boolean
 143   /**
 144    * Started flag.
 145    */
 146   started: boolean
 147   /**
 148    * Shared buffer.
 149    */
 150   readonly sharedBuffer?: Int32Array
 151 }
 152
 153 /**
 154  * Worker usage statistics.
 155  *
 156  * @internal
 157  */
 158 export interface WorkerUsage {
 159   /**
 160    * Tasks statistics.
 161    */
 162   readonly tasks: TaskStatistics
 163   /**
 164    * Tasks runtime statistics.
 165    */
 166   readonly runTime: MeasurementStatistics
 167   /**
 168    * Tasks wait time statistics.
 169    */
 170   readonly waitTime: MeasurementStatistics
 171   /**
 172    * Tasks event loop utilization statistics.
 173    */
 174   readonly elu: EventLoopUtilizationMeasurementStatistics
 175 }
 176
 177 /**
 178  * Worker interface.
 179  */
 180 export interface IWorker {
 181   /**
 182    * Worker id.
 183    */
 184   readonly id?: number
 185   readonly threadId?: number
 186   /**
 187    * Registers an event listener.
 188    *
 189    * @param event - The event.
 190    * @param handler - The event handler.
 191    */
 192   on: ((event: 'message', handler: MessageHandler<this>) => void) &
 193   ((event: 'error', handler: ErrorHandler<this>) => void) &
 194   ((event: 'online', handler: OnlineHandler<this>) => void) &
 195   ((event: 'exit', handler: ExitHandler<this>) => void)
 196   /**
 197    * Registers a listener to the exit event that will only be performed once.
 198    *
 199    * @param event - `'exit'`.
 200    * @param handler - The exit handler.
 201    */
 202   once: (event: 'exit', handler: ExitHandler<this>) => void
 203 }
 204
 205 /**
 206  * Worker node interface.
 207  *
 208  * @typeParam Worker - Type of worker.
 209  * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
 210  * @internal
 211  */
 212 export interface WorkerNode<Worker extends IWorker, Data = unknown> {
 213   /**
 214    * Worker node worker.
 215    */
 216   readonly worker: Worker
 217   /**
 218    * Worker node worker info.
 219    */
 220   readonly info: WorkerInfo
 221   /**
 222    * Worker node worker usage statistics.
 223    */
 224   usage: WorkerUsage
 225   /**
 226    * Worker node tasks queue.
 227    */
 228   readonly tasksQueue: Queue<Task<Data>>
 229 }