poolifier 2.5.3 → 2.6.0

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

@@ -1,7 +1,7 @@
 import type { IPool } from '../pool';
 import type { IWorker } from '../worker';
 import { AbstractWorkerChoiceStrategy } from './abstract-worker-choice-strategy';
-import type { IWorkerChoiceStrategy, RequiredStatistics, WorkerChoiceStrategyOptions } from './selection-strategies-types';
+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.
@@ -12,7 +12,7 @@ import type { IWorkerChoiceStrategy, RequiredStatistics, WorkerChoiceStrategyOpt
  */
 export declare class FairShareWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> extends AbstractWorkerChoiceStrategy<Worker, Data, Response> implements IWorkerChoiceStrategy {
     /** @inheritDoc */
-    readonly requiredStatistics: RequiredStatistics;
+    readonly taskStatisticsRequirements: TaskStatisticsRequirements;
     /**
      * Workers' virtual task end execution timestamp.
      */

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

@@ -1,7 +1,7 @@
 import type { IPool } from '../pool';
 import type { IWorker } from '../worker';
 import { AbstractWorkerChoiceStrategy } from './abstract-worker-choice-strategy';
-import type { IWorkerChoiceStrategy, RequiredStatistics, WorkerChoiceStrategyOptions } from './selection-strategies-types';
+import type { IWorkerChoiceStrategy, TaskStatisticsRequirements, WorkerChoiceStrategyOptions } from './selection-strategies-types';
 /**
  * Selects the least busy worker.
  *
@@ -11,7 +11,7 @@ import type { IWorkerChoiceStrategy, RequiredStatistics, WorkerChoiceStrategyOpt
  */
 export declare class LeastBusyWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> extends AbstractWorkerChoiceStrategy<Worker, Data, Response> implements IWorkerChoiceStrategy {
     /** @inheritDoc */
-    readonly requiredStatistics: RequiredStatistics;
+    readonly taskStatisticsRequirements: TaskStatisticsRequirements;
     /** @inheritDoc */
     constructor(pool: IPool<Worker, Data, Response>, opts?: WorkerChoiceStrategyOptions);
     /** @inheritDoc */

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

@@ -0,0 +1,25 @@
+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 serializable data.
+ * @typeParam Response - Type of execution response. This can only be serializable 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;
+    /** @inheritDoc */
+    remove(): boolean;
+}

package/lib/pools/selection-strategies/selection-strategies-types.d.ts

@@ -14,6 +14,12 @@ export declare const WorkerChoiceStrategies: Readonly<{
      * Least busy worker selection strategy.
      */
     readonly LEAST_BUSY: "LEAST_BUSY";
+    /**
+     * Least ELU worker selection strategy.
+     *
+     * @experimental
+     */
+    readonly LEAST_ELU: "LEAST_ELU";
     /**
      * Fair share worker selection strategy.
      */
@@ -33,22 +39,53 @@ export declare const WorkerChoiceStrategies: Readonly<{
  * Worker choice strategy.
  */
 export type WorkerChoiceStrategy = keyof typeof WorkerChoiceStrategies;
+/**
+ * Enumeration of measurements.
+ */
+export declare const Measurements: Readonly<{
+    readonly runTime: "runTime";
+    readonly waitTime: "waitTime";
+    readonly elu: "elu";
+}>;
+/**
+ * Measurement.
+ */
+export type Measurement = keyof typeof Measurements;
+/**
+ * Measurement options.
+ */
+export interface MeasurementOptions {
+    /**
+     * Set measurement median.
+     */
+    median: boolean;
+}
 /**
  * Worker choice strategy options.
  */
 export interface WorkerChoiceStrategyOptions {
     /**
-     * Use tasks median runtime instead of average runtime.
+     * Measurement to use for worker choice strategy.
+     */
+    measurement?: Measurement;
+    /**
+     * Runtime options.
+     *
+     * @defaultValue \{ median: false \}
+     */
+    runTime?: MeasurementOptions;
+    /**
+     * Wait time options.
      *
-     * @defaultValue false
+     * @defaultValue \{ median: false \}
      */
-    medRunTime?: boolean;
+    waitTime?: MeasurementOptions;
     /**
-     * Use tasks median wait time instead of average runtime.
+     * Event loop utilization options.
      *
-     * @defaultValue false
+     * @defaultValue \{ median: false \}
      */
-    medWaitTime?: boolean;
+    elu?: MeasurementOptions;
     /**
      * Worker weights to use for weighted round robin worker selection strategy.
      * Weight is the tasks maximum average or median runtime in milliseconds.
@@ -58,44 +95,51 @@ export interface WorkerChoiceStrategyOptions {
     weights?: Record<number, number>;
 }
 /**
- * Pool worker tasks usage statistics requirements.
+ * Measurement statistics requirements.
  *
  * @internal
  */
-export interface RequiredStatistics {
+export interface MeasurementStatisticsRequirements {
     /**
-     * Require tasks runtime.
+     * Require measurement aggregate.
      */
-    runTime: boolean;
+    aggregate: boolean;
     /**
-     * Require tasks average runtime.
+     * Require measurement average.
      */
-    avgRunTime: boolean;
+    average: boolean;
     /**
-     * Require tasks median runtime.
+     * Require measurement median.
      */
-    medRunTime: boolean;
+    median: boolean;
+}
+/**
+ * Pool worker node worker usage statistics requirements.
+ *
+ * @internal
+ */
+export interface TaskStatisticsRequirements {
     /**
-     * Require tasks wait time.
+     * Tasks runtime requirements.
      */
-    waitTime: boolean;
+    runTime: MeasurementStatisticsRequirements;
     /**
-     * Require tasks average wait time.
+     * Tasks wait time requirements.
      */
-    avgWaitTime: boolean;
+    waitTime: MeasurementStatisticsRequirements;
     /**
-     * Require tasks median wait time.
+     * Tasks event loop utilization requirements.
      */
-    medWaitTime: boolean;
+    elu: MeasurementStatisticsRequirements;
 }
 /**
  * Worker choice strategy interface.
  */
 export interface IWorkerChoiceStrategy {
     /**
-     * Required tasks usage statistics.
+     * Tasks statistics requirements.
      */
-    readonly requiredStatistics: RequiredStatistics;
+    readonly taskStatisticsRequirements: TaskStatisticsRequirements;
     /**
      * Resets strategy internals.
      *

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

@@ -1,7 +1,7 @@
 import type { IWorker } from '../worker';
 import type { IPool } from '../pool';
 import { AbstractWorkerChoiceStrategy } from './abstract-worker-choice-strategy';
-import type { IWorkerChoiceStrategy, RequiredStatistics, WorkerChoiceStrategyOptions } from './selection-strategies-types';
+import type { IWorkerChoiceStrategy, TaskStatisticsRequirements, WorkerChoiceStrategyOptions } from './selection-strategies-types';
 /**
  * Selects the next worker with a weighted round robin scheduling algorithm.
  * Loosely modeled after the weighted round robin queueing algorithm: https://en.wikipedia.org/wiki/Weighted_round_robin.
@@ -12,7 +12,7 @@ import type { IWorkerChoiceStrategy, RequiredStatistics, WorkerChoiceStrategyOpt
  */
 export declare class WeightedRoundRobinWorkerChoiceStrategy<Worker extends IWorker, Data = unknown, Response = unknown> extends AbstractWorkerChoiceStrategy<Worker, Data, Response> implements IWorkerChoiceStrategy {
     /** @inheritDoc */
-    readonly requiredStatistics: RequiredStatistics;
+    readonly taskStatisticsRequirements: TaskStatisticsRequirements;
     /**
      * Worker node id where the current task will be submitted.
      */

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

@@ -1,6 +1,6 @@
 import type { IPool } from '../pool';
 import type { IWorker } from '../worker';
-import type { RequiredStatistics, WorkerChoiceStrategy, WorkerChoiceStrategyOptions } from './selection-strategies-types';
+import type { TaskStatisticsRequirements, WorkerChoiceStrategy, WorkerChoiceStrategyOptions } from './selection-strategies-types';
 /**
  * The worker choice strategy context.
  *
@@ -20,11 +20,11 @@ export declare class WorkerChoiceStrategyContext<Worker extends IWorker, Data =
      */
     constructor(pool: IPool<Worker, Data, Response>, workerChoiceStrategy?: WorkerChoiceStrategy, opts?: WorkerChoiceStrategyOptions);
     /**
-     * Gets the worker choice strategy in the context required statistics.
+     * Gets the worker choice strategy task statistics requirements in the context.
      *
-     * @returns The required statistics.
+     * @returns The task statistics requirements.
      */
-    getRequiredStatistics(): RequiredStatistics;
+    getTaskStatisticsRequirements(): TaskStatisticsRequirements;
     /**
      * Sets the worker choice strategy to use in the context.
      *

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

@@ -1,5 +1,5 @@
-import { type PoolOptions, type PoolType } from '../pool';
-import { FixedThreadPool, type ThreadWorkerWithMessageChannel } from './fixed';
+import { type PoolType } from '../pool';
+import { FixedThreadPool, type ThreadPoolOptions } from './fixed';
 /**
  * A thread pool with a dynamic number of threads, but a guaranteed minimum number of threads.
  *
@@ -21,7 +21,7 @@ export declare class DynamicThreadPool<Data = unknown, Response = unknown> exten
      * @param filePath - Path to an implementation of a `ThreadWorker` file, which can be relative or absolute.
      * @param opts - Options for this dynamic thread pool.
      */
-    constructor(min: number, max: number, filePath: string, opts?: PoolOptions<ThreadWorkerWithMessageChannel>);
+    constructor(min: number, max: number, filePath: string, opts?: ThreadPoolOptions);
     /** @inheritDoc */
     protected get type(): PoolType;
     /** @inheritDoc */

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

@@ -1,8 +1,19 @@
 /// <reference types="node" />
-import { MessageChannel, Worker } from 'node:worker_threads';
+import { MessageChannel, Worker, type WorkerOptions } from 'node:worker_threads';
 import type { Draft, MessageValue } from '../../utility-types';
 import { AbstractPool } from '../abstract-pool';
 import { type PoolOptions, type PoolType, type WorkerType } from '../pool';
+/**
+ * Options for a poolifier thread pool.
+ */
+export interface ThreadPoolOptions extends PoolOptions<Worker> {
+    /**
+     * Worker options.
+     *
+     * @see https://nodejs.org/api/worker_threads.html#new-workerfilename-options
+     */
+    workerOptions?: WorkerOptions;
+}
 /**
  * A thread worker with message channels for communication between main thread and thread worker.
  */
@@ -12,14 +23,13 @@ export type ThreadWorkerWithMessageChannel = Worker & Draft<MessageChannel>;
  *
  * It is possible to perform tasks in sync or asynchronous mode as you prefer.
  *
- * This pool selects the threads in a round robin fashion.
- *
  * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
  * @typeParam Response - Type of execution response. This can only be serializable data.
  * @author [Alessandro Pio Ardizio](https://github.com/pioardi)
  * @since 0.0.1
  */
 export declare class FixedThreadPool<Data = unknown, Response = unknown> extends AbstractPool<ThreadWorkerWithMessageChannel, Data, Response> {
+    protected readonly opts: ThreadPoolOptions;
     /**
      * Constructs a new poolifier fixed thread pool.
      *
@@ -27,7 +37,7 @@ export declare class FixedThreadPool<Data = unknown, Response = unknown> extends
      * @param filePath - Path to an implementation of a `ThreadWorker` file, which can be relative or absolute.
      * @param opts - Options for this fixed thread pool.
      */
-    constructor(numberOfThreads: number, filePath: string, opts?: PoolOptions<ThreadWorkerWithMessageChannel>);
+    constructor(numberOfThreads: number, filePath: string, opts?: ThreadPoolOptions);
     /** @inheritDoc */
     protected isMain(): boolean;
     /** @inheritDoc */

package/lib/pools/worker.d.ts

@@ -32,64 +32,92 @@ export interface Task<Data = unknown> {
      */
     readonly data?: Data;
     /**
-     * Submission timestamp.
+     * Timestamp.
      */
-    readonly submissionTimestamp?: number;
+    readonly timestamp?: number;
     /**
      * Message UUID.
      */
     readonly id?: string;
 }
 /**
- * Worker tasks usage statistics.
+ * Measurement statistics.
  *
  * @internal
  */
-export interface TasksUsage {
+export interface MeasurementStatistics {
     /**
-     * Number of tasks executed.
+     * Measurement aggregate.
      */
-    run: number;
+    aggregate: number;
     /**
-     * Number of tasks running.
+     * Measurement average.
      */
-    running: number;
+    average: number;
     /**
-     * Tasks runtime.
+     * Measurement median.
      */
-    runTime: number;
+    median: number;
     /**
-     * Tasks runtime history.
+     * Measurement history.
      */
-    runTimeHistory: CircularArray<number>;
+    history: CircularArray<number>;
+}
+/**
+ * Event loop utilization measurement statistics.
+ *
+ * @internal
+ */
+export interface EventLoopUtilizationMeasurementStatistics {
+    idle: MeasurementStatistics;
+    active: MeasurementStatistics;
+    utilization: number;
+}
+/**
+ * Task statistics.
+ *
+ * @internal
+ */
+export interface TaskStatistics {
+    /**
+     * Number of executed tasks.
+     */
+    executed: number;
     /**
-     * Average tasks runtime.
+     * Number of executing tasks.
      */
-    avgRunTime: number;
+    executing: number;
     /**
-     * Median tasks runtime.
+     * Number of queued tasks.
      */
-    medRunTime: number;
+    readonly queued: number;
     /**
-     * Tasks wait time.
+     * Number of failed tasks.
      */
-    waitTime: number;
+    failed: number;
+}
+/**
+ * Worker usage statistics.
+ *
+ * @internal
+ */
+export interface WorkerUsage {
     /**
-     * Tasks wait time history.
+     * Tasks statistics.
      */
-    waitTimeHistory: CircularArray<number>;
+    tasks: TaskStatistics;
     /**
-     * Average tasks wait time.
+     * Tasks runtime statistics.
      */
-    avgWaitTime: number;
+    runTime: MeasurementStatistics;
     /**
-     * Median tasks wait time.
+     * Tasks wait time statistics.
      */
-    medWaitTime: number;
+    waitTime: MeasurementStatistics;
     /**
-     * Number of tasks errored.
+     * Tasks event loop utilization statistics.
      */
-    error: number;
+    elu: EventLoopUtilizationMeasurementStatistics;
 }
 /**
  * Worker interface.
@@ -123,9 +151,9 @@ export interface WorkerNode<Worker extends IWorker, Data = unknown> {
      */
     readonly worker: Worker;
     /**
-     * Worker node tasks usage statistics.
+     * Worker node worker usage statistics.
      */
-    tasksUsage: TasksUsage;
+    workerUsage: WorkerUsage;
     /**
      * Worker node tasks queue.
      */

package/lib/utility-types.d.ts

@@ -1,7 +1,9 @@
 /// <reference types="node" />
 /// <reference types="node" />
+/// <reference types="node" />
 import type { Worker as ClusterWorker } from 'node:cluster';
 import type { MessagePort } from 'node:worker_threads';
+import type { EventLoopUtilization } from 'node:perf_hooks';
 import type { KillBehavior } from './worker/worker-options';
 import type { IWorker, Task } from './pools/worker';
 /**
@@ -13,71 +15,74 @@ export type Draft<T> = {
     -readonly [P in keyof T]?: T[P];
 };
 /**
- * Message object that is passed between main worker and worker.
+ * Task error.
  *
  * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
- * @typeParam MainWorker - Type of main worker.
- * @internal
  */
-export interface MessageValue<Data = unknown, MainWorker extends ClusterWorker | MessagePort = ClusterWorker | MessagePort> extends Task<Data> {
-    /**
-     * Kill code.
-     */
-    readonly kill?: KillBehavior | 1;
+export interface TaskError<Data = unknown> {
     /**
-     * Task error.
+     * Error message.
      */
-    readonly error?: string;
+    message: string;
     /**
-     * Task data triggering task error.
+     * Data passed to the worker triggering the error.
      */
-    readonly errorData?: unknown;
+    data?: Data;
+}
+/**
+ * Task performance.
+ */
+export interface TaskPerformance {
     /**
-     * Runtime.
+     * Task performance timestamp.
      */
-    readonly runTime?: number;
+    timestamp: number;
     /**
-     * Wait time.
+     * Task runtime.
      */
-    readonly waitTime?: number;
+    runTime?: number;
     /**
-     * Reference to main worker.
+     * Task event loop utilization.
      */
-    readonly parent?: MainWorker;
+    elu?: EventLoopUtilization;
 }
 /**
- * Worker synchronous function that can be executed.
- *
- * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
- * @typeParam Response - Type of execution response. This can only be serializable data.
- */
-export type WorkerSyncFunction<Data = unknown, Response = unknown> = (data?: Data) => Response;
-/**
- * Worker asynchronous function that can be executed.
- * This function must return a promise.
- *
- * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
- * @typeParam Response - Type of execution response. This can only be serializable data.
- */
-export type WorkerAsyncFunction<Data = unknown, Response = unknown> = (data?: Data) => Promise<Response>;
-/**
- * Worker function that can be executed.
- * This function can be synchronous or asynchronous.
- *
- * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
- * @typeParam Response - Type of execution response. This can only be serializable data.
+ * Performance statistics computation.
  */
-export type WorkerFunction<Data = unknown, Response = unknown> = WorkerSyncFunction<Data, Response> | WorkerAsyncFunction<Data, Response>;
+export interface WorkerStatistics {
+    runTime: boolean;
+    elu: boolean;
+}
 /**
- * Worker functions that can be executed.
- * This object can contain synchronous or asynchronous functions.
- * The key is the name of the function.
- * The value is the function itself.
+ * Message object that is passed between main worker and worker.
  *
+ * @typeParam MessageData - Type of data sent to and/or from the worker. This can only be serializable data.
  * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
- * @typeParam Response - Type of execution response. This can only be serializable data.
+ * @typeParam MainWorker - Type of main worker.
+ * @internal
  */
-export type TaskFunctions<Data = unknown, Response = unknown> = Record<string, WorkerFunction<Data, Response>>;
+export interface MessageValue<MessageData = unknown, Data = unknown, MainWorker extends ClusterWorker | MessagePort = ClusterWorker | MessagePort> extends Task<MessageData> {
+    /**
+     * Kill code.
+     */
+    readonly kill?: KillBehavior | 1;
+    /**
+     * Task error.
+     */
+    readonly taskError?: TaskError<Data>;
+    /**
+     * Task performance.
+     */
+    readonly taskPerformance?: TaskPerformance;
+    /**
+     * Reference to main worker.
+     */
+    readonly parent?: MainWorker;
+    /**
+     * Whether to compute the given statistics or not.
+     */
+    readonly statistics?: WorkerStatistics;
+}
 /**
  * An object holding the execution response promise resolve/reject callbacks.
  *

package/lib/worker/abstract-worker.d.ts

@@ -5,8 +5,9 @@
 import { AsyncResource } from 'node:async_hooks';
 import type { Worker } from 'node:cluster';
 import type { MessagePort } from 'node:worker_threads';
-import type { MessageValue, TaskFunctions, WorkerAsyncFunction, WorkerFunction, WorkerSyncFunction } from '../utility-types';
+import type { MessageValue, WorkerStatistics } from '../utility-types';
 import { type WorkerOptions } from './worker-options';
+import type { TaskFunctions, WorkerAsyncFunction, WorkerFunction, WorkerSyncFunction } from './worker-functions';
 /**
  * Base class that implements some shared logic for all poolifier workers.
  *
@@ -26,6 +27,10 @@ export declare abstract class AbstractWorker<MainWorker extends Worker | Message
      * Timestamp of the last task processed by this worker.
      */
     protected lastTaskTimestamp: number;
+    /**
+     * Performance statistics computation.
+     */
+    protected statistics: WorkerStatistics;
     /**
      * Handler id of the `aliveInterval` worker alive check.
      */
@@ -52,7 +57,7 @@ export declare abstract class AbstractWorker<MainWorker extends Worker | Message
      *
      * @param message - Message received.
      */
-    protected messageListener(message: MessageValue<Data, MainWorker>): void;
+    protected messageListener(message: MessageValue<Data, Data, MainWorker>): void;
     /**
      * Returns the main worker.
      *
@@ -64,7 +69,7 @@ export declare abstract class AbstractWorker<MainWorker extends Worker | Message
      *
      * @param message - The response message.
      */
-    protected abstract sendToMainWorker(message: MessageValue<Response>): void;
+    protected abstract sendToMainWorker(message: MessageValue<Response, Data>): void;
     /**
      * Checks if the worker should be terminated, because its living too long.
      */
@@ -96,4 +101,6 @@ export declare abstract class AbstractWorker<MainWorker extends Worker | Message
      * @param name - Name of the function that will be returned.
      */
     private getTaskFunction;
+    private beginTaskPerformance;
+    private endTaskPerformance;
 }

package/lib/worker/cluster-worker.d.ts

@@ -1,8 +1,9 @@
 /// <reference types="node" />
 import { type Worker } from 'node:cluster';
-import type { MessageValue, TaskFunctions, WorkerFunction } from '../utility-types';
+import type { MessageValue } from '../utility-types';
 import { AbstractWorker } from './abstract-worker';
 import type { WorkerOptions } from './worker-options';
+import type { TaskFunctions, WorkerFunction } from './worker-functions';
 /**
  * A cluster worker used by a poolifier `ClusterPool`.
  *

package/lib/worker/thread-worker.d.ts

@@ -1,8 +1,9 @@
 /// <reference types="node" />
 import { type MessagePort } from 'node:worker_threads';
-import type { MessageValue, TaskFunctions, WorkerFunction } from '../utility-types';
+import type { MessageValue } from '../utility-types';
 import { AbstractWorker } from './abstract-worker';
 import type { WorkerOptions } from './worker-options';
+import type { TaskFunctions, WorkerFunction } from './worker-functions';
 /**
  * A thread worker used by a poolifier `ThreadPool`.
  *