src/pools/pool.ts

   1 import EventEmitter from 'node:events'
   2 import type {
   3   ErrorHandler,
   4   ExitHandler,
   5   IWorker,
   6   MessageHandler,
   7   OnlineHandler,
   8   WorkerNode
   9 } from './worker'
  10 import type {
  11   WorkerChoiceStrategy,
  12   WorkerChoiceStrategyOptions
  13 } from './selection-strategies/selection-strategies-types'
  14
  15 /**
  16  * Pool types.
  17  *
  18  * @enum
  19  * @internal
  20  */
  21 export enum PoolType {
  22   /**
  23    * Fixed pool type.
  24    */
  25   FIXED = 'fixed',
  26   /**
  27    * Dynamic pool type.
  28    */
  29   DYNAMIC = 'dynamic'
  30 }
  31
  32 /**
  33  * Pool events emitter.
  34  */
  35 export class PoolEmitter extends EventEmitter {}
  36
  37 /**
  38  * Enumeration of pool events.
  39  */
  40 export const PoolEvents = Object.freeze({
  41   full: 'full',
  42   busy: 'busy'
  43 } as const)
  44
  45 /**
  46  * Pool event.
  47  */
  48 export type PoolEvent = keyof typeof PoolEvents
  49
  50 /**
  51  * Worker tasks queue options.
  52  */
  53 export interface TasksQueueOptions {
  54   /**
  55    * Maximum number of tasks that can be executed concurrently on a worker.
  56    *
  57    * @defaultValue 1
  58    */
  59   concurrency?: number
  60 }
  61
  62 /**
  63  * Options for a poolifier pool.
  64  *
  65  * @typeParam Worker - Type of worker.
  66  */
  67 export interface PoolOptions<Worker extends IWorker> {
  68   /**
  69    * A function that will listen for message event on each worker.
  70    */
  71   messageHandler?: MessageHandler<Worker>
  72   /**
  73    * A function that will listen for error event on each worker.
  74    */
  75   errorHandler?: ErrorHandler<Worker>
  76   /**
  77    * A function that will listen for online event on each worker.
  78    */
  79   onlineHandler?: OnlineHandler<Worker>
  80   /**
  81    * A function that will listen for exit event on each worker.
  82    */
  83   exitHandler?: ExitHandler<Worker>
  84   /**
  85    * The worker choice strategy to use in this pool.
  86    *
  87    * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
  88    */
  89   workerChoiceStrategy?: WorkerChoiceStrategy
  90   /**
  91    * The worker choice strategy options.
  92    */
  93   workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
  94   /**
  95    * Pool events emission.
  96    *
  97    * @defaultValue true
  98    */
  99   enableEvents?: boolean
 100   /**
 101    * Pool worker tasks queue.
 102    *
 103    * @defaultValue false
 104    */
 105   enableTasksQueue?: boolean
 106   /**
 107    * Pool worker tasks queue options.
 108    */
 109   tasksQueueOptions?: TasksQueueOptions
 110 }
 111
 112 /**
 113  * Contract definition for a poolifier pool.
 114  *
 115  * @typeParam Worker - Type of worker which manages this pool.
 116  * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
 117  * @typeParam Response - Type of execution response. This can only be serializable data.
 118  */
 119 export interface IPool<
 120   Worker extends IWorker,
 121   Data = unknown,
 122   Response = unknown
 123 > {
 124   /**
 125    * Pool type.
 126    *
 127    * If it is `'dynamic'`, it provides the `max` property.
 128    */
 129   readonly type: PoolType
 130   /**
 131    * Pool worker nodes.
 132    */
 133   readonly workerNodes: Array<WorkerNode<Worker, Data>>
 134   /**
 135    * Emitter on which events can be listened to.
 136    *
 137    * Events that can currently be listened to:
 138    *
 139    * - `'full'`: Emitted when the pool is dynamic and full.
 140    * - `'busy'`: Emitted when the pool is busy.
 141    */
 142   readonly emitter?: PoolEmitter
 143   /**
 144    * Finds the first free worker node key based on the number of tasks the worker has applied.
 145    *
 146    * If a worker is found with `0` running tasks, it is detected as free and its worker node key is returned.
 147    *
 148    * If no free worker is found, `-1` is returned.
 149    *
 150    * @returns A worker node key if there is one, `-1` otherwise.
 151    */
 152   findFreeWorkerNodeKey: () => number
 153   /**
 154    * Finds the last free worker node key based on the number of tasks the worker has applied.
 155    *
 156    * If a worker is found with `0` running tasks, it is detected as free and its worker node key is returned.
 157    *
 158    * If no free worker is found, `-1` is returned.
 159    *
 160    * @returns A worker node key if there is one, `-1` otherwise.
 161    */
 162   findLastFreeWorkerNodeKey: () => number
 163   /**
 164    * Executes the function specified in the worker constructor with the task data input parameter.
 165    *
 166    * @param data - The task input data for the specified worker function. This can only be serializable data.
 167    * @returns Promise that will be fulfilled when the task is completed.
 168    */
 169   execute: (data?: Data) => Promise<Response>
 170   /**
 171    * Shutdowns every current worker in this pool.
 172    */
 173   destroy: () => Promise<void>
 174   /**
 175    * Sets the worker choice strategy in this pool.
 176    *
 177    * @param workerChoiceStrategy - The worker choice strategy.
 178    * @param workerChoiceStrategyOptions - The worker choice strategy options.
 179    */
 180   setWorkerChoiceStrategy: (
 181     workerChoiceStrategy: WorkerChoiceStrategy,
 182     workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
 183   ) => void
 184   /**
 185    * Sets the worker choice strategy options in this pool.
 186    *
 187    * @param workerChoiceStrategyOptions - The worker choice strategy options.
 188    */
 189   setWorkerChoiceStrategyOptions: (
 190     workerChoiceStrategyOptions: WorkerChoiceStrategyOptions
 191   ) => void
 192   /**
 193    * Enables/disables the worker tasks queue in this pool.
 194    *
 195    * @param enable - Whether to enable or disable the worker tasks queue.
 196    * @param tasksQueueOptions - The worker tasks queue options.
 197    */
 198   enableTasksQueue: (
 199     enable: boolean,
 200     tasksQueueOptions?: TasksQueueOptions
 201   ) => void
 202   /**
 203    * Sets the worker tasks queue options in this pool.
 204    *
 205    * @param tasksQueueOptions - The worker tasks queue options.
 206    */
 207   setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void
 208 }