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 export interface PoolOptions<Worker extends IWorker> {
  65   /**
  66    * A function that will listen for message event on each worker.
  67    */
  68   messageHandler?: MessageHandler<Worker>
  69   /**
  70    * A function that will listen for error event on each worker.
  71    */
  72   errorHandler?: ErrorHandler<Worker>
  73   /**
  74    * A function that will listen for online event on each worker.
  75    */
  76   onlineHandler?: OnlineHandler<Worker>
  77   /**
  78    * A function that will listen for exit event on each worker.
  79    */
  80   exitHandler?: ExitHandler<Worker>
  81   /**
  82    * The worker choice strategy to use in this pool.
  83    */
  84   workerChoiceStrategy?: WorkerChoiceStrategy
  85   /**
  86    * The worker choice strategy options.
  87    */
  88   workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
  89   /**
  90    * Pool events emission.
  91    *
  92    * @defaultValue true
  93    */
  94   enableEvents?: boolean
  95   /**
  96    * Pool worker tasks queue.
  97    *
  98    * @experimental
  99    * @defaultValue false
 100    */
 101   enableTasksQueue?: boolean
 102   /**
 103    * Pool worker tasks queue options.
 104    *
 105    * @experimental
 106    */
 107   tasksQueueOptions?: TasksQueueOptions
 108 }
 109
 110 /**
 111  * Contract definition for a poolifier pool.
 112  *
 113  * @typeParam Worker - Type of worker which manages this pool.
 114  * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
 115  * @typeParam Response - Type of response of execution. This can only be serializable data.
 116  */
 117 export interface IPool<
 118   Worker extends IWorker,
 119   Data = unknown,
 120   Response = unknown
 121 > {
 122   /**
 123    * Pool type.
 124    *
 125    * If it is `'dynamic'`, it provides the `max` property.
 126    */
 127   readonly type: PoolType
 128   /**
 129    * Pool worker nodes.
 130    */
 131   readonly workerNodes: Array<WorkerNode<Worker, Data>>
 132   /**
 133    * Emitter on which events can be listened to.
 134    *
 135    * Events that can currently be listened to:
 136    *
 137    * - `'full'`: Emitted when the pool is dynamic and full.
 138    * - `'busy'`: Emitted when the pool is busy.
 139    */
 140   readonly emitter?: PoolEmitter
 141   /**
 142    * Whether the pool is full or not.
 143    *
 144    * The pool filling boolean status.
 145    */
 146   readonly full: boolean
 147   /**
 148    * Whether the pool is busy or not.
 149    *
 150    * The pool busyness boolean status.
 151    */
 152   readonly busy: boolean
 153   /**
 154    * Finds a 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   findFreeWorkerNodeKey: () => number
 163   /**
 164    * Performs the task specified in the constructor with the data parameter.
 165    *
 166    * @param data - The input for the specified task. This can only be serializable data.
 167    * @returns Promise that will be resolved when the task is successfully 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    */
 179   setWorkerChoiceStrategy: (workerChoiceStrategy: WorkerChoiceStrategy) => void
 180 }