Merge pull request #2365 from poolifier/map-execute
[poolifier.git] / src / pools / abstract-pool.ts
1 import { AsyncResource } from 'node:async_hooks'
2 import { randomUUID } from 'node:crypto'
3 import { EventEmitterAsyncResource } from 'node:events'
4 import { performance } from 'node:perf_hooks'
5 import type { TransferListItem } from 'node:worker_threads'
6
7 import { defaultBucketSize } from '../priority-queue.js'
8 import type {
9 MessageValue,
10 PromiseResponseWrapper,
11 Task,
12 TaskFunctionProperties,
13 } from '../utility-types.js'
14 import {
15 average,
16 buildTaskFunctionProperties,
17 DEFAULT_TASK_NAME,
18 EMPTY_FUNCTION,
19 exponentialDelay,
20 isKillBehavior,
21 isPlainObject,
22 max,
23 median,
24 min,
25 round,
26 sleep,
27 } from '../utils.js'
28 import type {
29 TaskFunction,
30 TaskFunctionObject,
31 } from '../worker/task-functions.js'
32 import { KillBehaviors } from '../worker/worker-options.js'
33 import {
34 type IPool,
35 PoolEvents,
36 type PoolInfo,
37 type PoolOptions,
38 type PoolType,
39 PoolTypes,
40 type TasksQueueOptions,
41 } from './pool.js'
42 import {
43 Measurements,
44 WorkerChoiceStrategies,
45 type WorkerChoiceStrategy,
46 type WorkerChoiceStrategyOptions,
47 } from './selection-strategies/selection-strategies-types.js'
48 import { WorkerChoiceStrategiesContext } from './selection-strategies/worker-choice-strategies-context.js'
49 import {
50 checkFilePath,
51 checkValidPriority,
52 checkValidTasksQueueOptions,
53 checkValidWorkerChoiceStrategy,
54 getDefaultTasksQueueOptions,
55 updateEluWorkerUsage,
56 updateRunTimeWorkerUsage,
57 updateTaskStatisticsWorkerUsage,
58 updateWaitTimeWorkerUsage,
59 waitWorkerNodeEvents,
60 } from './utils.js'
61 import { version } from './version.js'
62 import type {
63 IWorker,
64 IWorkerNode,
65 WorkerInfo,
66 WorkerNodeEventDetail,
67 WorkerType,
68 } from './worker.js'
69 import { WorkerNode } from './worker-node.js'
70
71 /**
72 * Base class that implements some shared logic for all poolifier pools.
73 * @typeParam Worker - Type of worker which manages this pool.
74 * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
75 * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
76 */
77 export abstract class AbstractPool<
78 Worker extends IWorker,
79 Data = unknown,
80 Response = unknown
81 > implements IPool<Worker, Data, Response> {
82 /** @inheritDoc */
83 public readonly workerNodes: IWorkerNode<Worker, Data>[] = []
84
85 /** @inheritDoc */
86 public emitter?: EventEmitterAsyncResource
87
88 /**
89 * The task execution response promise map:
90 * - `key`: The message id of each submitted task.
91 * - `value`: An object that contains task's worker node key, execution response promise resolve and reject callbacks, async resource.
92 *
93 * When we receive a message from the worker, we get a map entry with the promise resolve/reject bound to the message id.
94 */
95 protected promiseResponseMap: Map<
96 `${string}-${string}-${string}-${string}-${string}`,
97 PromiseResponseWrapper<Response>
98 > = new Map<
99 `${string}-${string}-${string}-${string}-${string}`,
100 PromiseResponseWrapper<Response>
101 >()
102
103 /**
104 * Worker choice strategies context referencing worker choice algorithms implementation.
105 */
106 protected workerChoiceStrategiesContext?: WorkerChoiceStrategiesContext<
107 Worker,
108 Data,
109 Response
110 >
111
112 /**
113 * The task functions added at runtime map:
114 * - `key`: The task function name.
115 * - `value`: The task function object.
116 */
117 private readonly taskFunctions: Map<
118 string,
119 TaskFunctionObject<Data, Response>
120 >
121
122 /**
123 * Whether the pool is started or not.
124 */
125 private started: boolean
126 /**
127 * Whether the pool is starting or not.
128 */
129 private starting: boolean
130 /**
131 * Whether the pool is destroying or not.
132 */
133 private destroying: boolean
134 /**
135 * Whether the minimum number of workers is starting or not.
136 */
137 private startingMinimumNumberOfWorkers: boolean
138 /**
139 * Whether the pool ready event has been emitted or not.
140 */
141 private readyEventEmitted: boolean
142 /**
143 * The start timestamp of the pool.
144 */
145 private startTimestamp?: number
146
147 /**
148 * Constructs a new poolifier pool.
149 * @param minimumNumberOfWorkers - Minimum number of workers that this pool manages.
150 * @param filePath - Path to the worker file.
151 * @param opts - Options for the pool.
152 * @param maximumNumberOfWorkers - Maximum number of workers that this pool manages.
153 */
154 public constructor (
155 protected readonly minimumNumberOfWorkers: number,
156 protected readonly filePath: string,
157 protected readonly opts: PoolOptions<Worker>,
158 protected readonly maximumNumberOfWorkers?: number
159 ) {
160 if (!this.isMain()) {
161 throw new Error(
162 'Cannot start a pool from a worker with the same type as the pool'
163 )
164 }
165 this.checkPoolType()
166 checkFilePath(this.filePath)
167 this.checkMinimumNumberOfWorkers(this.minimumNumberOfWorkers)
168 this.checkPoolOptions(this.opts)
169
170 this.chooseWorkerNode = this.chooseWorkerNode.bind(this)
171 this.executeTask = this.executeTask.bind(this)
172 this.enqueueTask = this.enqueueTask.bind(this)
173
174 if (this.opts.enableEvents === true) {
175 this.initEventEmitter()
176 }
177 this.workerChoiceStrategiesContext = new WorkerChoiceStrategiesContext<
178 Worker,
179 Data,
180 Response
181 >(
182 this,
183 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
184 [this.opts.workerChoiceStrategy!],
185 this.opts.workerChoiceStrategyOptions
186 )
187
188 this.setupHook()
189
190 this.taskFunctions = new Map<string, TaskFunctionObject<Data, Response>>()
191
192 this.started = false
193 this.starting = false
194 this.destroying = false
195 this.readyEventEmitted = false
196 this.startingMinimumNumberOfWorkers = false
197 if (this.opts.startWorkers === true) {
198 this.start()
199 }
200 }
201
202 private checkPoolType (): void {
203 if (this.type === PoolTypes.fixed && this.maximumNumberOfWorkers != null) {
204 throw new Error(
205 'Cannot instantiate a fixed pool with a maximum number of workers specified at initialization'
206 )
207 }
208 }
209
210 private checkMinimumNumberOfWorkers (
211 minimumNumberOfWorkers: number | undefined
212 ): void {
213 if (minimumNumberOfWorkers == null) {
214 throw new Error(
215 'Cannot instantiate a pool without specifying the number of workers'
216 )
217 } else if (!Number.isSafeInteger(minimumNumberOfWorkers)) {
218 throw new TypeError(
219 'Cannot instantiate a pool with a non safe integer number of workers'
220 )
221 } else if (minimumNumberOfWorkers < 0) {
222 throw new RangeError(
223 'Cannot instantiate a pool with a negative number of workers'
224 )
225 } else if (this.type === PoolTypes.fixed && minimumNumberOfWorkers === 0) {
226 throw new RangeError('Cannot instantiate a fixed pool with zero worker')
227 }
228 }
229
230 private checkPoolOptions (opts: PoolOptions<Worker>): void {
231 if (isPlainObject(opts)) {
232 this.opts.startWorkers = opts.startWorkers ?? true
233 checkValidWorkerChoiceStrategy(opts.workerChoiceStrategy)
234 this.opts.workerChoiceStrategy =
235 opts.workerChoiceStrategy ?? WorkerChoiceStrategies.ROUND_ROBIN
236 this.checkValidWorkerChoiceStrategyOptions(
237 opts.workerChoiceStrategyOptions
238 )
239 if (opts.workerChoiceStrategyOptions != null) {
240 this.opts.workerChoiceStrategyOptions = opts.workerChoiceStrategyOptions
241 }
242 this.opts.restartWorkerOnError = opts.restartWorkerOnError ?? true
243 this.opts.enableEvents = opts.enableEvents ?? true
244 this.opts.enableTasksQueue = opts.enableTasksQueue ?? false
245 if (this.opts.enableTasksQueue) {
246 checkValidTasksQueueOptions(opts.tasksQueueOptions)
247 this.opts.tasksQueueOptions = this.buildTasksQueueOptions(
248 opts.tasksQueueOptions
249 )
250 }
251 } else {
252 throw new TypeError('Invalid pool options: must be a plain object')
253 }
254 }
255
256 private checkValidWorkerChoiceStrategyOptions (
257 workerChoiceStrategyOptions: WorkerChoiceStrategyOptions | undefined
258 ): void {
259 if (
260 workerChoiceStrategyOptions != null &&
261 !isPlainObject(workerChoiceStrategyOptions)
262 ) {
263 throw new TypeError(
264 'Invalid worker choice strategy options: must be a plain object'
265 )
266 }
267 if (
268 workerChoiceStrategyOptions?.weights != null &&
269 Object.keys(workerChoiceStrategyOptions.weights).length !==
270 (this.maximumNumberOfWorkers ?? this.minimumNumberOfWorkers)
271 ) {
272 throw new Error(
273 'Invalid worker choice strategy options: must have a weight for each worker node'
274 )
275 }
276 if (
277 workerChoiceStrategyOptions?.measurement != null &&
278 !Object.values(Measurements).includes(
279 workerChoiceStrategyOptions.measurement
280 )
281 ) {
282 throw new Error(
283 `Invalid worker choice strategy options: invalid measurement '${workerChoiceStrategyOptions.measurement}'`
284 )
285 }
286 }
287
288 private initEventEmitter (): void {
289 this.emitter = new EventEmitterAsyncResource({
290 name: `poolifier:${this.type}-${this.worker}-pool`,
291 })
292 }
293
294 /** @inheritDoc */
295 public get info (): PoolInfo {
296 return {
297 version,
298 type: this.type,
299 worker: this.worker,
300 started: this.started,
301 ready: this.ready,
302 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
303 defaultStrategy: this.opts.workerChoiceStrategy!,
304 strategyRetries: this.workerChoiceStrategiesContext?.retriesCount ?? 0,
305 minSize: this.minimumNumberOfWorkers,
306 maxSize: this.maximumNumberOfWorkers ?? this.minimumNumberOfWorkers,
307 ...(this.workerChoiceStrategiesContext?.getTaskStatisticsRequirements()
308 .runTime.aggregate === true &&
309 this.workerChoiceStrategiesContext.getTaskStatisticsRequirements()
310 .waitTime.aggregate && {
311 utilization: round(this.utilization),
312 }),
313 workerNodes: this.workerNodes.length,
314 idleWorkerNodes: this.workerNodes.reduce(
315 (accumulator, workerNode) =>
316 workerNode.usage.tasks.executing === 0
317 ? accumulator + 1
318 : accumulator,
319 0
320 ),
321 ...(this.opts.enableTasksQueue === true && {
322 stealingWorkerNodes: this.workerNodes.reduce(
323 (accumulator, workerNode) =>
324 workerNode.info.stealing ? accumulator + 1 : accumulator,
325 0
326 ),
327 }),
328 busyWorkerNodes: this.workerNodes.reduce(
329 (accumulator, _, workerNodeKey) =>
330 this.isWorkerNodeBusy(workerNodeKey) ? accumulator + 1 : accumulator,
331 0
332 ),
333 executedTasks: this.workerNodes.reduce(
334 (accumulator, workerNode) =>
335 accumulator + workerNode.usage.tasks.executed,
336 0
337 ),
338 executingTasks: this.workerNodes.reduce(
339 (accumulator, workerNode) =>
340 accumulator + workerNode.usage.tasks.executing,
341 0
342 ),
343 ...(this.opts.enableTasksQueue === true && {
344 queuedTasks: this.workerNodes.reduce(
345 (accumulator, workerNode) =>
346 accumulator + workerNode.usage.tasks.queued,
347 0
348 ),
349 }),
350 ...(this.opts.enableTasksQueue === true && {
351 maxQueuedTasks: this.workerNodes.reduce(
352 (accumulator, workerNode) =>
353 accumulator + (workerNode.usage.tasks.maxQueued ?? 0),
354 0
355 ),
356 }),
357 ...(this.opts.enableTasksQueue === true && {
358 backPressure: this.hasBackPressure(),
359 }),
360 ...(this.opts.enableTasksQueue === true && {
361 stolenTasks: this.workerNodes.reduce(
362 (accumulator, workerNode) =>
363 accumulator + workerNode.usage.tasks.stolen,
364 0
365 ),
366 }),
367 failedTasks: this.workerNodes.reduce(
368 (accumulator, workerNode) =>
369 accumulator + workerNode.usage.tasks.failed,
370 0
371 ),
372 ...(this.workerChoiceStrategiesContext?.getTaskStatisticsRequirements()
373 .runTime.aggregate === true && {
374 runTime: {
375 minimum: round(
376 min(
377 ...this.workerNodes.map(
378 workerNode =>
379 workerNode.usage.runTime.minimum ?? Number.POSITIVE_INFINITY
380 )
381 )
382 ),
383 maximum: round(
384 max(
385 ...this.workerNodes.map(
386 workerNode =>
387 workerNode.usage.runTime.maximum ?? Number.NEGATIVE_INFINITY
388 )
389 )
390 ),
391 ...(this.workerChoiceStrategiesContext.getTaskStatisticsRequirements()
392 .runTime.average && {
393 average: round(
394 average(
395 this.workerNodes.reduce<number[]>(
396 (accumulator, workerNode) =>
397 accumulator.concat(
398 workerNode.usage.runTime.history.toArray()
399 ),
400 []
401 )
402 )
403 ),
404 }),
405 ...(this.workerChoiceStrategiesContext.getTaskStatisticsRequirements()
406 .runTime.median && {
407 median: round(
408 median(
409 this.workerNodes.reduce<number[]>(
410 (accumulator, workerNode) =>
411 accumulator.concat(
412 workerNode.usage.runTime.history.toArray()
413 ),
414 []
415 )
416 )
417 ),
418 }),
419 },
420 }),
421 ...(this.workerChoiceStrategiesContext?.getTaskStatisticsRequirements()
422 .waitTime.aggregate === true && {
423 waitTime: {
424 minimum: round(
425 min(
426 ...this.workerNodes.map(
427 workerNode =>
428 workerNode.usage.waitTime.minimum ?? Number.POSITIVE_INFINITY
429 )
430 )
431 ),
432 maximum: round(
433 max(
434 ...this.workerNodes.map(
435 workerNode =>
436 workerNode.usage.waitTime.maximum ?? Number.NEGATIVE_INFINITY
437 )
438 )
439 ),
440 ...(this.workerChoiceStrategiesContext.getTaskStatisticsRequirements()
441 .waitTime.average && {
442 average: round(
443 average(
444 this.workerNodes.reduce<number[]>(
445 (accumulator, workerNode) =>
446 accumulator.concat(
447 workerNode.usage.waitTime.history.toArray()
448 ),
449 []
450 )
451 )
452 ),
453 }),
454 ...(this.workerChoiceStrategiesContext.getTaskStatisticsRequirements()
455 .waitTime.median && {
456 median: round(
457 median(
458 this.workerNodes.reduce<number[]>(
459 (accumulator, workerNode) =>
460 accumulator.concat(
461 workerNode.usage.waitTime.history.toArray()
462 ),
463 []
464 )
465 )
466 ),
467 }),
468 },
469 }),
470 ...(this.workerChoiceStrategiesContext?.getTaskStatisticsRequirements()
471 .elu.aggregate === true && {
472 elu: {
473 idle: {
474 minimum: round(
475 min(
476 ...this.workerNodes.map(
477 workerNode =>
478 workerNode.usage.elu.idle.minimum ??
479 Number.POSITIVE_INFINITY
480 )
481 )
482 ),
483 maximum: round(
484 max(
485 ...this.workerNodes.map(
486 workerNode =>
487 workerNode.usage.elu.idle.maximum ??
488 Number.NEGATIVE_INFINITY
489 )
490 )
491 ),
492 ...(this.workerChoiceStrategiesContext.getTaskStatisticsRequirements()
493 .elu.average && {
494 average: round(
495 average(
496 this.workerNodes.reduce<number[]>(
497 (accumulator, workerNode) =>
498 accumulator.concat(
499 workerNode.usage.elu.idle.history.toArray()
500 ),
501 []
502 )
503 )
504 ),
505 }),
506 ...(this.workerChoiceStrategiesContext.getTaskStatisticsRequirements()
507 .elu.median && {
508 median: round(
509 median(
510 this.workerNodes.reduce<number[]>(
511 (accumulator, workerNode) =>
512 accumulator.concat(
513 workerNode.usage.elu.idle.history.toArray()
514 ),
515 []
516 )
517 )
518 ),
519 }),
520 },
521 active: {
522 minimum: round(
523 min(
524 ...this.workerNodes.map(
525 workerNode =>
526 workerNode.usage.elu.active.minimum ??
527 Number.POSITIVE_INFINITY
528 )
529 )
530 ),
531 maximum: round(
532 max(
533 ...this.workerNodes.map(
534 workerNode =>
535 workerNode.usage.elu.active.maximum ??
536 Number.NEGATIVE_INFINITY
537 )
538 )
539 ),
540 ...(this.workerChoiceStrategiesContext.getTaskStatisticsRequirements()
541 .elu.average && {
542 average: round(
543 average(
544 this.workerNodes.reduce<number[]>(
545 (accumulator, workerNode) =>
546 accumulator.concat(
547 workerNode.usage.elu.active.history.toArray()
548 ),
549 []
550 )
551 )
552 ),
553 }),
554 ...(this.workerChoiceStrategiesContext.getTaskStatisticsRequirements()
555 .elu.median && {
556 median: round(
557 median(
558 this.workerNodes.reduce<number[]>(
559 (accumulator, workerNode) =>
560 accumulator.concat(
561 workerNode.usage.elu.active.history.toArray()
562 ),
563 []
564 )
565 )
566 ),
567 }),
568 },
569 utilization: {
570 average: round(
571 average(
572 this.workerNodes.map(
573 workerNode => workerNode.usage.elu.utilization ?? 0
574 )
575 )
576 ),
577 median: round(
578 median(
579 this.workerNodes.map(
580 workerNode => workerNode.usage.elu.utilization ?? 0
581 )
582 )
583 ),
584 },
585 },
586 }),
587 }
588 }
589
590 /**
591 * The pool readiness boolean status.
592 */
593 private get ready (): boolean {
594 if (this.empty) {
595 return false
596 }
597 return (
598 this.workerNodes.reduce(
599 (accumulator, workerNode) =>
600 !workerNode.info.dynamic && workerNode.info.ready
601 ? accumulator + 1
602 : accumulator,
603 0
604 ) >= this.minimumNumberOfWorkers
605 )
606 }
607
608 /**
609 * The pool emptiness boolean status.
610 */
611 protected get empty (): boolean {
612 return this.minimumNumberOfWorkers === 0 && this.workerNodes.length === 0
613 }
614
615 /**
616 * The approximate pool utilization.
617 * @returns The pool utilization.
618 */
619 private get utilization (): number {
620 if (this.startTimestamp == null) {
621 return 0
622 }
623 const poolTimeCapacity =
624 (performance.now() - this.startTimestamp) *
625 (this.maximumNumberOfWorkers ?? this.minimumNumberOfWorkers)
626 const totalTasksRunTime = this.workerNodes.reduce(
627 (accumulator, workerNode) =>
628 accumulator + (workerNode.usage.runTime.aggregate ?? 0),
629 0
630 )
631 const totalTasksWaitTime = this.workerNodes.reduce(
632 (accumulator, workerNode) =>
633 accumulator + (workerNode.usage.waitTime.aggregate ?? 0),
634 0
635 )
636 return (totalTasksRunTime + totalTasksWaitTime) / poolTimeCapacity
637 }
638
639 /**
640 * The pool type.
641 *
642 * If it is `'dynamic'`, it provides the `max` property.
643 */
644 protected abstract get type (): PoolType
645
646 /**
647 * The worker type.
648 */
649 protected abstract get worker (): WorkerType
650
651 /**
652 * Checks if the worker id sent in the received message from a worker is valid.
653 * @param message - The received message.
654 * @throws {@link https://nodejs.org/api/errors.html#class-error} If the worker id is invalid.
655 */
656 private checkMessageWorkerId (message: MessageValue<Data | Response>): void {
657 if (message.workerId == null) {
658 throw new Error('Worker message received without worker id')
659 } else if (this.getWorkerNodeKeyByWorkerId(message.workerId) === -1) {
660 throw new Error(
661 `Worker message received from unknown worker '${message.workerId.toString()}'`
662 )
663 }
664 }
665
666 /**
667 * Gets the worker node key given its worker id.
668 * @param workerId - The worker id.
669 * @returns The worker node key if the worker id is found in the pool worker nodes, `-1` otherwise.
670 */
671 private getWorkerNodeKeyByWorkerId (workerId: number | undefined): number {
672 return this.workerNodes.findIndex(
673 workerNode => workerNode.info.id === workerId
674 )
675 }
676
677 /** @inheritDoc */
678 public setWorkerChoiceStrategy (
679 workerChoiceStrategy: WorkerChoiceStrategy,
680 workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
681 ): void {
682 let requireSync = false
683 checkValidWorkerChoiceStrategy(workerChoiceStrategy)
684 if (workerChoiceStrategyOptions != null) {
685 requireSync = !this.setWorkerChoiceStrategyOptions(
686 workerChoiceStrategyOptions
687 )
688 }
689 if (workerChoiceStrategy !== this.opts.workerChoiceStrategy) {
690 this.opts.workerChoiceStrategy = workerChoiceStrategy
691 this.workerChoiceStrategiesContext?.setDefaultWorkerChoiceStrategy(
692 this.opts.workerChoiceStrategy,
693 this.opts.workerChoiceStrategyOptions
694 )
695 requireSync = true
696 }
697 if (requireSync) {
698 this.workerChoiceStrategiesContext?.syncWorkerChoiceStrategies(
699 this.getWorkerChoiceStrategies(),
700 this.opts.workerChoiceStrategyOptions
701 )
702 for (const workerNodeKey of this.workerNodes.keys()) {
703 this.sendStatisticsMessageToWorker(workerNodeKey)
704 }
705 }
706 }
707
708 /** @inheritDoc */
709 public setWorkerChoiceStrategyOptions (
710 workerChoiceStrategyOptions: WorkerChoiceStrategyOptions | undefined
711 ): boolean {
712 this.checkValidWorkerChoiceStrategyOptions(workerChoiceStrategyOptions)
713 if (workerChoiceStrategyOptions != null) {
714 this.opts.workerChoiceStrategyOptions = workerChoiceStrategyOptions
715 this.workerChoiceStrategiesContext?.setOptions(
716 this.opts.workerChoiceStrategyOptions
717 )
718 this.workerChoiceStrategiesContext?.syncWorkerChoiceStrategies(
719 this.getWorkerChoiceStrategies(),
720 this.opts.workerChoiceStrategyOptions
721 )
722 for (const workerNodeKey of this.workerNodes.keys()) {
723 this.sendStatisticsMessageToWorker(workerNodeKey)
724 }
725 return true
726 }
727 return false
728 }
729
730 /** @inheritDoc */
731 public enableTasksQueue (
732 enable: boolean,
733 tasksQueueOptions?: TasksQueueOptions
734 ): void {
735 if (this.opts.enableTasksQueue === true && !enable) {
736 this.unsetTaskStealing()
737 this.unsetTasksStealingOnBackPressure()
738 this.flushTasksQueues()
739 }
740 this.opts.enableTasksQueue = enable
741 this.setTasksQueueOptions(tasksQueueOptions)
742 }
743
744 /** @inheritDoc */
745 public setTasksQueueOptions (
746 tasksQueueOptions: TasksQueueOptions | undefined
747 ): void {
748 if (this.opts.enableTasksQueue === true) {
749 checkValidTasksQueueOptions(tasksQueueOptions)
750 this.opts.tasksQueueOptions =
751 this.buildTasksQueueOptions(tasksQueueOptions)
752 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
753 this.setTasksQueueSize(this.opts.tasksQueueOptions.size!)
754 if (this.opts.tasksQueueOptions.taskStealing === true) {
755 this.unsetTaskStealing()
756 this.setTaskStealing()
757 } else {
758 this.unsetTaskStealing()
759 }
760 if (this.opts.tasksQueueOptions.tasksStealingOnBackPressure === true) {
761 this.unsetTasksStealingOnBackPressure()
762 this.setTasksStealingOnBackPressure()
763 } else {
764 this.unsetTasksStealingOnBackPressure()
765 }
766 } else if (this.opts.tasksQueueOptions != null) {
767 delete this.opts.tasksQueueOptions
768 }
769 }
770
771 private buildTasksQueueOptions (
772 tasksQueueOptions: TasksQueueOptions | undefined
773 ): TasksQueueOptions {
774 return {
775 ...getDefaultTasksQueueOptions(
776 this.maximumNumberOfWorkers ?? this.minimumNumberOfWorkers
777 ),
778 ...tasksQueueOptions,
779 }
780 }
781
782 private setTasksQueueSize (size: number): void {
783 for (const workerNode of this.workerNodes) {
784 workerNode.tasksQueueBackPressureSize = size
785 }
786 }
787
788 private setTaskStealing (): void {
789 for (const workerNodeKey of this.workerNodes.keys()) {
790 this.workerNodes[workerNodeKey].on('idle', this.handleWorkerNodeIdleEvent)
791 }
792 }
793
794 private unsetTaskStealing (): void {
795 for (const workerNodeKey of this.workerNodes.keys()) {
796 this.workerNodes[workerNodeKey].off(
797 'idle',
798 this.handleWorkerNodeIdleEvent
799 )
800 }
801 }
802
803 private setTasksStealingOnBackPressure (): void {
804 for (const workerNodeKey of this.workerNodes.keys()) {
805 this.workerNodes[workerNodeKey].on(
806 'backPressure',
807 this.handleWorkerNodeBackPressureEvent
808 )
809 }
810 }
811
812 private unsetTasksStealingOnBackPressure (): void {
813 for (const workerNodeKey of this.workerNodes.keys()) {
814 this.workerNodes[workerNodeKey].off(
815 'backPressure',
816 this.handleWorkerNodeBackPressureEvent
817 )
818 }
819 }
820
821 /**
822 * Whether the pool is full or not.
823 *
824 * The pool filling boolean status.
825 */
826 protected get full (): boolean {
827 return (
828 this.workerNodes.length >=
829 (this.maximumNumberOfWorkers ?? this.minimumNumberOfWorkers)
830 )
831 }
832
833 /**
834 * Whether the pool is busy or not.
835 *
836 * The pool busyness boolean status.
837 */
838 protected abstract get busy (): boolean
839
840 /**
841 * Whether worker nodes are executing concurrently their tasks quota or not.
842 * @returns Worker nodes busyness boolean status.
843 */
844 protected internalBusy (): boolean {
845 if (this.opts.enableTasksQueue === true) {
846 return (
847 this.workerNodes.findIndex(
848 workerNode =>
849 workerNode.info.ready &&
850 workerNode.usage.tasks.executing <
851 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
852 this.opts.tasksQueueOptions!.concurrency!
853 ) === -1
854 )
855 }
856 return (
857 this.workerNodes.findIndex(
858 workerNode =>
859 workerNode.info.ready && workerNode.usage.tasks.executing === 0
860 ) === -1
861 )
862 }
863
864 private isWorkerNodeBusy (workerNodeKey: number): boolean {
865 if (this.opts.enableTasksQueue === true) {
866 return (
867 this.workerNodes[workerNodeKey].usage.tasks.executing >=
868 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
869 this.opts.tasksQueueOptions!.concurrency!
870 )
871 }
872 return this.workerNodes[workerNodeKey].usage.tasks.executing > 0
873 }
874
875 private async sendTaskFunctionOperationToWorker (
876 workerNodeKey: number,
877 message: MessageValue<Data>
878 ): Promise<boolean> {
879 return await new Promise<boolean>((resolve, reject) => {
880 const taskFunctionOperationListener = (
881 message: MessageValue<Response>
882 ): void => {
883 this.checkMessageWorkerId(message)
884 const workerId = this.getWorkerInfo(workerNodeKey)?.id
885 if (
886 message.taskFunctionOperationStatus != null &&
887 message.workerId === workerId
888 ) {
889 if (message.taskFunctionOperationStatus) {
890 resolve(true)
891 } else {
892 reject(
893 new Error(
894 // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
895 `Task function operation '${message.taskFunctionOperation?.toString()}' failed on worker ${message.workerId?.toString()} with error: '${
896 // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
897 message.workerError?.message
898 }'`
899 )
900 )
901 }
902 this.deregisterWorkerMessageListener(
903 this.getWorkerNodeKeyByWorkerId(message.workerId),
904 taskFunctionOperationListener
905 )
906 }
907 }
908 this.registerWorkerMessageListener(
909 workerNodeKey,
910 taskFunctionOperationListener
911 )
912 this.sendToWorker(workerNodeKey, message)
913 })
914 }
915
916 private async sendTaskFunctionOperationToWorkers (
917 message: MessageValue<Data>
918 ): Promise<boolean> {
919 return await new Promise<boolean>((resolve, reject) => {
920 const responsesReceived = new Array<MessageValue<Response>>()
921 const taskFunctionOperationsListener = (
922 message: MessageValue<Response>
923 ): void => {
924 this.checkMessageWorkerId(message)
925 if (message.taskFunctionOperationStatus != null) {
926 responsesReceived.push(message)
927 if (responsesReceived.length === this.workerNodes.length) {
928 if (
929 responsesReceived.every(
930 message => message.taskFunctionOperationStatus === true
931 )
932 ) {
933 resolve(true)
934 } else if (
935 responsesReceived.some(
936 message => message.taskFunctionOperationStatus === false
937 )
938 ) {
939 const errorResponse = responsesReceived.find(
940 response => response.taskFunctionOperationStatus === false
941 )
942 reject(
943 new Error(
944 `Task function operation '${
945 message.taskFunctionOperation as string
946 // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
947 }' failed on worker ${errorResponse?.workerId?.toString()} with error: '${
948 // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
949 errorResponse?.workerError?.message
950 }'`
951 )
952 )
953 }
954 this.deregisterWorkerMessageListener(
955 this.getWorkerNodeKeyByWorkerId(message.workerId),
956 taskFunctionOperationsListener
957 )
958 }
959 }
960 }
961 for (const workerNodeKey of this.workerNodes.keys()) {
962 this.registerWorkerMessageListener(
963 workerNodeKey,
964 taskFunctionOperationsListener
965 )
966 this.sendToWorker(workerNodeKey, message)
967 }
968 })
969 }
970
971 /** @inheritDoc */
972 public hasTaskFunction (name: string): boolean {
973 return this.listTaskFunctionsProperties().some(
974 taskFunctionProperties => taskFunctionProperties.name === name
975 )
976 }
977
978 /** @inheritDoc */
979 public async addTaskFunction (
980 name: string,
981 fn: TaskFunction<Data, Response> | TaskFunctionObject<Data, Response>
982 ): Promise<boolean> {
983 if (typeof name !== 'string') {
984 throw new TypeError('name argument must be a string')
985 }
986 if (typeof name === 'string' && name.trim().length === 0) {
987 throw new TypeError('name argument must not be an empty string')
988 }
989 if (typeof fn === 'function') {
990 fn = { taskFunction: fn } satisfies TaskFunctionObject<Data, Response>
991 }
992 if (typeof fn.taskFunction !== 'function') {
993 throw new TypeError('taskFunction property must be a function')
994 }
995 checkValidPriority(fn.priority)
996 checkValidWorkerChoiceStrategy(fn.strategy)
997 const opResult = await this.sendTaskFunctionOperationToWorkers({
998 taskFunctionOperation: 'add',
999 taskFunctionProperties: buildTaskFunctionProperties(name, fn),
1000 taskFunction: fn.taskFunction.toString(),
1001 })
1002 this.taskFunctions.set(name, fn)
1003 this.workerChoiceStrategiesContext?.syncWorkerChoiceStrategies(
1004 this.getWorkerChoiceStrategies()
1005 )
1006 for (const workerNodeKey of this.workerNodes.keys()) {
1007 this.sendStatisticsMessageToWorker(workerNodeKey)
1008 }
1009 return opResult
1010 }
1011
1012 /** @inheritDoc */
1013 public async removeTaskFunction (name: string): Promise<boolean> {
1014 if (!this.taskFunctions.has(name)) {
1015 throw new Error(
1016 'Cannot remove a task function not handled on the pool side'
1017 )
1018 }
1019 const opResult = await this.sendTaskFunctionOperationToWorkers({
1020 taskFunctionOperation: 'remove',
1021 taskFunctionProperties: buildTaskFunctionProperties(
1022 name,
1023 this.taskFunctions.get(name)
1024 ),
1025 })
1026 for (const workerNode of this.workerNodes) {
1027 workerNode.deleteTaskFunctionWorkerUsage(name)
1028 }
1029 this.taskFunctions.delete(name)
1030 this.workerChoiceStrategiesContext?.syncWorkerChoiceStrategies(
1031 this.getWorkerChoiceStrategies()
1032 )
1033 for (const workerNodeKey of this.workerNodes.keys()) {
1034 this.sendStatisticsMessageToWorker(workerNodeKey)
1035 }
1036 return opResult
1037 }
1038
1039 /** @inheritDoc */
1040 public listTaskFunctionsProperties (): TaskFunctionProperties[] {
1041 for (const workerNode of this.workerNodes) {
1042 if (
1043 Array.isArray(workerNode.info.taskFunctionsProperties) &&
1044 workerNode.info.taskFunctionsProperties.length > 0
1045 ) {
1046 return workerNode.info.taskFunctionsProperties
1047 }
1048 }
1049 return []
1050 }
1051
1052 /**
1053 * Gets task function worker choice strategy, if any.
1054 * @param name - The task function name.
1055 * @returns The task function worker choice strategy if the task function worker choice strategy is defined, `undefined` otherwise.
1056 */
1057 private readonly getTaskFunctionWorkerChoiceStrategy = (
1058 name?: string
1059 ): WorkerChoiceStrategy | undefined => {
1060 name = name ?? DEFAULT_TASK_NAME
1061 const taskFunctionsProperties = this.listTaskFunctionsProperties()
1062 if (name === DEFAULT_TASK_NAME) {
1063 name = taskFunctionsProperties[1]?.name
1064 }
1065 return taskFunctionsProperties.find(
1066 (taskFunctionProperties: TaskFunctionProperties) =>
1067 taskFunctionProperties.name === name
1068 )?.strategy
1069 }
1070
1071 /**
1072 * Gets worker node task function worker choice strategy, if any.
1073 * @param workerNodeKey - The worker node key.
1074 * @param name - The task function name.
1075 * @returns The worker node task function worker choice strategy if the worker node task function worker choice strategy is defined, `undefined` otherwise.
1076 */
1077 private readonly getWorkerNodeTaskFunctionWorkerChoiceStrategy = (
1078 workerNodeKey: number,
1079 name?: string
1080 ): WorkerChoiceStrategy | undefined => {
1081 const workerInfo = this.getWorkerInfo(workerNodeKey)
1082 if (workerInfo == null) {
1083 return
1084 }
1085 name = name ?? DEFAULT_TASK_NAME
1086 if (name === DEFAULT_TASK_NAME) {
1087 name = workerInfo.taskFunctionsProperties?.[1]?.name
1088 }
1089 return workerInfo.taskFunctionsProperties?.find(
1090 (taskFunctionProperties: TaskFunctionProperties) =>
1091 taskFunctionProperties.name === name
1092 )?.strategy
1093 }
1094
1095 /**
1096 * Gets worker node task function priority, if any.
1097 * @param workerNodeKey - The worker node key.
1098 * @param name - The task function name.
1099 * @returns The worker node task function priority if the worker node task function priority is defined, `undefined` otherwise.
1100 */
1101 private readonly getWorkerNodeTaskFunctionPriority = (
1102 workerNodeKey: number,
1103 name?: string
1104 ): number | undefined => {
1105 const workerInfo = this.getWorkerInfo(workerNodeKey)
1106 if (workerInfo == null) {
1107 return
1108 }
1109 name = name ?? DEFAULT_TASK_NAME
1110 if (name === DEFAULT_TASK_NAME) {
1111 name = workerInfo.taskFunctionsProperties?.[1]?.name
1112 }
1113 return workerInfo.taskFunctionsProperties?.find(
1114 (taskFunctionProperties: TaskFunctionProperties) =>
1115 taskFunctionProperties.name === name
1116 )?.priority
1117 }
1118
1119 /**
1120 * Gets the worker choice strategies registered in this pool.
1121 * @returns The worker choice strategies.
1122 */
1123 private readonly getWorkerChoiceStrategies =
1124 (): Set<WorkerChoiceStrategy> => {
1125 return new Set([
1126 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1127 this.opts.workerChoiceStrategy!,
1128 ...(this.listTaskFunctionsProperties()
1129 .map(
1130 (taskFunctionProperties: TaskFunctionProperties) =>
1131 taskFunctionProperties.strategy
1132 )
1133 .filter(
1134 (strategy: WorkerChoiceStrategy | undefined) => strategy != null
1135 ) as WorkerChoiceStrategy[]),
1136 ])
1137 }
1138
1139 /** @inheritDoc */
1140 public async setDefaultTaskFunction (name: string): Promise<boolean> {
1141 return await this.sendTaskFunctionOperationToWorkers({
1142 taskFunctionOperation: 'default',
1143 taskFunctionProperties: buildTaskFunctionProperties(
1144 name,
1145 this.taskFunctions.get(name)
1146 ),
1147 })
1148 }
1149
1150 private shallExecuteTask (workerNodeKey: number): boolean {
1151 return (
1152 this.tasksQueueSize(workerNodeKey) === 0 &&
1153 this.workerNodes[workerNodeKey].usage.tasks.executing <
1154 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1155 this.opts.tasksQueueOptions!.concurrency!
1156 )
1157 }
1158
1159 /** @inheritDoc */
1160 public async execute (
1161 data?: Data,
1162 name?: string,
1163 transferList?: readonly TransferListItem[]
1164 ): Promise<Response> {
1165 return await new Promise<Response>((resolve, reject) => {
1166 if (!this.started) {
1167 reject(new Error('Cannot execute a task on not started pool'))
1168 return
1169 }
1170 if (this.destroying) {
1171 reject(new Error('Cannot execute a task on destroying pool'))
1172 return
1173 }
1174 if (name != null && typeof name !== 'string') {
1175 reject(new TypeError('name argument must be a string'))
1176 return
1177 }
1178 if (
1179 name != null &&
1180 typeof name === 'string' &&
1181 name.trim().length === 0
1182 ) {
1183 reject(new TypeError('name argument must not be an empty string'))
1184 return
1185 }
1186 if (transferList != null && !Array.isArray(transferList)) {
1187 reject(new TypeError('transferList argument must be an array'))
1188 return
1189 }
1190 const timestamp = performance.now()
1191 const workerNodeKey = this.chooseWorkerNode(name)
1192 const task: Task<Data> = {
1193 name: name ?? DEFAULT_TASK_NAME,
1194 data: data ?? ({} as Data),
1195 priority: this.getWorkerNodeTaskFunctionPriority(workerNodeKey, name),
1196 strategy: this.getWorkerNodeTaskFunctionWorkerChoiceStrategy(
1197 workerNodeKey,
1198 name
1199 ),
1200 transferList,
1201 timestamp,
1202 taskId: randomUUID(),
1203 }
1204 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1205 this.promiseResponseMap.set(task.taskId!, {
1206 resolve,
1207 reject,
1208 workerNodeKey,
1209 ...(this.emitter != null && {
1210 asyncResource: new AsyncResource('poolifier:task', {
1211 triggerAsyncId: this.emitter.asyncId,
1212 requireManualDestroy: true,
1213 }),
1214 }),
1215 })
1216 if (
1217 this.opts.enableTasksQueue === false ||
1218 (this.opts.enableTasksQueue === true &&
1219 this.shallExecuteTask(workerNodeKey))
1220 ) {
1221 this.executeTask(workerNodeKey, task)
1222 } else {
1223 this.enqueueTask(workerNodeKey, task)
1224 }
1225 })
1226 }
1227
1228
1229 /** @inheritDoc */
1230 public mapExecute (
1231 data: Iterable<Data>,
1232 name?: string,
1233 transferList?: readonly TransferListItem[]
1234 ): Promise<Response[]> {
1235 return Promise.all(
1236 [...data].map(data => this.execute(data, name, transferList))
1237 )
1238 }
1239
1240 /**
1241 * Starts the minimum number of workers.
1242 * @param initWorkerNodeUsage - Whether to initialize the worker node usage or not. @defaultValue false
1243 */
1244 private startMinimumNumberOfWorkers (initWorkerNodeUsage = false): void {
1245 this.startingMinimumNumberOfWorkers = true
1246 while (
1247 this.workerNodes.reduce(
1248 (accumulator, workerNode) =>
1249 !workerNode.info.dynamic ? accumulator + 1 : accumulator,
1250 0
1251 ) < this.minimumNumberOfWorkers
1252 ) {
1253 const workerNodeKey = this.createAndSetupWorkerNode()
1254 initWorkerNodeUsage &&
1255 this.initWorkerNodeUsage(this.workerNodes[workerNodeKey])
1256 }
1257 this.startingMinimumNumberOfWorkers = false
1258 }
1259
1260 /** @inheritdoc */
1261 public start (): void {
1262 if (this.started) {
1263 throw new Error('Cannot start an already started pool')
1264 }
1265 if (this.starting) {
1266 throw new Error('Cannot start an already starting pool')
1267 }
1268 if (this.destroying) {
1269 throw new Error('Cannot start a destroying pool')
1270 }
1271 this.starting = true
1272 this.startMinimumNumberOfWorkers()
1273 this.startTimestamp = performance.now()
1274 this.starting = false
1275 this.started = true
1276 }
1277
1278 /** @inheritDoc */
1279 public async destroy (): Promise<void> {
1280 if (!this.started) {
1281 throw new Error('Cannot destroy an already destroyed pool')
1282 }
1283 if (this.starting) {
1284 throw new Error('Cannot destroy an starting pool')
1285 }
1286 if (this.destroying) {
1287 throw new Error('Cannot destroy an already destroying pool')
1288 }
1289 this.destroying = true
1290 await Promise.all(
1291 this.workerNodes.map(async (_, workerNodeKey) => {
1292 await this.destroyWorkerNode(workerNodeKey)
1293 })
1294 )
1295 this.emitter?.emit(PoolEvents.destroy, this.info)
1296 this.emitter?.emitDestroy()
1297 this.readyEventEmitted = false
1298 delete this.startTimestamp
1299 this.destroying = false
1300 this.started = false
1301 }
1302
1303 private async sendKillMessageToWorker (workerNodeKey: number): Promise<void> {
1304 await new Promise<void>((resolve, reject) => {
1305 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
1306 if (this.workerNodes[workerNodeKey] == null) {
1307 resolve()
1308 return
1309 }
1310 const killMessageListener = (message: MessageValue<Response>): void => {
1311 this.checkMessageWorkerId(message)
1312 if (message.kill === 'success') {
1313 resolve()
1314 } else if (message.kill === 'failure') {
1315 reject(
1316 new Error(
1317 // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
1318 `Kill message handling failed on worker ${message.workerId?.toString()}`
1319 )
1320 )
1321 }
1322 }
1323 // FIXME: should be registered only once
1324 this.registerWorkerMessageListener(workerNodeKey, killMessageListener)
1325 this.sendToWorker(workerNodeKey, { kill: true })
1326 })
1327 }
1328
1329 /**
1330 * Terminates the worker node given its worker node key.
1331 * @param workerNodeKey - The worker node key.
1332 */
1333 protected async destroyWorkerNode (workerNodeKey: number): Promise<void> {
1334 this.flagWorkerNodeAsNotReady(workerNodeKey)
1335 const flushedTasks = this.flushTasksQueue(workerNodeKey)
1336 const workerNode = this.workerNodes[workerNodeKey]
1337 await waitWorkerNodeEvents(
1338 workerNode,
1339 'taskFinished',
1340 flushedTasks,
1341 this.opts.tasksQueueOptions?.tasksFinishedTimeout ??
1342 getDefaultTasksQueueOptions(
1343 this.maximumNumberOfWorkers ?? this.minimumNumberOfWorkers
1344 ).tasksFinishedTimeout
1345 )
1346 await this.sendKillMessageToWorker(workerNodeKey)
1347 await workerNode.terminate()
1348 }
1349
1350 /**
1351 * Setup hook to execute code before worker nodes are created in the abstract constructor.
1352 * Can be overridden.
1353 */
1354 protected setupHook (): void {
1355 /* Intentionally empty */
1356 }
1357
1358 /**
1359 * Returns whether the worker is the main worker or not.
1360 * @returns `true` if the worker is the main worker, `false` otherwise.
1361 */
1362 protected abstract isMain (): boolean
1363
1364 /**
1365 * Hook executed before the worker task execution.
1366 * Can be overridden.
1367 * @param workerNodeKey - The worker node key.
1368 * @param task - The task to execute.
1369 */
1370 protected beforeTaskExecutionHook (
1371 workerNodeKey: number,
1372 task: Task<Data>
1373 ): void {
1374 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
1375 if (this.workerNodes[workerNodeKey]?.usage != null) {
1376 const workerUsage = this.workerNodes[workerNodeKey].usage
1377 ++workerUsage.tasks.executing
1378 updateWaitTimeWorkerUsage(
1379 this.workerChoiceStrategiesContext,
1380 workerUsage,
1381 task
1382 )
1383 }
1384 if (
1385 this.shallUpdateTaskFunctionWorkerUsage(workerNodeKey) &&
1386 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1387 this.workerNodes[workerNodeKey].getTaskFunctionWorkerUsage(task.name!) !=
1388 null
1389 ) {
1390 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1391 const taskFunctionWorkerUsage = this.workerNodes[
1392 workerNodeKey
1393 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1394 ].getTaskFunctionWorkerUsage(task.name!)!
1395 ++taskFunctionWorkerUsage.tasks.executing
1396 updateWaitTimeWorkerUsage(
1397 this.workerChoiceStrategiesContext,
1398 taskFunctionWorkerUsage,
1399 task
1400 )
1401 }
1402 }
1403
1404 /**
1405 * Hook executed after the worker task execution.
1406 * Can be overridden.
1407 * @param workerNodeKey - The worker node key.
1408 * @param message - The received message.
1409 */
1410 protected afterTaskExecutionHook (
1411 workerNodeKey: number,
1412 message: MessageValue<Response>
1413 ): void {
1414 let needWorkerChoiceStrategiesUpdate = false
1415 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
1416 if (this.workerNodes[workerNodeKey]?.usage != null) {
1417 const workerUsage = this.workerNodes[workerNodeKey].usage
1418 updateTaskStatisticsWorkerUsage(workerUsage, message)
1419 updateRunTimeWorkerUsage(
1420 this.workerChoiceStrategiesContext,
1421 workerUsage,
1422 message
1423 )
1424 updateEluWorkerUsage(
1425 this.workerChoiceStrategiesContext,
1426 workerUsage,
1427 message
1428 )
1429 needWorkerChoiceStrategiesUpdate = true
1430 }
1431 if (
1432 this.shallUpdateTaskFunctionWorkerUsage(workerNodeKey) &&
1433 this.workerNodes[workerNodeKey].getTaskFunctionWorkerUsage(
1434 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1435 message.taskPerformance!.name
1436 ) != null
1437 ) {
1438 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1439 const taskFunctionWorkerUsage = this.workerNodes[
1440 workerNodeKey
1441 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1442 ].getTaskFunctionWorkerUsage(message.taskPerformance!.name)!
1443 updateTaskStatisticsWorkerUsage(taskFunctionWorkerUsage, message)
1444 updateRunTimeWorkerUsage(
1445 this.workerChoiceStrategiesContext,
1446 taskFunctionWorkerUsage,
1447 message
1448 )
1449 updateEluWorkerUsage(
1450 this.workerChoiceStrategiesContext,
1451 taskFunctionWorkerUsage,
1452 message
1453 )
1454 needWorkerChoiceStrategiesUpdate = true
1455 }
1456 if (needWorkerChoiceStrategiesUpdate) {
1457 this.workerChoiceStrategiesContext?.update(workerNodeKey)
1458 }
1459 }
1460
1461 /**
1462 * Whether the worker node shall update its task function worker usage or not.
1463 * @param workerNodeKey - The worker node key.
1464 * @returns `true` if the worker node shall update its task function worker usage, `false` otherwise.
1465 */
1466 private shallUpdateTaskFunctionWorkerUsage (workerNodeKey: number): boolean {
1467 const workerInfo = this.getWorkerInfo(workerNodeKey)
1468 return (
1469 workerInfo != null &&
1470 Array.isArray(workerInfo.taskFunctionsProperties) &&
1471 workerInfo.taskFunctionsProperties.length > 2
1472 )
1473 }
1474
1475 /**
1476 * Chooses a worker node for the next task.
1477 * @param name - The task function name.
1478 * @returns The chosen worker node key.
1479 */
1480 private chooseWorkerNode (name?: string): number {
1481 if (this.shallCreateDynamicWorker()) {
1482 const workerNodeKey = this.createAndSetupDynamicWorkerNode()
1483 if (
1484 this.workerChoiceStrategiesContext?.getPolicy().dynamicWorkerUsage ===
1485 true
1486 ) {
1487 return workerNodeKey
1488 }
1489 }
1490 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1491 return this.workerChoiceStrategiesContext!.execute(
1492 this.getTaskFunctionWorkerChoiceStrategy(name)
1493 )
1494 }
1495
1496 /**
1497 * Conditions for dynamic worker creation.
1498 * @returns Whether to create a dynamic worker or not.
1499 */
1500 protected abstract shallCreateDynamicWorker (): boolean
1501
1502 /**
1503 * Sends a message to worker given its worker node key.
1504 * @param workerNodeKey - The worker node key.
1505 * @param message - The message.
1506 * @param transferList - The optional array of transferable objects.
1507 */
1508 protected abstract sendToWorker (
1509 workerNodeKey: number,
1510 message: MessageValue<Data>,
1511 transferList?: readonly TransferListItem[]
1512 ): void
1513
1514 /**
1515 * Initializes the worker node usage with sensible default values gathered during runtime.
1516 * @param workerNode - The worker node.
1517 */
1518 private initWorkerNodeUsage (workerNode: IWorkerNode<Worker, Data>): void {
1519 if (
1520 this.workerChoiceStrategiesContext?.getTaskStatisticsRequirements()
1521 .runTime.aggregate === true
1522 ) {
1523 workerNode.usage.runTime.aggregate = min(
1524 ...this.workerNodes.map(
1525 workerNode =>
1526 workerNode.usage.runTime.aggregate ?? Number.POSITIVE_INFINITY
1527 )
1528 )
1529 }
1530 if (
1531 this.workerChoiceStrategiesContext?.getTaskStatisticsRequirements()
1532 .waitTime.aggregate === true
1533 ) {
1534 workerNode.usage.waitTime.aggregate = min(
1535 ...this.workerNodes.map(
1536 workerNode =>
1537 workerNode.usage.waitTime.aggregate ?? Number.POSITIVE_INFINITY
1538 )
1539 )
1540 }
1541 if (
1542 this.workerChoiceStrategiesContext?.getTaskStatisticsRequirements().elu
1543 .aggregate === true
1544 ) {
1545 workerNode.usage.elu.active.aggregate = min(
1546 ...this.workerNodes.map(
1547 workerNode =>
1548 workerNode.usage.elu.active.aggregate ?? Number.POSITIVE_INFINITY
1549 )
1550 )
1551 }
1552 }
1553
1554 /**
1555 * Creates a new, completely set up worker node.
1556 * @returns New, completely set up worker node key.
1557 */
1558 protected createAndSetupWorkerNode (): number {
1559 const workerNode = this.createWorkerNode()
1560 workerNode.registerWorkerEventHandler(
1561 'online',
1562 this.opts.onlineHandler ?? EMPTY_FUNCTION
1563 )
1564 workerNode.registerWorkerEventHandler(
1565 'message',
1566 this.opts.messageHandler ?? EMPTY_FUNCTION
1567 )
1568 workerNode.registerWorkerEventHandler(
1569 'error',
1570 this.opts.errorHandler ?? EMPTY_FUNCTION
1571 )
1572 workerNode.registerOnceWorkerEventHandler('error', (error: Error) => {
1573 workerNode.info.ready = false
1574 this.emitter?.emit(PoolEvents.error, error)
1575 if (
1576 this.started &&
1577 !this.destroying &&
1578 this.opts.restartWorkerOnError === true
1579 ) {
1580 if (workerNode.info.dynamic) {
1581 this.createAndSetupDynamicWorkerNode()
1582 } else if (!this.startingMinimumNumberOfWorkers) {
1583 this.startMinimumNumberOfWorkers(true)
1584 }
1585 }
1586 if (
1587 this.started &&
1588 !this.destroying &&
1589 this.opts.enableTasksQueue === true
1590 ) {
1591 this.redistributeQueuedTasks(this.workerNodes.indexOf(workerNode))
1592 }
1593 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
1594 workerNode?.terminate().catch((error: unknown) => {
1595 this.emitter?.emit(PoolEvents.error, error)
1596 })
1597 })
1598 workerNode.registerWorkerEventHandler(
1599 'exit',
1600 this.opts.exitHandler ?? EMPTY_FUNCTION
1601 )
1602 workerNode.registerOnceWorkerEventHandler('exit', () => {
1603 this.removeWorkerNode(workerNode)
1604 if (
1605 this.started &&
1606 !this.startingMinimumNumberOfWorkers &&
1607 !this.destroying
1608 ) {
1609 this.startMinimumNumberOfWorkers(true)
1610 }
1611 })
1612 const workerNodeKey = this.addWorkerNode(workerNode)
1613 this.afterWorkerNodeSetup(workerNodeKey)
1614 return workerNodeKey
1615 }
1616
1617 /**
1618 * Creates a new, completely set up dynamic worker node.
1619 * @returns New, completely set up dynamic worker node key.
1620 */
1621 protected createAndSetupDynamicWorkerNode (): number {
1622 const workerNodeKey = this.createAndSetupWorkerNode()
1623 this.registerWorkerMessageListener(workerNodeKey, message => {
1624 this.checkMessageWorkerId(message)
1625 const localWorkerNodeKey = this.getWorkerNodeKeyByWorkerId(
1626 message.workerId
1627 )
1628 const workerInfo = this.getWorkerInfo(localWorkerNodeKey)
1629 const workerUsage = this.workerNodes[localWorkerNodeKey]?.usage
1630 // Kill message received from worker
1631 if (
1632 isKillBehavior(KillBehaviors.HARD, message.kill) ||
1633 (isKillBehavior(KillBehaviors.SOFT, message.kill) &&
1634 ((this.opts.enableTasksQueue === false &&
1635 workerUsage.tasks.executing === 0) ||
1636 (this.opts.enableTasksQueue === true &&
1637 workerInfo != null &&
1638 !workerInfo.stealing &&
1639 workerUsage.tasks.executing === 0 &&
1640 this.tasksQueueSize(localWorkerNodeKey) === 0)))
1641 ) {
1642 // Flag the worker node as not ready immediately
1643 this.flagWorkerNodeAsNotReady(localWorkerNodeKey)
1644 this.destroyWorkerNode(localWorkerNodeKey).catch((error: unknown) => {
1645 this.emitter?.emit(PoolEvents.error, error)
1646 })
1647 }
1648 })
1649 this.sendToWorker(workerNodeKey, {
1650 checkActive: true,
1651 })
1652 if (this.taskFunctions.size > 0) {
1653 for (const [taskFunctionName, taskFunctionObject] of this.taskFunctions) {
1654 this.sendTaskFunctionOperationToWorker(workerNodeKey, {
1655 taskFunctionOperation: 'add',
1656 taskFunctionProperties: buildTaskFunctionProperties(
1657 taskFunctionName,
1658 taskFunctionObject
1659 ),
1660 taskFunction: taskFunctionObject.taskFunction.toString(),
1661 }).catch((error: unknown) => {
1662 this.emitter?.emit(PoolEvents.error, error)
1663 })
1664 }
1665 }
1666 const workerNode = this.workerNodes[workerNodeKey]
1667 workerNode.info.dynamic = true
1668 if (
1669 this.workerChoiceStrategiesContext?.getPolicy().dynamicWorkerReady ===
1670 true ||
1671 this.workerChoiceStrategiesContext?.getPolicy().dynamicWorkerUsage ===
1672 true
1673 ) {
1674 workerNode.info.ready = true
1675 }
1676 this.initWorkerNodeUsage(workerNode)
1677 this.checkAndEmitDynamicWorkerCreationEvents()
1678 return workerNodeKey
1679 }
1680
1681 /**
1682 * Registers a listener callback on the worker given its worker node key.
1683 * @param workerNodeKey - The worker node key.
1684 * @param listener - The message listener callback.
1685 */
1686 protected abstract registerWorkerMessageListener<
1687 Message extends Data | Response
1688 >(
1689 workerNodeKey: number,
1690 listener: (message: MessageValue<Message>) => void
1691 ): void
1692
1693 /**
1694 * Registers once a listener callback on the worker given its worker node key.
1695 * @param workerNodeKey - The worker node key.
1696 * @param listener - The message listener callback.
1697 */
1698 protected abstract registerOnceWorkerMessageListener<
1699 Message extends Data | Response
1700 >(
1701 workerNodeKey: number,
1702 listener: (message: MessageValue<Message>) => void
1703 ): void
1704
1705 /**
1706 * Deregisters a listener callback on the worker given its worker node key.
1707 * @param workerNodeKey - The worker node key.
1708 * @param listener - The message listener callback.
1709 */
1710 protected abstract deregisterWorkerMessageListener<
1711 Message extends Data | Response
1712 >(
1713 workerNodeKey: number,
1714 listener: (message: MessageValue<Message>) => void
1715 ): void
1716
1717 /**
1718 * Method hooked up after a worker node has been newly created.
1719 * Can be overridden.
1720 * @param workerNodeKey - The newly created worker node key.
1721 */
1722 protected afterWorkerNodeSetup (workerNodeKey: number): void {
1723 // Listen to worker messages.
1724 this.registerWorkerMessageListener(
1725 workerNodeKey,
1726 this.workerMessageListener
1727 )
1728 // Send the startup message to worker.
1729 this.sendStartupMessageToWorker(workerNodeKey)
1730 // Send the statistics message to worker.
1731 this.sendStatisticsMessageToWorker(workerNodeKey)
1732 if (this.opts.enableTasksQueue === true) {
1733 if (this.opts.tasksQueueOptions?.taskStealing === true) {
1734 this.workerNodes[workerNodeKey].on(
1735 'idle',
1736 this.handleWorkerNodeIdleEvent
1737 )
1738 }
1739 if (this.opts.tasksQueueOptions?.tasksStealingOnBackPressure === true) {
1740 this.workerNodes[workerNodeKey].on(
1741 'backPressure',
1742 this.handleWorkerNodeBackPressureEvent
1743 )
1744 }
1745 }
1746 }
1747
1748 /**
1749 * Sends the startup message to worker given its worker node key.
1750 * @param workerNodeKey - The worker node key.
1751 */
1752 protected abstract sendStartupMessageToWorker (workerNodeKey: number): void
1753
1754 /**
1755 * Sends the statistics message to worker given its worker node key.
1756 * @param workerNodeKey - The worker node key.
1757 */
1758 private sendStatisticsMessageToWorker (workerNodeKey: number): void {
1759 this.sendToWorker(workerNodeKey, {
1760 statistics: {
1761 runTime:
1762 this.workerChoiceStrategiesContext?.getTaskStatisticsRequirements()
1763 .runTime.aggregate ?? false,
1764 elu:
1765 this.workerChoiceStrategiesContext?.getTaskStatisticsRequirements()
1766 .elu.aggregate ?? false,
1767 },
1768 })
1769 }
1770
1771 private cannotStealTask (): boolean {
1772 return this.workerNodes.length <= 1 || this.info.queuedTasks === 0
1773 }
1774
1775 private handleTask (workerNodeKey: number, task: Task<Data>): void {
1776 if (this.shallExecuteTask(workerNodeKey)) {
1777 this.executeTask(workerNodeKey, task)
1778 } else {
1779 this.enqueueTask(workerNodeKey, task)
1780 }
1781 }
1782
1783 private redistributeQueuedTasks (sourceWorkerNodeKey: number): void {
1784 if (sourceWorkerNodeKey === -1 || this.cannotStealTask()) {
1785 return
1786 }
1787 while (this.tasksQueueSize(sourceWorkerNodeKey) > 0) {
1788 const destinationWorkerNodeKey = this.workerNodes.reduce(
1789 (minWorkerNodeKey, workerNode, workerNodeKey, workerNodes) => {
1790 return sourceWorkerNodeKey !== workerNodeKey &&
1791 workerNode.info.ready &&
1792 workerNode.usage.tasks.queued <
1793 workerNodes[minWorkerNodeKey].usage.tasks.queued
1794 ? workerNodeKey
1795 : minWorkerNodeKey
1796 },
1797 0
1798 )
1799 this.handleTask(
1800 destinationWorkerNodeKey,
1801 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1802 this.dequeueTask(sourceWorkerNodeKey)!
1803 )
1804 }
1805 }
1806
1807 private updateTaskStolenStatisticsWorkerUsage (
1808 workerNodeKey: number,
1809 taskName: string
1810 ): void {
1811 const workerNode = this.workerNodes[workerNodeKey]
1812 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
1813 if (workerNode?.usage != null) {
1814 ++workerNode.usage.tasks.stolen
1815 }
1816 if (
1817 this.shallUpdateTaskFunctionWorkerUsage(workerNodeKey) &&
1818 workerNode.getTaskFunctionWorkerUsage(taskName) != null
1819 ) {
1820 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1821 ++workerNode.getTaskFunctionWorkerUsage(taskName)!.tasks.stolen
1822 }
1823 }
1824
1825 private updateTaskSequentiallyStolenStatisticsWorkerUsage (
1826 workerNodeKey: number,
1827 taskName: string,
1828 previousTaskName?: string
1829 ): void {
1830 const workerNode = this.workerNodes[workerNodeKey]
1831 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
1832 if (workerNode?.usage != null) {
1833 ++workerNode.usage.tasks.sequentiallyStolen
1834 }
1835 if (
1836 this.shallUpdateTaskFunctionWorkerUsage(workerNodeKey) &&
1837 workerNode.getTaskFunctionWorkerUsage(taskName) != null
1838 ) {
1839 const taskFunctionWorkerUsage =
1840 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1841 workerNode.getTaskFunctionWorkerUsage(taskName)!
1842 if (
1843 taskFunctionWorkerUsage.tasks.sequentiallyStolen === 0 ||
1844 (previousTaskName != null &&
1845 previousTaskName === taskName &&
1846 taskFunctionWorkerUsage.tasks.sequentiallyStolen > 0)
1847 ) {
1848 ++taskFunctionWorkerUsage.tasks.sequentiallyStolen
1849 } else if (taskFunctionWorkerUsage.tasks.sequentiallyStolen > 0) {
1850 taskFunctionWorkerUsage.tasks.sequentiallyStolen = 0
1851 }
1852 }
1853 }
1854
1855 private resetTaskSequentiallyStolenStatisticsWorkerUsage (
1856 workerNodeKey: number,
1857 taskName: string
1858 ): void {
1859 const workerNode = this.workerNodes[workerNodeKey]
1860 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
1861 if (workerNode?.usage != null) {
1862 workerNode.usage.tasks.sequentiallyStolen = 0
1863 }
1864 if (
1865 this.shallUpdateTaskFunctionWorkerUsage(workerNodeKey) &&
1866 workerNode.getTaskFunctionWorkerUsage(taskName) != null
1867 ) {
1868 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1869 workerNode.getTaskFunctionWorkerUsage(
1870 taskName
1871 )!.tasks.sequentiallyStolen = 0
1872 }
1873 }
1874
1875 private readonly handleWorkerNodeIdleEvent = (
1876 eventDetail: WorkerNodeEventDetail,
1877 previousStolenTask?: Task<Data>
1878 ): void => {
1879 const { workerNodeKey } = eventDetail
1880 if (workerNodeKey == null) {
1881 throw new Error(
1882 "WorkerNode event detail 'workerNodeKey' property must be defined"
1883 )
1884 }
1885 const workerInfo = this.getWorkerInfo(workerNodeKey)
1886 if (workerInfo == null) {
1887 throw new Error(
1888 `Worker node with key '${workerNodeKey.toString()}' not found in pool`
1889 )
1890 }
1891 if (
1892 this.cannotStealTask() ||
1893 (this.info.stealingWorkerNodes ?? 0) >
1894 Math.floor(this.workerNodes.length / 2)
1895 ) {
1896 if (previousStolenTask != null) {
1897 workerInfo.stealing = false
1898 this.resetTaskSequentiallyStolenStatisticsWorkerUsage(
1899 workerNodeKey,
1900 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1901 previousStolenTask.name!
1902 )
1903 }
1904 return
1905 }
1906 const workerNodeTasksUsage = this.workerNodes[workerNodeKey].usage.tasks
1907 if (
1908 previousStolenTask != null &&
1909 (workerNodeTasksUsage.executing > 0 ||
1910 this.tasksQueueSize(workerNodeKey) > 0)
1911 ) {
1912 workerInfo.stealing = false
1913 this.resetTaskSequentiallyStolenStatisticsWorkerUsage(
1914 workerNodeKey,
1915 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1916 previousStolenTask.name!
1917 )
1918 return
1919 }
1920 workerInfo.stealing = true
1921 const stolenTask = this.workerNodeStealTask(workerNodeKey)
1922 if (stolenTask != null) {
1923 this.updateTaskSequentiallyStolenStatisticsWorkerUsage(
1924 workerNodeKey,
1925 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1926 stolenTask.name!,
1927 previousStolenTask?.name
1928 )
1929 }
1930 sleep(exponentialDelay(workerNodeTasksUsage.sequentiallyStolen))
1931 .then(() => {
1932 this.handleWorkerNodeIdleEvent(eventDetail, stolenTask)
1933 return undefined
1934 })
1935 .catch((error: unknown) => {
1936 this.emitter?.emit(PoolEvents.error, error)
1937 })
1938 }
1939
1940 private readonly workerNodeStealTask = (
1941 workerNodeKey: number
1942 ): Task<Data> | undefined => {
1943 const workerNodes = this.workerNodes
1944 .slice()
1945 .sort(
1946 (workerNodeA, workerNodeB) =>
1947 workerNodeB.usage.tasks.queued - workerNodeA.usage.tasks.queued
1948 )
1949 const sourceWorkerNode = workerNodes.find(
1950 (sourceWorkerNode, sourceWorkerNodeKey) =>
1951 sourceWorkerNode.info.ready &&
1952 !sourceWorkerNode.info.stealing &&
1953 sourceWorkerNodeKey !== workerNodeKey &&
1954 sourceWorkerNode.usage.tasks.queued > 0
1955 )
1956 if (sourceWorkerNode != null) {
1957 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1958 const task = sourceWorkerNode.dequeueLastPrioritizedTask()!
1959 this.handleTask(workerNodeKey, task)
1960 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1961 this.updateTaskStolenStatisticsWorkerUsage(workerNodeKey, task.name!)
1962 return task
1963 }
1964 }
1965
1966 private readonly handleWorkerNodeBackPressureEvent = (
1967 eventDetail: WorkerNodeEventDetail
1968 ): void => {
1969 if (
1970 this.cannotStealTask() ||
1971 this.hasBackPressure() ||
1972 (this.info.stealingWorkerNodes ?? 0) >
1973 Math.floor(this.workerNodes.length / 2)
1974 ) {
1975 return
1976 }
1977 const sizeOffset = 1
1978 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1979 if (this.opts.tasksQueueOptions!.size! <= sizeOffset) {
1980 return
1981 }
1982 const { workerId } = eventDetail
1983 const sourceWorkerNode =
1984 this.workerNodes[this.getWorkerNodeKeyByWorkerId(workerId)]
1985 const workerNodes = this.workerNodes
1986 .slice()
1987 .sort(
1988 (workerNodeA, workerNodeB) =>
1989 workerNodeA.usage.tasks.queued - workerNodeB.usage.tasks.queued
1990 )
1991 for (const [workerNodeKey, workerNode] of workerNodes.entries()) {
1992 if (
1993 sourceWorkerNode.usage.tasks.queued > 0 &&
1994 workerNode.info.ready &&
1995 !workerNode.info.stealing &&
1996 workerNode.info.id !== workerId &&
1997 workerNode.usage.tasks.queued <
1998 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
1999 this.opts.tasksQueueOptions!.size! - sizeOffset
2000 ) {
2001 const workerInfo = this.getWorkerInfo(workerNodeKey)
2002 if (workerInfo == null) {
2003 throw new Error(
2004 `Worker node with key '${workerNodeKey.toString()}' not found in pool`
2005 )
2006 }
2007 workerInfo.stealing = true
2008 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
2009 const task = sourceWorkerNode.dequeueLastPrioritizedTask()!
2010 this.handleTask(workerNodeKey, task)
2011 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
2012 this.updateTaskStolenStatisticsWorkerUsage(workerNodeKey, task.name!)
2013 workerInfo.stealing = false
2014 }
2015 }
2016 }
2017
2018 private setTasksQueuePriority (workerNodeKey: number): void {
2019 this.workerNodes[workerNodeKey].setTasksQueuePriority(
2020 this.getTasksQueuePriority()
2021 )
2022 }
2023
2024 /**
2025 * This method is the message listener registered on each worker.
2026 * @param message - The message received from the worker.
2027 */
2028 protected readonly workerMessageListener = (
2029 message: MessageValue<Response>
2030 ): void => {
2031 this.checkMessageWorkerId(message)
2032 const { workerId, ready, taskId, taskFunctionsProperties } = message
2033 if (ready != null && taskFunctionsProperties != null) {
2034 // Worker ready response received from worker
2035 this.handleWorkerReadyResponse(message)
2036 } else if (taskFunctionsProperties != null) {
2037 // Task function properties message received from worker
2038 const workerNodeKey = this.getWorkerNodeKeyByWorkerId(workerId)
2039 const workerInfo = this.getWorkerInfo(workerNodeKey)
2040 if (workerInfo != null) {
2041 workerInfo.taskFunctionsProperties = taskFunctionsProperties
2042 this.sendStatisticsMessageToWorker(workerNodeKey)
2043 this.setTasksQueuePriority(workerNodeKey)
2044 }
2045 } else if (taskId != null) {
2046 // Task execution response received from worker
2047 this.handleTaskExecutionResponse(message)
2048 }
2049 }
2050
2051 private checkAndEmitReadyEvent (): void {
2052 if (!this.readyEventEmitted && this.ready) {
2053 this.emitter?.emit(PoolEvents.ready, this.info)
2054 this.readyEventEmitted = true
2055 }
2056 }
2057
2058 private handleWorkerReadyResponse (message: MessageValue<Response>): void {
2059 const { workerId, ready, taskFunctionsProperties } = message
2060 if (ready == null || !ready) {
2061 // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
2062 throw new Error(`Worker ${workerId?.toString()} failed to initialize`)
2063 }
2064 const workerNodeKey = this.getWorkerNodeKeyByWorkerId(workerId)
2065 const workerNode = this.workerNodes[workerNodeKey]
2066 workerNode.info.ready = ready
2067 workerNode.info.taskFunctionsProperties = taskFunctionsProperties
2068 this.sendStatisticsMessageToWorker(workerNodeKey)
2069 this.setTasksQueuePriority(workerNodeKey)
2070 this.checkAndEmitReadyEvent()
2071 }
2072
2073 private handleTaskExecutionResponse (message: MessageValue<Response>): void {
2074 const { workerId, taskId, workerError, data } = message
2075 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
2076 const promiseResponse = this.promiseResponseMap.get(taskId!)
2077 if (promiseResponse != null) {
2078 const { resolve, reject, workerNodeKey, asyncResource } = promiseResponse
2079 const workerNode = this.workerNodes[workerNodeKey]
2080 if (workerError != null) {
2081 this.emitter?.emit(PoolEvents.taskError, workerError)
2082 asyncResource != null
2083 ? asyncResource.runInAsyncScope(
2084 reject,
2085 this.emitter,
2086 workerError.message
2087 )
2088 : reject(workerError.message)
2089 } else {
2090 asyncResource != null
2091 ? asyncResource.runInAsyncScope(resolve, this.emitter, data)
2092 : resolve(data as Response)
2093 }
2094 asyncResource?.emitDestroy()
2095 this.afterTaskExecutionHook(workerNodeKey, message)
2096 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
2097 this.promiseResponseMap.delete(taskId!)
2098 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
2099 workerNode?.emit('taskFinished', taskId)
2100 if (
2101 this.opts.enableTasksQueue === true &&
2102 !this.destroying &&
2103 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
2104 workerNode != null
2105 ) {
2106 const workerNodeTasksUsage = workerNode.usage.tasks
2107 if (
2108 this.tasksQueueSize(workerNodeKey) > 0 &&
2109 workerNodeTasksUsage.executing <
2110 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
2111 this.opts.tasksQueueOptions!.concurrency!
2112 ) {
2113 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
2114 this.executeTask(workerNodeKey, this.dequeueTask(workerNodeKey)!)
2115 }
2116 if (
2117 workerNodeTasksUsage.executing === 0 &&
2118 this.tasksQueueSize(workerNodeKey) === 0 &&
2119 workerNodeTasksUsage.sequentiallyStolen === 0
2120 ) {
2121 workerNode.emit('idle', {
2122 workerId,
2123 workerNodeKey,
2124 })
2125 }
2126 }
2127 }
2128 }
2129
2130 private checkAndEmitTaskExecutionEvents (): void {
2131 if (this.busy) {
2132 this.emitter?.emit(PoolEvents.busy, this.info)
2133 }
2134 }
2135
2136 private checkAndEmitTaskQueuingEvents (): void {
2137 if (this.hasBackPressure()) {
2138 this.emitter?.emit(PoolEvents.backPressure, this.info)
2139 }
2140 }
2141
2142 /**
2143 * Emits dynamic worker creation events.
2144 */
2145 protected abstract checkAndEmitDynamicWorkerCreationEvents (): void
2146
2147 /**
2148 * Gets the worker information given its worker node key.
2149 * @param workerNodeKey - The worker node key.
2150 * @returns The worker information.
2151 */
2152 protected getWorkerInfo (workerNodeKey: number): WorkerInfo | undefined {
2153 return this.workerNodes[workerNodeKey]?.info
2154 }
2155
2156 private getTasksQueuePriority (): boolean {
2157 return this.listTaskFunctionsProperties().some(
2158 taskFunctionProperties => taskFunctionProperties.priority != null
2159 )
2160 }
2161
2162 /**
2163 * Creates a worker node.
2164 * @returns The created worker node.
2165 */
2166 private createWorkerNode (): IWorkerNode<Worker, Data> {
2167 const workerNode = new WorkerNode<Worker, Data>(
2168 this.worker,
2169 this.filePath,
2170 {
2171 env: this.opts.env,
2172 workerOptions: this.opts.workerOptions,
2173 tasksQueueBackPressureSize:
2174 this.opts.tasksQueueOptions?.size ??
2175 getDefaultTasksQueueOptions(
2176 this.maximumNumberOfWorkers ?? this.minimumNumberOfWorkers
2177 ).size,
2178 tasksQueueBucketSize: defaultBucketSize,
2179 tasksQueuePriority: this.getTasksQueuePriority(),
2180 }
2181 )
2182 // Flag the worker node as ready at pool startup.
2183 if (this.starting) {
2184 workerNode.info.ready = true
2185 }
2186 return workerNode
2187 }
2188
2189 /**
2190 * Adds the given worker node in the pool worker nodes.
2191 * @param workerNode - The worker node.
2192 * @returns The added worker node key.
2193 * @throws {@link https://nodejs.org/api/errors.html#class-error} If the added worker node is not found.
2194 */
2195 private addWorkerNode (workerNode: IWorkerNode<Worker, Data>): number {
2196 this.workerNodes.push(workerNode)
2197 const workerNodeKey = this.workerNodes.indexOf(workerNode)
2198 if (workerNodeKey === -1) {
2199 throw new Error('Worker added not found in worker nodes')
2200 }
2201 return workerNodeKey
2202 }
2203
2204 private checkAndEmitEmptyEvent (): void {
2205 if (this.empty) {
2206 this.emitter?.emit(PoolEvents.empty, this.info)
2207 this.readyEventEmitted = false
2208 }
2209 }
2210
2211 /**
2212 * Removes the worker node from the pool worker nodes.
2213 * @param workerNode - The worker node.
2214 */
2215 private removeWorkerNode (workerNode: IWorkerNode<Worker, Data>): void {
2216 const workerNodeKey = this.workerNodes.indexOf(workerNode)
2217 if (workerNodeKey !== -1) {
2218 this.workerNodes.splice(workerNodeKey, 1)
2219 this.workerChoiceStrategiesContext?.remove(workerNodeKey)
2220 }
2221 this.checkAndEmitEmptyEvent()
2222 }
2223
2224 protected flagWorkerNodeAsNotReady (workerNodeKey: number): void {
2225 const workerInfo = this.getWorkerInfo(workerNodeKey)
2226 if (workerInfo != null) {
2227 workerInfo.ready = false
2228 }
2229 }
2230
2231 private hasBackPressure (): boolean {
2232 return (
2233 this.opts.enableTasksQueue === true &&
2234 this.workerNodes.findIndex(
2235 workerNode => !workerNode.hasBackPressure()
2236 ) === -1
2237 )
2238 }
2239
2240 /**
2241 * Executes the given task on the worker given its worker node key.
2242 * @param workerNodeKey - The worker node key.
2243 * @param task - The task to execute.
2244 */
2245 private executeTask (workerNodeKey: number, task: Task<Data>): void {
2246 this.beforeTaskExecutionHook(workerNodeKey, task)
2247 this.sendToWorker(workerNodeKey, task, task.transferList)
2248 this.checkAndEmitTaskExecutionEvents()
2249 }
2250
2251 private enqueueTask (workerNodeKey: number, task: Task<Data>): number {
2252 const tasksQueueSize = this.workerNodes[workerNodeKey].enqueueTask(task)
2253 this.checkAndEmitTaskQueuingEvents()
2254 return tasksQueueSize
2255 }
2256
2257 private dequeueTask (workerNodeKey: number): Task<Data> | undefined {
2258 return this.workerNodes[workerNodeKey].dequeueTask()
2259 }
2260
2261 private tasksQueueSize (workerNodeKey: number): number {
2262 return this.workerNodes[workerNodeKey].tasksQueueSize()
2263 }
2264
2265 protected flushTasksQueue (workerNodeKey: number): number {
2266 let flushedTasks = 0
2267 while (this.tasksQueueSize(workerNodeKey) > 0) {
2268 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
2269 this.executeTask(workerNodeKey, this.dequeueTask(workerNodeKey)!)
2270 ++flushedTasks
2271 }
2272 this.workerNodes[workerNodeKey].clearTasksQueue()
2273 return flushedTasks
2274 }
2275
2276 private flushTasksQueues (): void {
2277 for (const workerNodeKey of this.workerNodes.keys()) {
2278 this.flushTasksQueue(workerNodeKey)
2279 }
2280 }
2281 }