X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=src%2Fpools%2Fpool.ts;h=26ca4c03279ad9969df3940141cf0bade3b815b4;hb=671d515455c745dc74f4c385fe23683975bfc3df;hp=f24d79e41e01dfba297821ea88acc22066052550;hpb=ffe8ca52bf1a05f68a0c939d16f15b6b54028be9;p=poolifier.git diff --git a/src/pools/pool.ts b/src/pools/pool.ts index f24d79e4..26ca4c03 100644 --- a/src/pools/pool.ts +++ b/src/pools/pool.ts @@ -1,16 +1,38 @@ -import EventEmitter from 'node:events' +import { EventEmitter } from 'node:events' +import { type TransferListItem } from 'node:worker_threads' import type { ErrorHandler, ExitHandler, IWorker, + IWorkerNode, MessageHandler, - OnlineHandler + OnlineHandler, + WorkerType } from './worker' import type { WorkerChoiceStrategy, WorkerChoiceStrategyOptions } from './selection-strategies/selection-strategies-types' +/** + * Enumeration of pool types. + */ +export const PoolTypes = Object.freeze({ + /** + * Fixed pool type. + */ + fixed: 'fixed', + /** + * Dynamic pool type. + */ + dynamic: 'dynamic' +} as const) + +/** + * Pool type. + */ +export type PoolType = keyof typeof PoolTypes + /** * Pool events emitter. */ @@ -20,8 +42,13 @@ export class PoolEmitter extends EventEmitter {} * Enumeration of pool events. */ export const PoolEvents = Object.freeze({ + ready: 'ready', + busy: 'busy', full: 'full', - busy: 'busy' + destroy: 'destroy', + error: 'error', + taskError: 'taskError', + backPressure: 'backPressure' } as const) /** @@ -29,10 +56,66 @@ 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. */ + 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. + */ +export interface TasksQueueOptions { + /** + * Maximum number of tasks that can be executed concurrently on a worker. + * + * @defaultValue 1 + */ + readonly concurrency?: number +} + /** * Options for a poolifier pool. + * + * @typeParam Worker - Type of worker. */ export interface PoolOptions { + /** + * A function that will listen for online event on each worker. + */ + onlineHandler?: OnlineHandler /** * A function that will listen for message event on each worker. */ @@ -41,22 +124,24 @@ export interface PoolOptions { * A function that will listen for error event on each worker. */ 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. */ 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. * @@ -66,43 +151,103 @@ export interface PoolOptions { /** * Pool worker tasks queue. * - * @experimental * @defaultValue false */ enableTasksQueue?: boolean + /** + * Pool worker tasks queue options. + */ + tasksQueueOptions?: TasksQueueOptions } /** * Contract definition for a poolifier pool. * - * @typeParam Data - Type of data sent to the worker. This can only be serializable data. - * @typeParam Response - Type of response of execution. This can only be serializable data. + * @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 { +export interface IPool< + Worker extends IWorker, + Data = unknown, + Response = unknown +> { + /** + * Pool information. + */ + readonly info: PoolInfo + /** + * Pool worker nodes. + */ + 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. + * - `'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. */ readonly emitter?: PoolEmitter /** - * Performs the task specified in the constructor with the data parameter. + * Executes the specified function in the worker constructor with the task data input parameter. * - * @param data - The input for the specified task. This can only be serializable data. - * @returns Promise that will be resolved when the task is successfully completed. + * @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 + /** + * Terminates all workers in this pool. */ - execute: (data: Data) => Promise + readonly destroy: () => Promise /** - * Shutdowns every current worker in this pool. + * Lists the names of task function available in this pool. + * + * @returns The names of task function available in this pool. */ - destroy: () => Promise + 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 tasks queue in this pool. + * + * @param enable - Whether to enable or disable the worker tasks queue. + * @param tasksQueueOptions - The worker tasks queue options. + */ + readonly enableTasksQueue: ( + enable: boolean, + tasksQueueOptions?: TasksQueueOptions + ) => void + /** + * Sets the worker tasks queue options in this pool. + * + * @param tasksQueueOptions - The worker tasks queue options. */ - setWorkerChoiceStrategy: (workerChoiceStrategy: WorkerChoiceStrategy) => void + readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void }