poolifier 2.6.37 → 2.6.39

package/lib/pools/abstract-pool.d.ts

@@ -1,316 +0,0 @@
-/// <reference types="node" />
-import { type TransferListItem } from 'node:worker_threads';
-import type { MessageValue, PromiseResponseWrapper, Task } from '../utility-types';
-import { type IPool, PoolEmitter, type PoolInfo, type PoolOptions, type PoolType, type TasksQueueOptions } from './pool';
-import type { IWorker, IWorkerNode, WorkerInfo, WorkerType } from './worker';
-import { type WorkerChoiceStrategy, type WorkerChoiceStrategyOptions } from './selection-strategies/selection-strategies-types';
-import { WorkerChoiceStrategyContext } from './selection-strategies/worker-choice-strategy-context';
-/**
- * Base class that implements some shared logic for all poolifier pools.
- *
- * @typeParam Worker - Type of worker which manages this pool.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
- */
-export declare abstract class AbstractPool<Worker extends IWorker, Data = unknown, Response = unknown> implements IPool<Worker, Data, Response> {
-    protected readonly numberOfWorkers: number;
-    protected readonly filePath: string;
-    protected readonly opts: PoolOptions<Worker>;
-    /** @inheritDoc */
-    readonly workerNodes: Array<IWorkerNode<Worker, Data>>;
-    /** @inheritDoc */
-    readonly emitter?: PoolEmitter;
-    /**
-     * The task execution response promise map.
-     *
-     * - `key`: The message id of each submitted task.
-     * - `value`: An object that contains the worker, the execution response promise resolve and reject callbacks.
-     *
-     * When we receive a message from the worker, we get a map entry with the promise resolve/reject bound to the message id.
-     */
-    protected promiseResponseMap: Map<string, PromiseResponseWrapper<Response>>;
-    /**
-     * Worker choice strategy context referencing a worker choice algorithm implementation.
-     */
-    protected workerChoiceStrategyContext: WorkerChoiceStrategyContext<Worker, Data, Response>;
-    /**
-     * Dynamic pool maximum size property placeholder.
-     */
-    protected readonly max?: number;
-    /**
-     * Whether the pool is starting or not.
-     */
-    private readonly starting;
-    /**
-     * Whether the pool is started or not.
-     */
-    private started;
-    /**
-     * The start timestamp of the pool.
-     */
-    private readonly startTimestamp;
-    /**
-     * Constructs a new poolifier pool.
-     *
-     * @param numberOfWorkers - Number of workers that this pool should manage.
-     * @param filePath - Path to the worker file.
-     * @param opts - Options for the pool.
-     */
-    constructor(numberOfWorkers: number, filePath: string, opts: PoolOptions<Worker>);
-    private checkFilePath;
-    private checkNumberOfWorkers;
-    protected checkDynamicPoolSize(min: number, max: number): void;
-    private checkPoolOptions;
-    private checkValidWorkerChoiceStrategy;
-    private checkValidWorkerChoiceStrategyOptions;
-    private checkValidTasksQueueOptions;
-    private startPool;
-    /** @inheritDoc */
-    get info(): PoolInfo;
-    /**
-     * The pool readiness boolean status.
-     */
-    private get ready();
-    /**
-     * The approximate pool utilization.
-     *
-     * @returns The pool utilization.
-     */
-    private get utilization();
-    /**
-     * The pool type.
-     *
-     * If it is `'dynamic'`, it provides the `max` property.
-     */
-    protected abstract get type(): PoolType;
-    /**
-     * The worker type.
-     */
-    protected abstract get worker(): WorkerType;
-    /**
-     * The pool minimum size.
-     */
-    protected get minSize(): number;
-    /**
-     * The pool maximum size.
-     */
-    protected get maxSize(): number;
-    /**
-     * Checks if the worker id sent in the received message from a worker is valid.
-     *
-     * @param message - The received message.
-     * @throws {@link https://nodejs.org/api/errors.html#class-error} If the worker id is invalid.
-     */
-    private checkMessageWorkerId;
-    /**
-     * Gets the given worker its worker node key.
-     *
-     * @param worker - The worker.
-     * @returns The worker node key if found in the pool worker nodes, `-1` otherwise.
-     */
-    private getWorkerNodeKeyByWorker;
-    /**
-     * Gets the worker node key given its worker id.
-     *
-     * @param workerId - The worker id.
-     * @returns The worker node key if the worker id is found in the pool worker nodes, `-1` otherwise.
-     */
-    private getWorkerNodeKeyByWorkerId;
-    /** @inheritDoc */
-    setWorkerChoiceStrategy(workerChoiceStrategy: WorkerChoiceStrategy, workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions): void;
-    /** @inheritDoc */
-    setWorkerChoiceStrategyOptions(workerChoiceStrategyOptions: WorkerChoiceStrategyOptions): void;
-    /** @inheritDoc */
-    enableTasksQueue(enable: boolean, tasksQueueOptions?: TasksQueueOptions): void;
-    /** @inheritDoc */
-    setTasksQueueOptions(tasksQueueOptions: TasksQueueOptions): void;
-    private setTasksQueueMaxSize;
-    private buildTasksQueueOptions;
-    /**
-     * Whether the pool is full or not.
-     *
-     * The pool filling boolean status.
-     */
-    protected get full(): boolean;
-    /**
-     * Whether the pool is busy or not.
-     *
-     * The pool busyness boolean status.
-     */
-    protected abstract get busy(): boolean;
-    /**
-     * Whether worker nodes are executing concurrently their tasks quota or not.
-     *
-     * @returns Worker nodes busyness boolean status.
-     */
-    protected internalBusy(): boolean;
-    /** @inheritDoc */
-    listTaskFunctions(): string[];
-    private shallExecuteTask;
-    /** @inheritDoc */
-    execute(data?: Data, name?: string, transferList?: TransferListItem[]): Promise<Response>;
-    /** @inheritDoc */
-    destroy(): Promise<void>;
-    protected sendKillMessageToWorker(workerNodeKey: number, workerId: number): Promise<void>;
-    /**
-     * Terminates the worker node given its worker node key.
-     *
-     * @param workerNodeKey - The worker node key.
-     */
-    protected abstract destroyWorkerNode(workerNodeKey: number): Promise<void>;
-    /**
-     * Setup hook to execute code before worker nodes are created in the abstract constructor.
-     * Can be overridden.
-     *
-     * @virtual
-     */
-    protected setupHook(): void;
-    /**
-     * Should return whether the worker is the main worker or not.
-     */
-    protected abstract isMain(): boolean;
-    /**
-     * Hook executed before the worker task execution.
-     * Can be overridden.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @param task - The task to execute.
-     */
-    protected beforeTaskExecutionHook(workerNodeKey: number, task: Task<Data>): void;
-    /**
-     * Hook executed after the worker task execution.
-     * Can be overridden.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @param message - The received message.
-     */
-    protected afterTaskExecutionHook(workerNodeKey: number, message: MessageValue<Response>): void;
-    /**
-     * Whether the worker node shall update its task function worker usage or not.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @returns `true` if the worker node shall update its task function worker usage, `false` otherwise.
-     */
-    private shallUpdateTaskFunctionWorkerUsage;
-    private updateTaskStatisticsWorkerUsage;
-    private updateRunTimeWorkerUsage;
-    private updateWaitTimeWorkerUsage;
-    private updateEluWorkerUsage;
-    /**
-     * Chooses a worker node for the next task.
-     *
-     * The default worker choice strategy uses a round robin algorithm to distribute the tasks.
-     *
-     * @returns The chosen worker node key
-     */
-    private chooseWorkerNode;
-    /**
-     * Conditions for dynamic worker creation.
-     *
-     * @returns Whether to create a dynamic worker or not.
-     */
-    private shallCreateDynamicWorker;
-    /**
-     * Sends a message to worker given its worker node key.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @param message - The message.
-     * @param transferList - The optional array of transferable objects.
-     */
-    protected abstract sendToWorker(workerNodeKey: number, message: MessageValue<Data>, transferList?: TransferListItem[]): void;
-    /**
-     * Creates a new worker.
-     *
-     * @returns Newly created worker.
-     */
-    protected abstract createWorker(): Worker;
-    /**
-     * Creates a new, completely set up worker node.
-     *
-     * @returns New, completely set up worker node key.
-     */
-    protected createAndSetupWorkerNode(): number;
-    /**
-     * Creates a new, completely set up dynamic worker node.
-     *
-     * @returns New, completely set up dynamic worker node key.
-     */
-    protected createAndSetupDynamicWorkerNode(): number;
-    /**
-     * Registers a listener callback on the worker given its worker node key.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @param listener - The message listener callback.
-     */
-    protected abstract registerWorkerMessageListener<Message extends Data | Response>(workerNodeKey: number, listener: (message: MessageValue<Message>) => void): void;
-    /**
-     * Method hooked up after a worker node has been newly created.
-     * Can be overridden.
-     *
-     * @param workerNodeKey - The newly created worker node key.
-     */
-    protected afterWorkerNodeSetup(workerNodeKey: number): void;
-    /**
-     * Sends the startup message to worker given its worker node key.
-     *
-     * @param workerNodeKey - The worker node key.
-     */
-    protected abstract sendStartupMessageToWorker(workerNodeKey: number): void;
-    /**
-     * Sends the statistics message to worker given its worker node key.
-     *
-     * @param workerNodeKey - The worker node key.
-     */
-    private sendStatisticsMessageToWorker;
-    private redistributeQueuedTasks;
-    private updateTaskStolenStatisticsWorkerUsage;
-    private taskStealingOnEmptyQueue;
-    private tasksStealingOnBackPressure;
-    /**
-     * This method is the listener registered for each worker message.
-     *
-     * @returns The listener function to execute when a message is received from a worker.
-     */
-    protected workerListener(): (message: MessageValue<Response>) => void;
-    private handleWorkerReadyResponse;
-    private handleTaskExecutionResponse;
-    private checkAndEmitTaskExecutionEvents;
-    private checkAndEmitTaskQueuingEvents;
-    private checkAndEmitDynamicWorkerCreationEvents;
-    /**
-     * Gets the worker information given its worker node key.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @returns The worker information.
-     */
-    protected getWorkerInfo(workerNodeKey: number): WorkerInfo | undefined;
-    /**
-     * Adds the given worker in the pool worker nodes.
-     *
-     * @param worker - The worker.
-     * @returns The added worker node key.
-     * @throws {@link https://nodejs.org/api/errors.html#class-error} If the added worker node is not found.
-     */
-    private addWorkerNode;
-    /**
-     * Removes the given worker from the pool worker nodes.
-     *
-     * @param worker - The worker.
-     */
-    private removeWorkerNode;
-    /** @inheritDoc */
-    hasWorkerNodeBackPressure(workerNodeKey: number): boolean;
-    private hasBackPressure;
-    /**
-     * Executes the given task on the worker given its worker node key.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @param task - The task to execute.
-     */
-    private executeTask;
-    private enqueueTask;
-    private dequeueTask;
-    private tasksQueueSize;
-    protected flushTasksQueue(workerNodeKey: number): void;
-    private flushTasksQueues;
-}

package/lib/pools/cluster/dynamic.d.ts

@@ -1,29 +0,0 @@
-import { type PoolType } from '../pool';
-import { type ClusterPoolOptions, FixedClusterPool } from './fixed';
-/**
- * A cluster pool with a dynamic number of workers, but a guaranteed minimum number of workers.
- *
- * This cluster pool creates new workers when the others are busy, up to the maximum number of workers.
- * When the maximum number of workers is reached and workers are busy, an event is emitted. If you want to listen to this event, use the pool's `emitter`.
- *
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
- * @author [Christopher Quadflieg](https://github.com/Shinigami92)
- * @since 2.0.0
- */
-export declare class DynamicClusterPool<Data = unknown, Response = unknown> extends FixedClusterPool<Data, Response> {
-    protected readonly max: number;
-    /**
-     * Constructs a new poolifier dynamic cluster pool.
-     *
-     * @param min - Minimum number of workers which are always active.
-     * @param max - Maximum number of workers that can be created by this pool.
-     * @param filePath - Path to an implementation of a `ClusterWorker` file, which can be relative or absolute.
-     * @param opts - Options for this dynamic cluster pool.
-     */
-    constructor(min: number, max: number, filePath: string, opts?: ClusterPoolOptions);
-    /** @inheritDoc */
-    protected get type(): PoolType;
-    /** @inheritDoc */
-    protected get busy(): boolean;
-}

package/lib/pools/cluster/fixed.d.ts

@@ -1,62 +0,0 @@
-/// <reference types="node" />
-import { type ClusterSettings, type Worker } from 'node:cluster';
-import type { MessageValue } from '../../utility-types';
-import { AbstractPool } from '../abstract-pool';
-import { type PoolOptions, type PoolType } from '../pool';
-import { type WorkerType } from '../worker';
-/**
- * Options for a poolifier cluster pool.
- */
-export interface ClusterPoolOptions extends PoolOptions<Worker> {
-    /**
-     * Key/value pairs to add to worker process environment.
-     *
-     * @see https://nodejs.org/api/cluster.html#cluster_cluster_fork_env
-     */
-    env?: Record<string, unknown>;
-    /**
-     * Cluster settings.
-     *
-     * @see https://nodejs.org/api/cluster.html#cluster_cluster_settings
-     */
-    settings?: ClusterSettings;
-}
-/**
- * A cluster pool with a fixed number of workers.
- *
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
- * @author [Christopher Quadflieg](https://github.com/Shinigami92)
- * @since 2.0.0
- */
-export declare class FixedClusterPool<Data = unknown, Response = unknown> extends AbstractPool<Worker, Data, Response> {
-    protected readonly opts: ClusterPoolOptions;
-    /**
-     * Constructs a new poolifier fixed cluster pool.
-     *
-     * @param numberOfWorkers - Number of workers for this pool.
-     * @param filePath - Path to an implementation of a `ClusterWorker` file, which can be relative or absolute.
-     * @param opts - Options for this fixed cluster pool.
-     */
-    constructor(numberOfWorkers: number, filePath: string, opts?: ClusterPoolOptions);
-    /** @inheritDoc */
-    protected setupHook(): void;
-    /** @inheritDoc */
-    protected isMain(): boolean;
-    /** @inheritDoc */
-    protected destroyWorkerNode(workerNodeKey: number): Promise<void>;
-    /** @inheritDoc */
-    protected sendToWorker(workerNodeKey: number, message: MessageValue<Data>): void;
-    /** @inheritDoc */
-    protected sendStartupMessageToWorker(workerNodeKey: number): void;
-    /** @inheritDoc */
-    protected registerWorkerMessageListener<Message extends Data | Response>(workerNodeKey: number, listener: (message: MessageValue<Message>) => void): void;
-    /** @inheritDoc */
-    protected createWorker(): Worker;
-    /** @inheritDoc */
-    protected get type(): PoolType;
-    /** @inheritDoc */
-    protected get worker(): WorkerType;
-    /** @inheritDoc */
-    protected get busy(): boolean;
-}

package/lib/pools/pool.d.ts

@@ -1,243 +0,0 @@
-/// <reference types="node" />
-/// <reference types="node" />
-import { EventEmitter } from 'node:events';
-import { type TransferListItem } from 'node:worker_threads';
-import type { ErrorHandler, ExitHandler, IWorker, IWorkerNode, MessageHandler, OnlineHandler, WorkerType } from './worker';
-import type { WorkerChoiceStrategy, WorkerChoiceStrategyOptions } from './selection-strategies/selection-strategies-types';
-/**
- * Enumeration of pool types.
- */
-export declare const PoolTypes: Readonly<{
-    /**
-     * Fixed pool type.
-     */
-    readonly fixed: "fixed";
-    /**
-     * Dynamic pool type.
-     */
-    readonly dynamic: "dynamic";
-}>;
-/**
- * Pool type.
- */
-export type PoolType = keyof typeof PoolTypes;
-/**
- * Pool events emitter.
- */
-export declare class PoolEmitter extends EventEmitter {
-}
-/**
- * Enumeration of pool events.
- */
-export declare const PoolEvents: Readonly<{
-    readonly ready: "ready";
-    readonly busy: "busy";
-    readonly full: "full";
-    readonly destroy: "destroy";
-    readonly error: "error";
-    readonly taskError: "taskError";
-    readonly backPressure: "backPressure";
-}>;
-/**
- * Pool event.
- */
-export type PoolEvent = keyof typeof PoolEvents;
-/**
- * Pool information.
- */
-export interface PoolInfo {
-    readonly version: string;
-    readonly type: PoolType;
-    readonly worker: WorkerType;
-    readonly ready: boolean;
-    readonly strategy: WorkerChoiceStrategy;
-    readonly minSize: number;
-    readonly maxSize: number;
-    /** Pool utilization. */
-    readonly utilization?: number;
-    /** Pool total worker nodes. */
-    readonly workerNodes: number;
-    /** Pool idle worker nodes. */
-    readonly idleWorkerNodes: number;
-    /** Pool busy worker nodes. */
-    readonly busyWorkerNodes: number;
-    readonly executedTasks: number;
-    readonly executingTasks: number;
-    readonly queuedTasks?: number;
-    readonly maxQueuedTasks?: number;
-    readonly backPressure?: boolean;
-    readonly stolenTasks?: number;
-    readonly failedTasks: number;
-    readonly runTime?: {
-        readonly minimum: number;
-        readonly maximum: number;
-        readonly average?: number;
-        readonly median?: number;
-    };
-    readonly waitTime?: {
-        readonly minimum: number;
-        readonly maximum: number;
-        readonly average?: number;
-        readonly median?: number;
-    };
-}
-/**
- * Worker node tasks queue options.
- */
-export interface TasksQueueOptions {
-    /**
-     * Maximum tasks queue size per worker node flagging it as back pressured.
-     *
-     * @defaultValue (pool maximum size)^2
-     */
-    readonly size?: number;
-    /**
-     * @deprecated Use `size` instead.
-     */
-    readonly queueMaxSize?: number;
-    /**
-     * Maximum number of tasks that can be executed concurrently on a worker node.
-     *
-     * @defaultValue 1
-     */
-    readonly concurrency?: number;
-}
-/**
- * Options for a poolifier pool.
- *
- * @typeParam Worker - Type of worker.
- */
-export interface PoolOptions<Worker extends IWorker> {
-    /**
-     * A function that will listen for online event on each worker.
-     */
-    onlineHandler?: OnlineHandler<Worker>;
-    /**
-     * A function that will listen for message event on each worker.
-     */
-    messageHandler?: MessageHandler<Worker>;
-    /**
-     * A function that will listen for error event on each worker.
-     */
-    errorHandler?: ErrorHandler<Worker>;
-    /**
-     * A function that will listen for exit event on each worker.
-     */
-    exitHandler?: ExitHandler<Worker>;
-    /**
-     * The worker choice strategy to use in this pool.
-     *
-     * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
-     */
-    workerChoiceStrategy?: WorkerChoiceStrategy;
-    /**
-     * The worker choice strategy options.
-     */
-    workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions;
-    /**
-     * Restart worker on error.
-     */
-    restartWorkerOnError?: boolean;
-    /**
-     * Pool events emission.
-     *
-     * @defaultValue true
-     */
-    enableEvents?: boolean;
-    /**
-     * Pool worker node tasks queue.
-     *
-     * @defaultValue false
-     */
-    enableTasksQueue?: boolean;
-    /**
-     * Pool worker node tasks queue options.
-     */
-    tasksQueueOptions?: TasksQueueOptions;
-}
-/**
- * Contract definition for a poolifier pool.
- *
- * @typeParam Worker - Type of worker which manages this pool.
- * @typeParam Data - Type of data sent to the worker. This can only be structured-cloneable data.
- * @typeParam Response - Type of execution response. This can only be structured-cloneable data.
- */
-export interface IPool<Worker extends IWorker, Data = unknown, Response = unknown> {
-    /**
-     * Pool information.
-     */
-    readonly info: PoolInfo;
-    /**
-     * Pool worker nodes.
-     *
-     * @internal
-     */
-    readonly workerNodes: Array<IWorkerNode<Worker, Data>>;
-    /**
-     * Whether the worker node has back pressure (i.e. its tasks queue is full).
-     *
-     * @param workerNodeKey - The worker node key.
-     * @returns `true` if the worker node has back pressure, `false` otherwise.
-     * @internal
-     */
-    readonly hasWorkerNodeBackPressure: (workerNodeKey: number) => boolean;
-    /**
-     * Emitter on which events can be listened to.
-     *
-     * Events that can currently be listened to:
-     *
-     * - `'ready'`: Emitted when the number of workers created in the pool has reached the minimum size expected and are ready.
-     * - `'busy'`: Emitted when the number of workers created in the pool has reached the maximum size expected and are executing concurrently their tasks quota.
-     * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected.
-     * - `'destroy'`: Emitted when the pool is destroyed.
-     * - `'error'`: Emitted when an uncaught error occurs.
-     * - `'taskError'`: Emitted when an error occurs while executing a task.
-     * - `'backPressure'`: Emitted when all worker nodes have back pressure (i.e. their tasks queue is full: queue size \>= maximum queue size).
-     */
-    readonly emitter?: PoolEmitter;
-    /**
-     * Executes the specified function in the worker constructor with the task data input parameter.
-     *
-     * @param data - The optional task input data for the specified task function. This can only be structured-cloneable data.
-     * @param name - The optional name of the task function to execute. If not specified, the default task function will be executed.
-     * @param transferList - An optional array of transferable objects to transfer ownership of. Ownership of the transferred objects is given to the pool's worker_threads worker and they should not be used in the main thread afterwards.
-     * @returns Promise that will be fulfilled when the task is completed.
-     */
-    readonly execute: (data?: Data, name?: string, transferList?: TransferListItem[]) => Promise<Response>;
-    /**
-     * Terminates all workers in this pool.
-     */
-    readonly destroy: () => Promise<void>;
-    /**
-     * Lists the names of task function available in this pool.
-     *
-     * @returns The names of task function available in this pool.
-     */
-    readonly listTaskFunctions: () => string[];
-    /**
-     * Sets the worker choice strategy in this pool.
-     *
-     * @param workerChoiceStrategy - The worker choice strategy.
-     * @param workerChoiceStrategyOptions - The worker choice strategy options.
-     */
-    readonly setWorkerChoiceStrategy: (workerChoiceStrategy: WorkerChoiceStrategy, workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions) => void;
-    /**
-     * Sets the worker choice strategy options in this pool.
-     *
-     * @param workerChoiceStrategyOptions - The worker choice strategy options.
-     */
-    readonly setWorkerChoiceStrategyOptions: (workerChoiceStrategyOptions: WorkerChoiceStrategyOptions) => void;
-    /**
-     * Enables/disables the worker node tasks queue in this pool.
-     *
-     * @param enable - Whether to enable or disable the worker node tasks queue.
-     * @param tasksQueueOptions - The worker node tasks queue options.
-     */
-    readonly enableTasksQueue: (enable: boolean, tasksQueueOptions?: TasksQueueOptions) => void;
-    /**
-     * Sets the worker node tasks queue options in this pool.
-     *
-     * @param tasksQueueOptions - The worker node tasks queue options.
-     */
-    readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void;
-}