src/pools/abstract-pool.ts

   1 import EventEmitter from 'events'
   2 import type { MessageValue } from '../utility-types'
   3 import type { IPool } from './pool'
   4
   5 /**
   6  * Callback invoked if the worker raised an error.
   7  */
   8 export type ErrorHandler<Worker> = (this: Worker, e: Error) => void
   9
  10 /**
  11  * Callback invoked when the worker has started successfully.
  12  */
  13 export type OnlineHandler<Worker> = (this: Worker) => void
  14
  15 /**
  16  * Callback invoked when the worker exits successfully.
  17  */
  18 export type ExitHandler<Worker> = (this: Worker, code: number) => void
  19
  20 /**
  21  * Basic interface that describes the minimum required implementation of listener events for a pool-worker.
  22  */
  23 export interface IWorker {
  24   on(event: 'error', handler: ErrorHandler<this>): void
  25   on(event: 'online', handler: OnlineHandler<this>): void
  26   on(event: 'exit', handler: ExitHandler<this>): void
  27 }
  28
  29 /**
  30  * Options for a poolifier pool.
  31  */
  32 export interface PoolOptions<Worker> {
  33   /**
  34    * A function that will listen for error event on each worker.
  35    */
  36   errorHandler?: ErrorHandler<Worker>
  37   /**
  38    * A function that will listen for online event on each worker.
  39    */
  40   onlineHandler?: OnlineHandler<Worker>
  41   /**
  42    * A function that will listen for exit event on each worker.
  43    */
  44   exitHandler?: ExitHandler<Worker>
  45   /**
  46    * This is just to avoid non-useful warning messages.
  47    *
  48    * Will be used to set `maxListeners` on event emitters (workers are event emitters).
  49    *
  50    * @default 1000
  51    * @see [Node events emitter.setMaxListeners(n)](https://nodejs.org/api/events.html#events_emitter_setmaxlisteners_n)
  52    */
  53   maxTasks?: number
  54 }
  55
  56 /**
  57  * Internal poolifier pool emitter.
  58  */
  59 class PoolEmitter extends EventEmitter {}
  60
  61 /**
  62  * Base class containing some shared logic for all poolifier pools.
  63  *
  64  * @template Worker Type of worker which manages this pool.
  65  * @template Data Type of data sent to the worker.
  66  * @template Response Type of response of execution.
  67  */
  68 export abstract class AbstractPool<
  69   Worker extends IWorker,
  70   Data = unknown,
  71   Response = unknown
  72 > implements IPool<Data, Response> {
  73   /**
  74    * List of currently available workers.
  75    */
  76   public readonly workers: Worker[] = []
  77
  78   /**
  79    * Index for the next worker.
  80    */
  81   public nextWorkerIndex: number = 0
  82
  83   /**
  84    * - `key`: The `Worker`
  85    * - `value`: Number of tasks that has been assigned to that worker since it started
  86    */
  87   public readonly tasks: Map<Worker, number> = new Map<Worker, number>()
  88
  89   /**
  90    * Emitter on which events can be listened to.
  91    *
  92    * Events that can currently be listened to:
  93    *
  94    * - `'FullPool'`
  95    */
  96   public readonly emitter: PoolEmitter
  97
  98   /**
  99    * ID of the next message.
 100    */
 101   protected nextMessageId: number = 0
 102
 103   /**
 104    * Constructs a new poolifier pool.
 105    *
 106    * @param numberOfWorkers Number of workers that this pool should manage.
 107    * @param filePath Path to the worker-file.
 108    * @param opts Options for the pool. Default: `{ maxTasks: 1000 }`
 109    */
 110   public constructor (
 111     public readonly numberOfWorkers: number,
 112     public readonly filePath: string,
 113     public readonly opts: PoolOptions<Worker> = { maxTasks: 1000 }
 114   ) {
 115     if (!this.isMain()) {
 116       throw new Error('Cannot start a pool from a worker!')
 117     }
 118     // TODO christopher 2021-02-07: Improve this check e.g. with a pattern or blank check
 119     if (!this.filePath) {
 120       throw new Error('Please specify a file with a worker implementation')
 121     }
 122
 123     this.setupHook()
 124
 125     for (let i = 1; i <= this.numberOfWorkers; i++) {
 126       this.createAndSetupWorker()
 127     }
 128
 129     this.emitter = new PoolEmitter()
 130   }
 131
 132   /**
 133    * Number of workers that this pool should manage.
 134    *
 135    * @returns Number of workers that this pool manages.
 136    * @deprecated Only here for backward compatibility.
 137    */
 138   // eslint-disable-next-line spellcheck/spell-checker
 139   public get numWorkers (): number {
 140     return this.numberOfWorkers
 141   }
 142
 143   /**
 144    * Index for the next worker.
 145    *
 146    * @returns Index for the next worker.
 147    * @deprecated Only here for backward compatibility.
 148    */
 149   public get nextWorker (): number {
 150     return this.nextWorkerIndex
 151   }
 152
 153   public execute (data: Data): Promise<Response> {
 154     // Configure worker to handle message with the specified task
 155     const worker = this.chooseWorker()
 156     this.increaseWorkersTask(worker)
 157     const messageId = ++this.nextMessageId
 158     const res = this.internalExecute(worker, messageId)
 159     this.sendToWorker(worker, { data: data || ({} as Data), id: messageId })
 160     return res
 161   }
 162
 163   public async destroy (): Promise<void> {
 164     for (const worker of this.workers) {
 165       await this.destroyWorker(worker)
 166     }
 167   }
 168
 169   /**
 170    * Shut down given worker.
 171    *
 172    * @param worker A worker within `workers`.
 173    */
 174   protected abstract destroyWorker (worker: Worker): void | Promise<void>
 175
 176   /**
 177    * Setup hook that can be overridden by a Poolifier pool implementation
 178    * to run code before workers are created in the abstract constructor.
 179    */
 180   protected setupHook (): void {
 181     // Can be overridden
 182   }
 183
 184   /**
 185    * Should return whether the worker is the main worker or not.
 186    */
 187   protected abstract isMain (): boolean
 188
 189   /**
 190    * Increase the number of tasks that the given workers has done.
 191    *
 192    * @param worker Workers whose tasks are increased.
 193    */
 194   protected increaseWorkersTask (worker: Worker): void {
 195     const numberOfTasksTheWorkerHas = this.tasks.get(worker)
 196     if (numberOfTasksTheWorkerHas !== undefined) {
 197       this.tasks.set(worker, numberOfTasksTheWorkerHas + 1)
 198     } else {
 199       throw Error('Worker could not be found in tasks map')
 200     }
 201   }
 202
 203   /**
 204    * Removes the given worker from the pool.
 205    *
 206    * @param worker Worker that will be removed.
 207    */
 208   protected removeWorker (worker: Worker): void {
 209     // Clean worker from data structure
 210     const workerIndex = this.workers.indexOf(worker)
 211     this.workers.splice(workerIndex, 1)
 212     this.tasks.delete(worker)
 213   }
 214
 215   /**
 216    * Choose a worker for the next task.
 217    *
 218    * The default implementation uses a round robin algorithm to distribute the load.
 219    *
 220    * @returns Worker.
 221    */
 222   protected chooseWorker (): Worker {
 223     const chosenWorker = this.workers[this.nextWorkerIndex]
 224     this.nextWorkerIndex++
 225     this.nextWorkerIndex %= this.workers.length
 226     return chosenWorker
 227   }
 228
 229   /**
 230    * Send a message to the given worker.
 231    *
 232    * @param worker The worker which should receive the message.
 233    * @param message The message.
 234    */
 235   protected abstract sendToWorker (
 236     worker: Worker,
 237     message: MessageValue<Data>
 238   ): void
 239
 240   protected abstract registerWorkerMessageListener (
 241     port: Worker,
 242     listener: (message: MessageValue<Response>) => void
 243   ): void
 244
 245   protected abstract unregisterWorkerMessageListener (
 246     port: Worker,
 247     listener: (message: MessageValue<Response>) => void
 248   ): void
 249
 250   protected internalExecute (
 251     worker: Worker,
 252     messageId: number
 253   ): Promise<Response> {
 254     return new Promise((resolve, reject) => {
 255       const listener: (message: MessageValue<Response>) => void = message => {
 256         if (message.id === messageId) {
 257           this.unregisterWorkerMessageListener(worker, listener)
 258           this.increaseWorkersTask(worker)
 259           if (message.error) reject(message.error)
 260           else resolve(message.data as Response)
 261         }
 262       }
 263       this.registerWorkerMessageListener(worker, listener)
 264     })
 265   }
 266
 267   /**
 268    * Returns a newly created worker.
 269    */
 270   protected abstract createWorker (): Worker
 271
 272   /**
 273    * Function that can be hooked up when a worker has been newly created and moved to the workers registry.
 274    *
 275    * Can be used to update the `maxListeners` or binding the `main-worker`<->`worker` connection if not bind by default.
 276    *
 277    * @param worker The newly created worker.
 278    */
 279   protected abstract afterWorkerSetup (worker: Worker): void
 280
 281   /**
 282    * Creates a new worker for this pool and sets it up completely.
 283    *
 284    * @returns New, completely set up worker.
 285    */
 286   protected createAndSetupWorker (): Worker {
 287     const worker: Worker = this.createWorker()
 288
 289     worker.on('error', this.opts.errorHandler ?? (() => {}))
 290     worker.on('online', this.opts.onlineHandler ?? (() => {}))
 291     // TODO handle properly when a worker exit
 292     worker.on('exit', this.opts.exitHandler ?? (() => {}))
 293
 294     this.workers.push(worker)
 295
 296     // Init tasks map
 297     this.tasks.set(worker, 0)
 298
 299     this.afterWorkerSetup(worker)
 300
 301     return worker
 302   }
 303 }