X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=src%2Fpools%2Fpool.ts;h=ab2cf2e49258acf35c267f03d5c88bab91f1428e;hb=ae036c3e73796126b7f1138129b6b18ef6bcef8c;hp=1a05f633250adb8e88c72a63cda565c3265205bc;hpb=f7b2b8101acbc121ec9c787a8b1c72ba3375175b;p=poolifier.git diff --git a/src/pools/pool.ts b/src/pools/pool.ts index 1a05f633..ab2cf2e4 100644 --- a/src/pools/pool.ts +++ b/src/pools/pool.ts @@ -1,5 +1,6 @@ import { EventEmitter } from 'node:events' import { type TransferListItem } from 'node:worker_threads' +import type { TaskFunction } from '../worker/task-functions' import type { ErrorHandler, ExitHandler, @@ -42,11 +43,13 @@ export class PoolEmitter extends EventEmitter {} * Enumeration of pool events. */ export const PoolEvents = Object.freeze({ - full: 'full', ready: 'ready', busy: 'busy', + full: 'full', + destroy: 'destroy', error: 'error', - taskError: 'taskError' + taskError: 'taskError', + backPressure: 'backPressure' } as const) /** @@ -61,6 +64,7 @@ export interface PoolInfo { readonly version: string readonly type: PoolType readonly worker: WorkerType + readonly started: boolean readonly ready: boolean readonly strategy: WorkerChoiceStrategy readonly minSize: number @@ -77,31 +81,51 @@ export interface PoolInfo { 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 average?: number readonly median?: number } readonly waitTime?: { readonly minimum: number readonly maximum: number - readonly average: number + readonly average?: number readonly median?: number } } /** - * Worker tasks queue options. + * Worker node tasks queue options. */ export interface TasksQueueOptions { /** - * Maximum number of tasks that can be executed concurrently on a worker. + * Maximum tasks queue size per worker node flagging it as back pressured. + * + * @defaultValue (pool maximum size)^2 + */ + readonly size?: number + /** + * Maximum number of tasks that can be executed concurrently on a worker node. * * @defaultValue 1 */ readonly concurrency?: number + /** + * Whether to enable task stealing. + * + * @defaultValue true + */ + readonly taskStealing?: boolean + /** + * Whether to enable tasks stealing on back pressure. + * + * @defaultValue true + */ + readonly tasksStealingOnBackPressure?: boolean } /** @@ -110,22 +134,36 @@ export interface TasksQueueOptions { * @typeParam Worker - Type of worker. */ export interface PoolOptions { + /** + * A function that will listen for online event on each worker. + * + * @defaultValue `() => {}` + */ + onlineHandler?: OnlineHandler /** * A function that will listen for message event on each worker. + * + * @defaultValue `() => {}` */ messageHandler?: MessageHandler /** * A function that will listen for error event on each worker. + * + * @defaultValue `() => {}` */ errorHandler?: ErrorHandler - /** - * A function that will listen for online event on each worker. - */ - onlineHandler?: OnlineHandler /** * A function that will listen for exit event on each worker. + * + * @defaultValue `() => {}` */ exitHandler?: ExitHandler + /** + * Whether to start the minimum number of workers at pool initialization. + * + * @defaultValue true + */ + startWorkers?: boolean /** * The worker choice strategy to use in this pool. * @@ -147,13 +185,13 @@ export interface PoolOptions { */ enableEvents?: boolean /** - * Pool worker tasks queue. + * Pool worker node tasks queue. * * @defaultValue false */ enableTasksQueue?: boolean /** - * Pool worker tasks queue options. + * Pool worker node tasks queue options. */ tasksQueueOptions?: TasksQueueOptions } @@ -176,18 +214,30 @@ export interface IPool< readonly info: PoolInfo /** * Pool worker nodes. + * + * @internal */ readonly workerNodes: Array> + /** + * 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: * - * - `'full'`: Emitted when the pool is dynamic and the number of workers created has reached the maximum size expected. * - `'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. + * - `'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 /** @@ -203,10 +253,55 @@ export interface IPool< name?: string, transferList?: TransferListItem[] ) => Promise + /** + * Starts the minimum number of workers in this pool. + */ + readonly start: () => void /** * Terminates all workers in this pool. */ readonly destroy: () => Promise + /** + * Whether the specified task function exists in this pool. + * + * @param name - The name of the task function. + * @returns `true` if the task function exists, `false` otherwise. + */ + readonly hasTaskFunction: (name: string) => boolean + /** + * Adds a task function to this pool. + * If a task function with the same name already exists, it will be overwritten. + * + * @param name - The name of the task function. + * @param fn - The task function. + * @returns `true` if the task function was added, `false` otherwise. + * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `name` parameter is not a string or an empty string. + * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `fn` parameter is not a function. + */ + readonly addTaskFunction: ( + name: string, + fn: TaskFunction + ) => Promise + /** + * Removes a task function from this pool. + * + * @param name - The name of the task function. + * @returns `true` if the task function was removed, `false` otherwise. + */ + readonly removeTaskFunction: (name: string) => Promise + /** + * Lists the names of task function available in this pool. + * + * @returns The names of task function available in this pool. + */ + readonly listTaskFunctionNames: () => string[] + /** + * Sets the default task function in this pool. + * + * @param name - The name of the task function. + * @returns `true` if the default task function was set, `false` otherwise. + */ + readonly setDefaultTaskFunction: (name: string) => Promise /** * Sets the worker choice strategy in this pool. * @@ -226,19 +321,19 @@ export interface IPool< workerChoiceStrategyOptions: WorkerChoiceStrategyOptions ) => void /** - * Enables/disables the worker tasks queue in this pool. + * Enables/disables the worker node tasks queue in this pool. * - * @param enable - Whether to enable or disable the worker tasks queue. - * @param tasksQueueOptions - The worker tasks queue options. + * @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 tasks queue options in this pool. + * Sets the worker node tasks queue options in this pool. * - * @param tasksQueueOptions - The worker tasks queue options. + * @param tasksQueueOptions - The worker node tasks queue options. */ readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void }