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    * Submission timestamp.
  51    */
  52   readonly submissionTimestamp?: number
  53   /**
  54    * Message UUID.
  55    */
  56   readonly id?: string
  57 }
  58
  59 /**
  60  * Worker tasks usage statistics.
  61  *
  62  * @internal
  63  */
  64 export interface TasksUsage {
  65   /**
  66    * Number of tasks executed.
  67    */
  68   ran: number
  69   /**
  70    * Number of tasks running.
  71    */
  72   running: number
  73   /**
  74    * Tasks runtime.
  75    */
  76   runTime: number
  77   /**
  78    * Tasks runtime history.
  79    */
  80   runTimeHistory: CircularArray<number>
  81   /**
  82    * Average tasks runtime.
  83    */
  84   avgRunTime: number
  85   /**
  86    * Median tasks runtime.
  87    */
  88   medRunTime: number
  89   /**
  90    * Tasks wait time.
  91    */
  92   waitTime: number
  93   /**
  94    * Tasks wait time history.
  95    */
  96   waitTimeHistory: CircularArray<number>
  97   /**
  98    * Average tasks wait time.
  99    */
 100   avgWaitTime: number
 101   /**
 102    * Median tasks wait time.
 103    */
 104   medWaitTime: number
 105   /**
 106    * Number of tasks errored.
 107    */
 108   error: number
 109   /**
 110    * Event loop utilization.
 111    */
 112   elu: EventLoopUtilization | undefined
 113 }
 114
 115 /**
 116  * Worker interface.
 117  */
 118 export interface IWorker {
 119   /**
 120    * Register an event listener.
 121    *
 122    * @param event - The event.
 123    * @param handler - The event handler.
 124    */
 125   on: ((event: 'message', handler: MessageHandler<this>) => void) &
 126   ((event: 'error', handler: ErrorHandler<this>) => void) &
 127   ((event: 'online', handler: OnlineHandler<this>) => void) &
 128   ((event: 'exit', handler: ExitHandler<this>) => void)
 129   /**
 130    * Register a listener to the exit event that will only be performed once.
 131    *
 132    * @param event - `'exit'`.
 133    * @param handler - The exit handler.
 134    */
 135   once: (event: 'exit', handler: ExitHandler<this>) => void
 136 }
 137
 138 /**
 139  * Worker node interface.
 140  *
 141  * @typeParam Worker - Type of worker.
 142  * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
 143  * @internal
 144  */
 145 export interface WorkerNode<Worker extends IWorker, Data = unknown> {
 146   /**
 147    * Worker node worker.
 148    */
 149   readonly worker: Worker
 150   /**
 151    * Worker node tasks usage statistics.
 152    */
 153   tasksUsage: TasksUsage
 154   /**
 155    * Worker node tasks queue.
 156    */
 157   readonly tasksQueue: Queue<Task<Data>>
 158 }