poolifier 2.6.36 → 2.6.38

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 at least one task.
-     * - `'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;
-}

package/lib/pools/selection-strategies/abstract-worker-choice-strategy.d.ts

@@ -1,104 +0,0 @@
-import type { IPool } from '../pool';
-import type { IWorker } from '../worker';
-import type { IWorkerChoiceStrategy, StrategyPolicy, TaskStatisticsRequirements, WorkerChoiceStrategyOptions } from './selection-strategies-types';
-/**
- * Worker choice strategy abstract base class.
- *
- * @typeParam Worker - Type of worker which manages the strategy.
- * @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 AbstractWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> implements IWorkerChoiceStrategy {
-    protected readonly pool: IPool<Worker, Data, Response>;
-    protected opts: WorkerChoiceStrategyOptions;
-    /**
-     * The next worker node key.
-     */
-    protected nextWorkerNodeKey: number | undefined;
-    /**
-     * The previous worker node key.
-     */
-    protected previousWorkerNodeKey: number;
-    /** @inheritDoc */
-    readonly strategyPolicy: StrategyPolicy;
-    /** @inheritDoc */
-    readonly taskStatisticsRequirements: TaskStatisticsRequirements;
-    /**
-     * Constructs a worker choice strategy bound to the pool.
-     *
-     * @param pool - The pool instance.
-     * @param opts - The worker choice strategy options.
-     */
-    constructor(pool: IPool<Worker, Data, Response>, opts?: WorkerChoiceStrategyOptions);
-    protected setTaskStatisticsRequirements(opts: WorkerChoiceStrategyOptions): void;
-    private toggleMedianMeasurementStatisticsRequirements;
-    protected resetWorkerNodeKeyProperties(): void;
-    /** @inheritDoc */
-    abstract reset(): boolean;
-    /** @inheritDoc */
-    abstract update(workerNodeKey: number): boolean;
-    /** @inheritDoc */
-    abstract choose(): number | undefined;
-    /** @inheritDoc */
-    abstract remove(workerNodeKey: number): boolean;
-    /** @inheritDoc */
-    setOptions(opts: WorkerChoiceStrategyOptions): void;
-    /**
-     * Whether the worker node is ready or not.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @returns Whether the worker node is ready or not.
-     */
-    private isWorkerNodeReady;
-    /**
-     * Whether the worker node has back pressure or not (i.e. its tasks queue is full).
-     *
-     * @param workerNodeKey - The worker node key.
-     * @returns `true` if the worker node has back pressure, `false` otherwise.
-     */
-    private hasWorkerNodeBackPressure;
-    /**
-     * Whether the worker node is eligible or not.
-     * A worker node is eligible if it is ready and does not have back pressure.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @returns `true` if the worker node is eligible, `false` otherwise.
-     * @see {@link isWorkerNodeReady}
-     * @see {@link hasWorkerNodeBackPressure}
-     */
-    protected isWorkerNodeEligible(workerNodeKey: number): boolean;
-    /**
-     * Gets the worker task runtime.
-     * If the task statistics require the average runtime, the average runtime is returned.
-     * If the task statistics require the median runtime , the median runtime is returned.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @returns The worker task runtime.
-     */
-    protected getWorkerTaskRunTime(workerNodeKey: number): number;
-    /**
-     * Gets the worker task wait time.
-     * If the task statistics require the average wait time, the average wait time is returned.
-     * If the task statistics require the median wait time, the median wait time is returned.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @returns The worker task wait time.
-     */
-    protected getWorkerTaskWaitTime(workerNodeKey: number): number;
-    /**
-     * Gets the worker task ELU.
-     * If the task statistics require the average ELU, the average ELU is returned.
-     * If the task statistics require the median ELU, the median ELU is returned.
-     *
-     * @param workerNodeKey - The worker node key.
-     * @returns The worker task ELU.
-     */
-    protected getWorkerTaskElu(workerNodeKey: number): number;
-    /**
-     * Check the next worker node eligibility.
-     *
-     * @param chosenNextWorkerNodeKey - The chosen worker node key.
-     */
-    protected checkNextWorkerNodeEligibility(chosenNextWorkerNodeKey: number | undefined): void;
-    protected computeDefaultWorkerWeight(): number;
-}

package/lib/pools/selection-strategies/fair-share-worker-choice-strategy.d.ts

@@ -1,39 +0,0 @@
-import type { IPool } from '../pool';
-import type { IWorker } from '../worker';
-import { AbstractWorkerChoiceStrategy } from './abstract-worker-choice-strategy';
-import { type IWorkerChoiceStrategy, type TaskStatisticsRequirements, type WorkerChoiceStrategyOptions } from './selection-strategies-types';
-/**
- * Selects the next worker with a fair share scheduling algorithm.
- * Loosely modeled after the fair queueing algorithm: https://en.wikipedia.org/wiki/Fair_queuing.
- *
- * @typeParam Worker - Type of worker which manages the strategy.
- * @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 class FairShareWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> extends AbstractWorkerChoiceStrategy<Worker, Data, Response> implements IWorkerChoiceStrategy {
-    /** @inheritDoc */
-    readonly taskStatisticsRequirements: TaskStatisticsRequirements;
-    /**
-     * Workers' virtual task end execution timestamp.
-     */
-    private workersVirtualTaskEndTimestamp;
-    /** @inheritDoc */
-    constructor(pool: IPool<Worker, Data, Response>, opts?: WorkerChoiceStrategyOptions);
-    /** @inheritDoc */
-    reset(): boolean;
-    /** @inheritDoc */
-    update(workerNodeKey: number): boolean;
-    /** @inheritDoc */
-    choose(): number | undefined;
-    /** @inheritDoc */
-    remove(workerNodeKey: number): boolean;
-    private fairShareNextWorkerNodeKey;
-    /**
-     * Computes the worker node key virtual task end timestamp.
-     *
-     * @param workerNodeKey - The worker node key.
-     */
-    private computeWorkerVirtualTaskEndTimestamp;
-    private getWorkerVirtualTaskEndTimestamp;
-    private getWorkerVirtualTaskStartTimestamp;
-}

package/lib/pools/selection-strategies/interleaved-weighted-round-robin-worker-choice-strategy.d.ts

@@ -1,39 +0,0 @@
-import type { IWorker } from '../worker';
-import type { IPool } from '../pool';
-import { AbstractWorkerChoiceStrategy } from './abstract-worker-choice-strategy';
-import type { IWorkerChoiceStrategy, WorkerChoiceStrategyOptions } from './selection-strategies-types';
-/**
- * Selects the next worker with an interleaved weighted round robin scheduling algorithm.
- *
- * @typeParam Worker - Type of worker which manages the strategy.
- * @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 class InterleavedWeightedRoundRobinWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> extends AbstractWorkerChoiceStrategy<Worker, Data, Response> implements IWorkerChoiceStrategy {
-    /**
-     * Round id.
-     * This is used to determine the current round weight.
-     */
-    private roundId;
-    /**
-     * Round weights.
-     */
-    private roundWeights;
-    /**
-     * Default worker weight.
-     */
-    private readonly defaultWorkerWeight;
-    /** @inheritDoc */
-    constructor(pool: IPool<Worker, Data, Response>, opts?: WorkerChoiceStrategyOptions);
-    /** @inheritDoc */
-    reset(): boolean;
-    /** @inheritDoc */
-    update(): boolean;
-    /** @inheritDoc */
-    choose(): number | undefined;
-    /** @inheritDoc */
-    remove(workerNodeKey: number): boolean;
-    /** @inheritDoc */
-    setOptions(opts: WorkerChoiceStrategyOptions): void;
-    private getRoundWeights;
-}

package/lib/pools/selection-strategies/least-busy-worker-choice-strategy.d.ts

@@ -1,26 +0,0 @@
-import type { IPool } from '../pool';
-import type { IWorker } from '../worker';
-import { AbstractWorkerChoiceStrategy } from './abstract-worker-choice-strategy';
-import type { IWorkerChoiceStrategy, TaskStatisticsRequirements, WorkerChoiceStrategyOptions } from './selection-strategies-types';
-/**
- * Selects the least busy worker.
- *
- * @typeParam Worker - Type of worker which manages the strategy.
- * @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 class LeastBusyWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> extends AbstractWorkerChoiceStrategy<Worker, Data, Response> implements IWorkerChoiceStrategy {
-    /** @inheritDoc */
-    readonly taskStatisticsRequirements: TaskStatisticsRequirements;
-    /** @inheritDoc */
-    constructor(pool: IPool<Worker, Data, Response>, opts?: WorkerChoiceStrategyOptions);
-    /** @inheritDoc */
-    reset(): boolean;
-    /** @inheritDoc */
-    update(): boolean;
-    /** @inheritDoc */
-    choose(): number | undefined;
-    /** @inheritDoc */
-    remove(): boolean;
-    private leastBusyNextWorkerNodeKey;
-}

package/lib/pools/selection-strategies/least-elu-worker-choice-strategy.d.ts

@@ -1,26 +0,0 @@
-import type { IPool } from '../pool';
-import type { IWorker } from '../worker';
-import { AbstractWorkerChoiceStrategy } from './abstract-worker-choice-strategy';
-import type { IWorkerChoiceStrategy, TaskStatisticsRequirements, WorkerChoiceStrategyOptions } from './selection-strategies-types';
-/**
- * Selects the worker with the least ELU.
- *
- * @typeParam Worker - Type of worker which manages the strategy.
- * @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 class LeastEluWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> extends AbstractWorkerChoiceStrategy<Worker, Data, Response> implements IWorkerChoiceStrategy {
-    /** @inheritDoc */
-    readonly taskStatisticsRequirements: TaskStatisticsRequirements;
-    /** @inheritDoc */
-    constructor(pool: IPool<Worker, Data, Response>, opts?: WorkerChoiceStrategyOptions);
-    /** @inheritDoc */
-    reset(): boolean;
-    /** @inheritDoc */
-    update(): boolean;
-    /** @inheritDoc */
-    choose(): number | undefined;
-    /** @inheritDoc */
-    remove(): boolean;
-    private leastEluNextWorkerNodeKey;
-}

package/lib/pools/selection-strategies/least-used-worker-choice-strategy.d.ts

@@ -1,24 +0,0 @@
-import type { IPool } from '../pool';
-import type { IWorker } from '../worker';
-import { AbstractWorkerChoiceStrategy } from './abstract-worker-choice-strategy';
-import type { IWorkerChoiceStrategy, WorkerChoiceStrategyOptions } from './selection-strategies-types';
-/**
- * Selects the least used worker.
- *
- * @typeParam Worker - Type of worker which manages the strategy.
- * @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 class LeastUsedWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> extends AbstractWorkerChoiceStrategy<Worker, Data, Response> implements IWorkerChoiceStrategy {
-    /** @inheritDoc */
-    constructor(pool: IPool<Worker, Data, Response>, opts?: WorkerChoiceStrategyOptions);
-    /** @inheritDoc */
-    reset(): boolean;
-    /** @inheritDoc */
-    update(): boolean;
-    /** @inheritDoc */
-    choose(): number | undefined;
-    /** @inheritDoc */
-    remove(): boolean;
-    private leastUsedNextWorkerNodeKey;
-}

package/lib/pools/selection-strategies/round-robin-worker-choice-strategy.d.ts

@@ -1,24 +0,0 @@
-import type { IPool } from '../pool';
-import type { IWorker } from '../worker';
-import { AbstractWorkerChoiceStrategy } from './abstract-worker-choice-strategy';
-import type { IWorkerChoiceStrategy, WorkerChoiceStrategyOptions } from './selection-strategies-types';
-/**
- * Selects the next worker in a round robin fashion.
- *
- * @typeParam Worker - Type of worker which manages the strategy.
- * @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 class RoundRobinWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> extends AbstractWorkerChoiceStrategy<Worker, Data, Response> implements IWorkerChoiceStrategy {
-    /** @inheritDoc */
-    constructor(pool: IPool<Worker, Data, Response>, opts?: WorkerChoiceStrategyOptions);
-    /** @inheritDoc */
-    reset(): boolean;
-    /** @inheritDoc */
-    update(): boolean;
-    /** @inheritDoc */
-    choose(): number | undefined;
-    /** @inheritDoc */
-    remove(workerNodeKey: number): boolean;
-    private roundRobinNextWorkerNodeKey;
-}