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