src/pools/worker.ts

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