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 onEmptyQueueCount: number
  50   private readonly taskFunctionsUsage: Map<string, WorkerUsage>
  51
  52   /**
  53    * Constructs a new worker node.
  54    *
  55    * @param worker - The worker.
  56    * @param tasksQueueBackPressureSize - The tasks queue back pressure size.
  57    */
  58   constructor (worker: Worker, tasksQueueBackPressureSize: number) {
  59     this.checkWorkerNodeArguments(worker, tasksQueueBackPressureSize)
  60     this.worker = worker
  61     this.info = this.initWorkerInfo(worker)
  62     this.usage = this.initWorkerUsage()
  63     if (this.info.type === WorkerTypes.thread) {
  64       this.messageChannel = new MessageChannel()
  65     }
  66     this.tasksQueueBackPressureSize = tasksQueueBackPressureSize
  67     this.tasksQueue = new Deque<Task<Data>>()
  68     this.onEmptyQueueCount = 0
  69     this.taskFunctionsUsage = new Map<string, WorkerUsage>()
  70   }
  71
  72   /** @inheritdoc */
  73   public tasksQueueSize (): number {
  74     return this.tasksQueue.size
  75   }
  76
  77   /** @inheritdoc */
  78   public enqueueTask (task: Task<Data>): number {
  79     const tasksQueueSize = this.tasksQueue.push(task)
  80     if (this.onBackPressure != null && this.hasBackPressure()) {
  81       this.onBackPressure(this.info.id as number)
  82     }
  83     return tasksQueueSize
  84   }
  85
  86   /** @inheritdoc */
  87   public unshiftTask (task: Task<Data>): number {
  88     const tasksQueueSize = this.tasksQueue.unshift(task)
  89     if (this.onBackPressure != null && this.hasBackPressure()) {
  90       this.onBackPressure(this.info.id as number)
  91     }
  92     return tasksQueueSize
  93   }
  94
  95   /** @inheritdoc */
  96   public dequeueTask (): Task<Data> | undefined {
  97     const task = this.tasksQueue.shift()
  98     if (this.onEmptyQueue != null && this.tasksQueue.size === 0) {
  99       this.startOnEmptyQueue().catch(EMPTY_FUNCTION)
 100     }
 101     return task
 102   }
 103
 104   /** @inheritdoc */
 105   public popTask (): Task<Data> | undefined {
 106     const task = this.tasksQueue.pop()
 107     if (this.onEmptyQueue != null && this.tasksQueue.size === 0) {
 108       this.startOnEmptyQueue().catch(EMPTY_FUNCTION)
 109     }
 110     return task
 111   }
 112
 113   /** @inheritdoc */
 114   public clearTasksQueue (): void {
 115     this.tasksQueue.clear()
 116   }
 117
 118   /** @inheritdoc */
 119   public hasBackPressure (): boolean {
 120     return this.tasksQueue.size >= this.tasksQueueBackPressureSize
 121   }
 122
 123   /** @inheritdoc */
 124   public resetUsage (): void {
 125     this.usage = this.initWorkerUsage()
 126     this.taskFunctionsUsage.clear()
 127   }
 128
 129   /** @inheritdoc */
 130   public closeChannel (): void {
 131     if (this.messageChannel != null) {
 132       this.messageChannel?.port1.unref()
 133       this.messageChannel?.port2.unref()
 134       this.messageChannel?.port1.close()
 135       this.messageChannel?.port2.close()
 136       delete this.messageChannel
 137     }
 138   }
 139
 140   /** @inheritdoc */
 141   public getTaskFunctionWorkerUsage (name: string): WorkerUsage | undefined {
 142     if (!Array.isArray(this.info.taskFunctions)) {
 143       throw new Error(
 144         `Cannot get task function worker usage for task function name '${name}' when task function names list is not yet defined`
 145       )
 146     }
 147     if (
 148       Array.isArray(this.info.taskFunctions) &&
 149       this.info.taskFunctions.length < 3
 150     ) {
 151       throw new Error(
 152         `Cannot get task function worker usage for task function name '${name}' when task function names list has less than 3 elements`
 153       )
 154     }
 155     if (name === DEFAULT_TASK_NAME) {
 156       name = this.info.taskFunctions[1]
 157     }
 158     if (!this.taskFunctionsUsage.has(name)) {
 159       this.taskFunctionsUsage.set(name, this.initTaskFunctionWorkerUsage(name))
 160     }
 161     return this.taskFunctionsUsage.get(name)
 162   }
 163
 164   private async startOnEmptyQueue (): Promise<void> {
 165     if (
 166       this.onEmptyQueueCount > 0 &&
 167       (this.usage.tasks.executing > 0 || this.tasksQueue.size > 0)
 168     ) {
 169       this.onEmptyQueueCount = 0
 170       return
 171     }
 172     ;(this.onEmptyQueue as WorkerNodeEventCallback)(this.info.id as number)
 173     ++this.onEmptyQueueCount
 174     await sleep(exponentialDelay(this.onEmptyQueueCount))
 175     await this.startOnEmptyQueue()
 176   }
 177
 178   private initWorkerInfo (worker: Worker): WorkerInfo {
 179     return {
 180       id: getWorkerId(worker),
 181       type: getWorkerType(worker) as WorkerType,
 182       dynamic: false,
 183       ready: false
 184     }
 185   }
 186
 187   private initWorkerUsage (): WorkerUsage {
 188     const getTasksQueueSize = (): number => {
 189       return this.tasksQueue.size
 190     }
 191     const getTasksQueueMaxSize = (): number => {
 192       return this.tasksQueue.maxSize
 193     }
 194     return {
 195       tasks: {
 196         executed: 0,
 197         executing: 0,
 198         get queued (): number {
 199           return getTasksQueueSize()
 200         },
 201         get maxQueued (): number {
 202           return getTasksQueueMaxSize()
 203         },
 204         stolen: 0,
 205         failed: 0
 206       },
 207       runTime: {
 208         history: new CircularArray()
 209       },
 210       waitTime: {
 211         history: new CircularArray()
 212       },
 213       elu: {
 214         idle: {
 215           history: new CircularArray()
 216         },
 217         active: {
 218           history: new CircularArray()
 219         }
 220       }
 221     }
 222   }
 223
 224   private initTaskFunctionWorkerUsage (name: string): WorkerUsage {
 225     const getTaskFunctionQueueSize = (): number => {
 226       let taskFunctionQueueSize = 0
 227       for (const task of this.tasksQueue) {
 228         if (
 229           (task.name === DEFAULT_TASK_NAME &&
 230             name === (this.info.taskFunctions as string[])[1]) ||
 231           (task.name !== DEFAULT_TASK_NAME && name === task.name)
 232         ) {
 233           ++taskFunctionQueueSize
 234         }
 235       }
 236       return taskFunctionQueueSize
 237     }
 238     return {
 239       tasks: {
 240         executed: 0,
 241         executing: 0,
 242         get queued (): number {
 243           return getTaskFunctionQueueSize()
 244         },
 245         stolen: 0,
 246         failed: 0
 247       },
 248       runTime: {
 249         history: new CircularArray()
 250       },
 251       waitTime: {
 252         history: new CircularArray()
 253       },
 254       elu: {
 255         idle: {
 256           history: new CircularArray()
 257         },
 258         active: {
 259           history: new CircularArray()
 260         }
 261       }
 262     }
 263   }
 264
 265   private checkWorkerNodeArguments (
 266     worker: Worker,
 267     tasksQueueBackPressureSize: number
 268   ): void {
 269     if (worker == null) {
 270       throw new TypeError('Cannot construct a worker node without a worker')
 271     }
 272     if (tasksQueueBackPressureSize == null) {
 273       throw new TypeError(
 274         'Cannot construct a worker node without a tasks queue back pressure size'
 275       )
 276     }
 277     if (!Number.isSafeInteger(tasksQueueBackPressureSize)) {
 278       throw new TypeError(
 279         'Cannot construct a worker node with a tasks queue back pressure size that is not an integer'
 280       )
 281     }
 282     if (tasksQueueBackPressureSize <= 0) {
 283       throw new RangeError(
 284         'Cannot construct a worker node with a tasks queue back pressure size that is not a positive integer'
 285       )
 286     }
 287   }
 288 }