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  */
  20 export enum PoolType {
  21   /**
  22    * Fixed pool type.
  23    */
  24   FIXED = 'fixed',
  25   /**
  26    * Dynamic pool type.
  27    */
  28   DYNAMIC = 'dynamic'
  29 }
  30
  31 /**
  32  * Pool events emitter.
  33  */
  34 export class PoolEmitter extends EventEmitter {}
  35
  36 /**
  37  * Enumeration of pool events.
  38  */
  39 export const PoolEvents = Object.freeze({
  40   full: 'full',
  41   busy: 'busy'
  42 } as const)
  43
  44 /**
  45  * Pool event.
  46  */
  47 export type PoolEvent = keyof typeof PoolEvents
  48
  49 /**
  50  * Worker tasks queue options.
  51  */
  52 export interface TasksQueueOptions {
  53   /**
  54    * Maximum number of tasks that can be executed concurrently on a worker.
  55    *
  56    * @defaultValue 1
  57    */
  58   concurrency?: number
  59 }
  60
  61 /**
  62  * Options for a poolifier pool.
  63  *
  64  * @typeParam Worker - The worker type.
  65  */
  66 export interface PoolOptions<Worker extends IWorker> {
  67   /**
  68    * A function that will listen for message event on each worker.
  69    */
  70   messageHandler?: MessageHandler<Worker>
  71   /**
  72    * A function that will listen for error event on each worker.
  73    */
  74   errorHandler?: ErrorHandler<Worker>
  75   /**
  76    * A function that will listen for online event on each worker.
  77    */
  78   onlineHandler?: OnlineHandler<Worker>
  79   /**
  80    * A function that will listen for exit event on each worker.
  81    */
  82   exitHandler?: ExitHandler<Worker>
  83   /**
  84    * The worker choice strategy to use in this pool.
  85    */
  86   workerChoiceStrategy?: WorkerChoiceStrategy
  87   /**
  88    * The worker choice strategy options.
  89    */
  90   workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
  91   /**
  92    * Pool events emission.
  93    *
  94    * @defaultValue true
  95    */
  96   enableEvents?: boolean
  97   /**
  98    * Pool worker tasks queue.
  99    *
 100    * @experimental
 101    * @defaultValue false
 102    */
 103   enableTasksQueue?: boolean
 104   /**
 105    * Pool worker tasks queue options.
 106    *
 107    * @experimental
 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 a 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    * Performs the task specified in the constructor with the data parameter.
 155    *
 156    * @param data - The input for the specified task. This can only be serializable data.
 157    * @returns Promise that will be resolved when the task is successfully completed.
 158    */
 159   execute: (data: Data) => Promise<Response>
 160   /**
 161    * Shutdowns every current worker in this pool.
 162    */
 163   destroy: () => Promise<void>
 164   /**
 165    * Sets the worker choice strategy in this pool.
 166    *
 167    * @param workerChoiceStrategy - The worker choice strategy.
 168    */
 169   setWorkerChoiceStrategy: (workerChoiceStrategy: WorkerChoiceStrategy) => void
 170 }