src/pools/worker-node.ts

   1 import { MessageChannel } from 'node:worker_threads'
   2 import { CircularArray } from '../circular-array'
   3 import type { Task } from '../utility-types'
   4 import {
   5   DEFAULT_TASK_NAME,
   6   EMPTY_FUNCTION,
   7   exponentialDelay,
   8   getWorkerId,
   9   getWorkerType,
  10   sleep
  11 } from '../utils'
  12 import { Deque } from '../deque'
  13 import {
  14   type IWorker,
  15   type IWorkerNode,
  16   type StrategyData,
  17   type WorkerInfo,
  18   type WorkerNodeEventCallback,
  19   type WorkerType,
  20   WorkerTypes,
  21   type WorkerUsage
  22 } from './worker'
  23
  24 /**
  25  * Worker node.
  26  *
  27  * @typeParam Worker - Type of worker.
  28  * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
  29  */
  30 export class WorkerNode<Worker extends IWorker, Data = unknown>
  31 implements IWorkerNode<Worker, Data> {
  32   /** @inheritdoc */
  33   public readonly worker: Worker
  34   /** @inheritdoc */
  35   public readonly info: WorkerInfo
  36   /** @inheritdoc */
  37   public usage: WorkerUsage
  38   /** @inheritdoc */
  39   public strategyData?: StrategyData
  40   /** @inheritdoc */
  41   public messageChannel?: MessageChannel
  42   /** @inheritdoc */
  43   public tasksQueueBackPressureSize: number
  44   /** @inheritdoc */
  45   public onBackPressure?: WorkerNodeEventCallback
  46   /** @inheritdoc */
  47   public onEmptyQueue?: WorkerNodeEventCallback
  48   private readonly tasksQueue: Deque<Task<Data>>
  49   private onBackPressureStarted: boolean
  50   private onEmptyQueueCount: number
  51   private readonly taskFunctionsUsage: Map<string, WorkerUsage>
  52
  53   /**
  54    * Constructs a new worker node.
  55    *
  56    * @param worker - The worker.
  57    * @param tasksQueueBackPressureSize - The tasks queue back pressure size.
  58    */
  59   constructor (worker: Worker, tasksQueueBackPressureSize: number) {
  60     this.checkWorkerNodeArguments(worker, tasksQueueBackPressureSize)
  61     this.worker = worker
  62     this.info = this.initWorkerInfo(worker)
  63     this.usage = this.initWorkerUsage()
  64     if (this.info.type === WorkerTypes.thread) {
  65       this.messageChannel = new MessageChannel()
  66     }
  67     this.tasksQueueBackPressureSize = tasksQueueBackPressureSize
  68     this.tasksQueue = new Deque<Task<Data>>()
  69     this.onBackPressureStarted = false
  70     this.onEmptyQueueCount = 0
  71     this.taskFunctionsUsage = new Map<string, WorkerUsage>()
  72   }
  73
  74   /** @inheritdoc */
  75   public tasksQueueSize (): number {
  76     return this.tasksQueue.size
  77   }
  78
  79   /** @inheritdoc */
  80   public enqueueTask (task: Task<Data>): number {
  81     const tasksQueueSize = this.tasksQueue.push(task)
  82     if (
  83       this.onBackPressure != null &&
  84       this.hasBackPressure() &&
  85       !this.onBackPressureStarted
  86     ) {
  87       this.onBackPressureStarted = true
  88       this.onBackPressure(this.info.id as number)
  89       this.onBackPressureStarted = false
  90     }
  91     return tasksQueueSize
  92   }
  93
  94   /** @inheritdoc */
  95   public unshiftTask (task: Task<Data>): number {
  96     const tasksQueueSize = this.tasksQueue.unshift(task)
  97     if (
  98       this.onBackPressure != null &&
  99       this.hasBackPressure() &&
 100       !this.onBackPressureStarted
 101     ) {
 102       this.onBackPressureStarted = true
 103       this.onBackPressure(this.info.id as number)
 104       this.onBackPressureStarted = false
 105     }
 106     return tasksQueueSize
 107   }
 108
 109   /** @inheritdoc */
 110   public dequeueTask (): Task<Data> | undefined {
 111     const task = this.tasksQueue.shift()
 112     if (
 113       this.onEmptyQueue != null &&
 114       this.tasksQueue.size === 0 &&
 115       this.onEmptyQueueCount === 0
 116     ) {
 117       this.startOnEmptyQueue().catch(EMPTY_FUNCTION)
 118     }
 119     return task
 120   }
 121
 122   /** @inheritdoc */
 123   public popTask (): Task<Data> | undefined {
 124     const task = this.tasksQueue.pop()
 125     if (
 126       this.onEmptyQueue != null &&
 127       this.tasksQueue.size === 0 &&
 128       this.onEmptyQueueCount === 0
 129     ) {
 130       this.startOnEmptyQueue().catch(EMPTY_FUNCTION)
 131     }
 132     return task
 133   }
 134
 135   /** @inheritdoc */
 136   public clearTasksQueue (): void {
 137     this.tasksQueue.clear()
 138   }
 139
 140   /** @inheritdoc */
 141   public hasBackPressure (): boolean {
 142     return this.tasksQueue.size >= this.tasksQueueBackPressureSize
 143   }
 144
 145   /** @inheritdoc */
 146   public resetUsage (): void {
 147     this.usage = this.initWorkerUsage()
 148     this.taskFunctionsUsage.clear()
 149   }
 150
 151   /** @inheritdoc */
 152   public closeChannel (): void {
 153     if (this.messageChannel != null) {
 154       this.messageChannel?.port1.unref()
 155       this.messageChannel?.port2.unref()
 156       this.messageChannel?.port1.close()
 157       this.messageChannel?.port2.close()
 158       delete this.messageChannel
 159     }
 160   }
 161
 162   /** @inheritdoc */
 163   public getTaskFunctionWorkerUsage (name: string): WorkerUsage | undefined {
 164     if (!Array.isArray(this.info.taskFunctionNames)) {
 165       throw new Error(
 166         `Cannot get task function worker usage for task function name '${name}' when task function names list is not yet defined`
 167       )
 168     }
 169     if (
 170       Array.isArray(this.info.taskFunctionNames) &&
 171       this.info.taskFunctionNames.length < 3
 172     ) {
 173       throw new Error(
 174         `Cannot get task function worker usage for task function name '${name}' when task function names list has less than 3 elements`
 175       )
 176     }
 177     if (name === DEFAULT_TASK_NAME) {
 178       name = this.info.taskFunctionNames[1]
 179     }
 180     if (!this.taskFunctionsUsage.has(name)) {
 181       this.taskFunctionsUsage.set(name, this.initTaskFunctionWorkerUsage(name))
 182     }
 183     return this.taskFunctionsUsage.get(name)
 184   }
 185
 186   /** @inheritdoc */
 187   public deleteTaskFunctionWorkerUsage (name: string): boolean {
 188     return this.taskFunctionsUsage.delete(name)
 189   }
 190
 191   private async startOnEmptyQueue (): Promise<void> {
 192     if (
 193       this.onEmptyQueueCount > 0 &&
 194       (this.usage.tasks.executing > 0 || this.tasksQueue.size > 0)
 195     ) {
 196       this.onEmptyQueueCount = 0
 197       return
 198     }
 199     ++this.onEmptyQueueCount
 200     this.onEmptyQueue?.(this.info.id as number)
 201     await sleep(exponentialDelay(this.onEmptyQueueCount))
 202     await this.startOnEmptyQueue()
 203   }
 204
 205   private initWorkerInfo (worker: Worker): WorkerInfo {
 206     return {
 207       id: getWorkerId(worker),
 208       type: getWorkerType(worker) as WorkerType,
 209       dynamic: false,
 210       ready: false
 211     }
 212   }
 213
 214   private initWorkerUsage (): WorkerUsage {
 215     const getTasksQueueSize = (): number => {
 216       return this.tasksQueue.size
 217     }
 218     const getTasksQueueMaxSize = (): number => {
 219       return this.tasksQueue.maxSize
 220     }
 221     return {
 222       tasks: {
 223         executed: 0,
 224         executing: 0,
 225         get queued (): number {
 226           return getTasksQueueSize()
 227         },
 228         get maxQueued (): number {
 229           return getTasksQueueMaxSize()
 230         },
 231         stolen: 0,
 232         failed: 0
 233       },
 234       runTime: {
 235         history: new CircularArray()
 236       },
 237       waitTime: {
 238         history: new CircularArray()
 239       },
 240       elu: {
 241         idle: {
 242           history: new CircularArray()
 243         },
 244         active: {
 245           history: new CircularArray()
 246         }
 247       }
 248     }
 249   }
 250
 251   private initTaskFunctionWorkerUsage (name: string): WorkerUsage {
 252     const getTaskFunctionQueueSize = (): number => {
 253       let taskFunctionQueueSize = 0
 254       for (const task of this.tasksQueue) {
 255         if (
 256           (task.name === DEFAULT_TASK_NAME &&
 257             name === (this.info.taskFunctionNames as string[])[1]) ||
 258           (task.name !== DEFAULT_TASK_NAME && name === task.name)
 259         ) {
 260           ++taskFunctionQueueSize
 261         }
 262       }
 263       return taskFunctionQueueSize
 264     }
 265     return {
 266       tasks: {
 267         executed: 0,
 268         executing: 0,
 269         get queued (): number {
 270           return getTaskFunctionQueueSize()
 271         },
 272         stolen: 0,
 273         failed: 0
 274       },
 275       runTime: {
 276         history: new CircularArray()
 277       },
 278       waitTime: {
 279         history: new CircularArray()
 280       },
 281       elu: {
 282         idle: {
 283           history: new CircularArray()
 284         },
 285         active: {
 286           history: new CircularArray()
 287         }
 288       }
 289     }
 290   }
 291
 292   private checkWorkerNodeArguments (
 293     worker: Worker,
 294     tasksQueueBackPressureSize: number
 295   ): void {
 296     if (worker == null) {
 297       throw new TypeError('Cannot construct a worker node without a worker')
 298     }
 299     if (tasksQueueBackPressureSize == null) {
 300       throw new TypeError(
 301         'Cannot construct a worker node without a tasks queue back pressure size'
 302       )
 303     }
 304     if (!Number.isSafeInteger(tasksQueueBackPressureSize)) {
 305       throw new TypeError(
 306         'Cannot construct a worker node with a tasks queue back pressure size that is not an integer'
 307       )
 308     }
 309     if (tasksQueueBackPressureSize <= 0) {
 310       throw new RangeError(
 311         'Cannot construct a worker node with a tasks queue back pressure size that is not a positive integer'
 312       )
 313     }
 314   }
 315 }