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