X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=src%2Fpools%2Fpool.ts;h=d7b6eeabeb074c31103854ec2f9789d137ff8409;hb=5b95eb9bcafda56ce57003da834cf4e153bb0509;hp=bb28535b0e732c7eafee9fa353f38166999862e5;hpb=2845f2a5555247bbc4e5f6f1059d4f95405a49cd;p=poolifier.git diff --git a/src/pools/pool.ts b/src/pools/pool.ts index bb28535b..d7b6eeab 100644 --- a/src/pools/pool.ts +++ b/src/pools/pool.ts @@ -1,21 +1,29 @@ -import { EventEmitter } from 'node:events' +import type { ClusterSettings } from 'node:cluster' +import type { EventEmitterAsyncResource } from 'node:events' +import type { TransferListItem, WorkerOptions } from 'node:worker_threads' + +import type { TaskFunction } from '../worker/task-functions.js' +import type { + WorkerChoiceStrategy, + WorkerChoiceStrategyOptions +} from './selection-strategies/selection-strategies-types.js' import type { ErrorHandler, ExitHandler, IWorker, + IWorkerNode, MessageHandler, OnlineHandler, - WorkerNode -} from './worker' -import type { - WorkerChoiceStrategy, - WorkerChoiceStrategyOptions -} from './selection-strategies/selection-strategies-types' + WorkerType +} from './worker.js' /** * Enumeration of pool types. */ -export const PoolTypes = Object.freeze({ +export const PoolTypes: Readonly<{ + fixed: 'fixed' + dynamic: 'dynamic' +}> = Object.freeze({ /** * Fixed pool type. */ @@ -31,32 +39,27 @@ export const PoolTypes = Object.freeze({ */ export type PoolType = keyof typeof PoolTypes -/** - * Enumeration of worker types. - */ -export const WorkerTypes = Object.freeze({ - cluster: 'cluster', - thread: 'thread' -} as const) - -/** - * Worker type. - */ -export type WorkerType = keyof typeof WorkerTypes - -/** - * Pool events emitter. - */ -export class PoolEmitter extends EventEmitter {} - /** * Enumeration of pool events. */ -export const PoolEvents = Object.freeze({ - full: 'full', +export const PoolEvents: Readonly<{ + ready: 'ready' + busy: 'busy' + full: 'full' + empty: 'empty' + destroy: 'destroy' + error: 'error' + taskError: 'taskError' + backPressure: 'backPressure' +}> = Object.freeze({ + ready: 'ready', busy: 'busy', + full: 'full', + empty: 'empty', + destroy: 'destroy', error: 'error', - taskError: 'taskError' + taskError: 'taskError', + backPressure: 'backPressure' } as const) /** @@ -68,36 +71,80 @@ export type PoolEvent = keyof typeof PoolEvents * Pool information. */ export interface PoolInfo { - version: string - type: PoolType - worker: WorkerType - minSize: number - maxSize: number - /** Pool utilization ratio. */ - utilization?: number - /** Pool total worker nodes */ - workerNodes: number - /** Pool idle worker nodes */ - idleWorkerNodes: number - /** Pool busy worker nodes */ - busyWorkerNodes: number - executedTasks: number - executingTasks: number - queuedTasks: number - maxQueuedTasks: number - failedTasks: number + readonly version: string + readonly type: PoolType + readonly worker: WorkerType + readonly started: boolean + readonly ready: boolean + readonly strategy: WorkerChoiceStrategy + readonly strategyRetries: number + readonly minSize: number + readonly maxSize: number + /** Pool utilization. */ + readonly utilization?: number + /** Pool total worker nodes. */ + readonly workerNodes: number + /** Pool stealing worker nodes. */ + readonly stealingWorkerNodes?: 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 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 on idle. + * + * @defaultValue true + */ + readonly taskStealing?: boolean + /** + * Whether to enable tasks stealing under back pressure. + * + * @defaultValue true + */ + readonly tasksStealingOnBackPressure?: boolean + /** + * Queued tasks finished timeout in milliseconds at worker node termination. + * + * @defaultValue 2000 + */ + readonly tasksFinishedTimeout?: number } /** @@ -106,22 +153,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. * @@ -137,21 +198,39 @@ export interface PoolOptions { */ restartWorkerOnError?: boolean /** - * Pool events emission. + * Pool events integrated with async resource emission. * * @defaultValue true */ 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 + /** + * Worker options. + * + * @see https://nodejs.org/api/worker_threads.html#new-workerfilename-options + */ + workerOptions?: WorkerOptions + /** + * Key/value pairs to add to worker process environment. + * + * @see https://nodejs.org/api/cluster.html#cluster_cluster_fork_env + */ + env?: Record + /** + * Cluster settings. + * + * @see https://nodejs.org/api/cluster.html#cluster_cluster_settings + */ + settings?: ClusterSettings } /** @@ -172,38 +251,95 @@ export interface IPool< readonly info: PoolInfo /** * Pool worker nodes. + * + * @internal */ - readonly workerNodes: Array> + readonly workerNodes: Array> /** - * Emitter on which events can be listened to. + * Pool event emitter integrated with async resource. + * The async tracking tooling identifier is `poolifier:--pool`. * * 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. If the pool is dynamic with a minimum number of workers is set to zero, this event is emitted when at least one dynamic worker is ready. + * - `'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. + * - `'empty'`: Emitted when the pool is dynamic with a minimum number of workers set to zero and the number of workers has reached the minimum 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 + readonly emitter?: EventEmitterAsyncResource /** * Executes the specified function in the worker constructor with the task data input parameter. * - * @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. + * @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 chosen 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. */ - execute: (data?: Data, name?: string) => Promise + readonly execute: ( + data?: Data, + 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 /** - * Terminates every current worker in this pool. + * 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. */ - destroy: () => Promise + readonly setDefaultTaskFunction: (name: string) => 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 @@ -212,23 +348,23 @@ export interface IPool< * * @param workerChoiceStrategyOptions - The worker choice strategy options. */ - setWorkerChoiceStrategyOptions: ( + readonly setWorkerChoiceStrategyOptions: ( 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. */ - enableTasksQueue: ( + 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. */ - setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void + readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void }