X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=src%2Fpools%2Fpool.ts;h=78d298f90f20381d3cb2157d276e32ced109f4a2;hb=2431bdb4c2dc637169bf623a40fc6562f685e56e;hp=907bfcb5982f8e1916877e516c3e791eddcc5be0;hpb=5abbf08a224670226e5432695f490fa44ff34937;p=poolifier.git diff --git a/src/pools/pool.ts b/src/pools/pool.ts index 907bfcb5..78d298f9 100644 --- a/src/pools/pool.ts +++ b/src/pools/pool.ts @@ -1,11 +1,12 @@ -import EventEmitter from 'node:events' +import { EventEmitter } from 'node:events' import type { ErrorHandler, ExitHandler, IWorker, + IWorkerNode, MessageHandler, OnlineHandler, - WorkerNode + WorkerType } from './worker' import type { WorkerChoiceStrategy, @@ -13,21 +14,23 @@ import type { } from './selection-strategies/selection-strategies-types' /** - * Pool types. - * - * @enum - * @internal + * Enumeration of pool types. */ -export enum PoolType { +export const PoolTypes = Object.freeze({ /** * Fixed pool type. */ - FIXED = 'fixed', + fixed: 'fixed', /** * Dynamic pool type. */ - DYNAMIC = 'dynamic' -} + dynamic: 'dynamic' +} as const) + +/** + * Pool type. + */ +export type PoolType = keyof typeof PoolTypes /** * Pool events emitter. @@ -39,7 +42,10 @@ export class PoolEmitter extends EventEmitter {} */ export const PoolEvents = Object.freeze({ full: 'full', - busy: 'busy' + ready: 'ready', + busy: 'busy', + error: 'error', + taskError: 'taskError' } as const) /** @@ -47,6 +53,44 @@ export const PoolEvents = Object.freeze({ */ 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 ratio. */ + 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 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 tasks queue options. */ @@ -56,7 +100,7 @@ export interface TasksQueueOptions { * * @defaultValue 1 */ - concurrency?: number + readonly concurrency?: number } /** @@ -83,12 +127,18 @@ export interface PoolOptions { exitHandler?: ExitHandler /** * 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. * @@ -111,8 +161,8 @@ export interface PoolOptions { * 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 serializable data. - * @typeParam Response - Type of execution response. This can only be serializable data. + * @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, @@ -120,52 +170,44 @@ export interface IPool< Response = unknown > { /** - * Pool type. - * - * If it is `'dynamic'`, it provides the `max` property. + * Pool information. */ - readonly type: PoolType + readonly info: PoolInfo /** * Pool worker nodes. */ - readonly workerNodes: Array> + readonly workerNodes: Array> /** * Emitter on which events can be listened to. * * Events that can currently be listened to: * - * - `'full'`: Emitted when the pool is dynamic and full. - * - `'busy'`: Emitted when the pool is busy. + * - `'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 maximum 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. + * - `'error'`: Emitted when an uncaught error occurs. + * - `'taskError'`: Emitted when an error occurs while executing a task. */ readonly emitter?: PoolEmitter /** - * Finds a free worker node key based on the number of tasks the worker has applied. - * - * If a worker is found with `0` running tasks, it is detected as free and its worker node key is returned. - * - * If no free worker is found, `-1` is returned. - * - * @returns A worker node key if there is one, `-1` otherwise. - */ - findFreeWorkerNodeKey: () => number - /** - * Executes the function specified in the constructor with the task data input parameter. + * Executes the specified function in the worker constructor with the task data input parameter. * - * @param data - The task input data for the specified function. This can only be serializable data. - * @returns Promise that will be resolved when the task is successfully completed. + * @param data - The task input data for the specified worker function. This can only be structured-cloneable data. + * @param name - The name of the worker function to execute. If not specified, the default worker function will be executed. + * @returns Promise that will be fulfilled when the task is completed. */ - execute: (data: Data) => Promise + readonly execute: (data?: Data, name?: string) => Promise /** - * Shutdowns every current worker in this pool. + * Terminates every current worker in this pool. */ - destroy: () => Promise + readonly destroy: () => Promise /** * Sets the worker choice strategy in this pool. * * @param workerChoiceStrategy - The worker choice strategy. * @param workerChoiceStrategyOptions - The worker choice strategy options. */ - setWorkerChoiceStrategy: ( + readonly setWorkerChoiceStrategy: ( workerChoiceStrategy: WorkerChoiceStrategy, workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions ) => void @@ -174,7 +216,7 @@ export interface IPool< * * @param workerChoiceStrategyOptions - The worker choice strategy options. */ - setWorkerChoiceStrategyOptions: ( + readonly setWorkerChoiceStrategyOptions: ( workerChoiceStrategyOptions: WorkerChoiceStrategyOptions ) => void /** @@ -183,7 +225,7 @@ export interface IPool< * @param enable - Whether to enable or disable the worker tasks queue. * @param tasksQueueOptions - The worker tasks queue options. */ - enableTasksQueue: ( + readonly enableTasksQueue: ( enable: boolean, tasksQueueOptions?: TasksQueueOptions ) => void @@ -192,5 +234,5 @@ export interface IPool< * * @param tasksQueueOptions - The worker tasks queue options. */ - setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void + readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void }