X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=src%2Fpools%2Fpool.ts;h=bcf7d9385035b938ac3c0ed9bdb24dda6382e0a1;hb=6a3ecc500583fc68d5bbce89f8448ccd022ab900;hp=212253ffbc5be7faff8760dc3847f9cdc486bb89;hpb=037af3175d6121a6c08a631c992aa0d7fe853a9f;p=poolifier.git diff --git a/src/pools/pool.ts b/src/pools/pool.ts index 212253ff..bcf7d938 100644 --- a/src/pools/pool.ts +++ b/src/pools/pool.ts @@ -1,6 +1,12 @@ -import { EventEmitter } from 'node:events' -import { type TransferListItem } from 'node:worker_threads' -import type { TaskFunction } from '../worker/task-functions' +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, @@ -9,16 +15,15 @@ import type { MessageHandler, OnlineHandler, WorkerType -} from './worker' -import type { - WorkerChoiceStrategy, - WorkerChoiceStrategyOptions -} from './selection-strategies/selection-strategies-types' +} 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. */ @@ -34,18 +39,23 @@ export const PoolTypes = Object.freeze({ */ export type PoolType = keyof typeof PoolTypes -/** - * Pool events emitter. - */ -export class PoolEmitter extends EventEmitter {} - /** * Enumeration of pool events. */ -export const PoolEvents = Object.freeze({ +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', @@ -67,12 +77,15 @@ export interface PoolInfo { 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. */ @@ -115,17 +128,23 @@ export interface TasksQueueOptions { */ readonly concurrency?: number /** - * Whether to enable task stealing. + * Whether to enable task stealing on idle. * * @defaultValue true */ readonly taskStealing?: boolean /** - * Whether to enable tasks stealing on back pressure. + * 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 } /** @@ -179,7 +198,7 @@ export interface PoolOptions { */ restartWorkerOnError?: boolean /** - * Pool events emission. + * Pool events integrated with async resource emission. * * @defaultValue true */ @@ -194,6 +213,24 @@ export interface PoolOptions { * 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 } /** @@ -219,39 +256,33 @@ export interface IPool< */ 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. + * Pool event emitter integrated with async resource. + * The async tracking tooling identifier is `poolifier:--pool`. * * Events that can currently be listened to: * - * - `'ready'`: Emitted when the number of workers created in the pool has reached the minimum size expected and are ready. + * - `'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 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. + * @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. */ readonly execute: ( data?: Data, name?: string, - transferList?: TransferListItem[] + transferList?: readonly TransferListItem[] ) => Promise /** * Starts the minimum number of workers in this pool. @@ -273,12 +304,14 @@ export interface IPool< * If a task function with the same name already exists, it will be overwritten. * * @param name - The name of the task function. - * @param taskFunction - 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, - taskFunction: TaskFunction + fn: TaskFunction ) => Promise /** * Removes a task function from this pool.