X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=src%2Fpools%2Fpool.ts;h=b1b504d59b22bba2aca61becc898fa87167c5c6c;hb=563d12ded5ff23152ed70f6dc675f01eb7cd9ee5;hp=6156a0421170e6baa8ad7c2071b755da554a03ed;hpb=6703b9f4492e347500111c42ffddbd8341c8f262;p=poolifier.git diff --git a/src/pools/pool.ts b/src/pools/pool.ts index 6156a042..b1b504d5 100644 --- a/src/pools/pool.ts +++ b/src/pools/pool.ts @@ -1,5 +1,5 @@ -import { EventEmitter } from 'node:events' -import { type TransferListItem } from 'node:worker_threads' +import type { TransferListItem } from 'node:worker_threads' +import type { EventEmitterAsyncResource } from 'node:events' import type { TaskFunction } from '../worker/task-functions' import type { ErrorHandler, @@ -34,11 +34,6 @@ export const PoolTypes = Object.freeze({ */ export type PoolType = keyof typeof PoolTypes -/** - * Pool events emitter. - */ -export class PoolEmitter extends EventEmitter {} - /** * Enumeration of pool events. */ @@ -64,6 +59,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 @@ -107,16 +103,24 @@ export interface TasksQueueOptions { * @defaultValue (pool maximum size)^2 */ readonly size?: number - /** - * @deprecated Use `size` instead. - */ - readonly queueMaxSize?: 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 } /** @@ -127,20 +131,34 @@ export interface TasksQueueOptions { 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 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. * @@ -156,7 +174,7 @@ export interface PoolOptions { */ restartWorkerOnError?: boolean /** - * Pool events emission. + * Pool events integrated with async resource emission. * * @defaultValue true */ @@ -204,7 +222,8 @@ export interface IPool< */ readonly hasWorkerNodeBackPressure: (workerNodeKey: number) => boolean /** - * Emitter on which events can be listened to. + * Event emitter integrated with async resource on which events can be listened to. + * The async tracking tooling identifier is `poolifier:--pool`. * * Events that can currently be listened to: * @@ -216,13 +235,13 @@ export interface IPool< * - `'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: ( @@ -230,6 +249,10 @@ 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. */ @@ -246,20 +269,22 @@ 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 - ) => boolean + 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) => boolean + readonly removeTaskFunction: (name: string) => Promise /** * Lists the names of task function available in this pool. * @@ -272,7 +297,7 @@ export interface IPool< * @param name - The name of the task function. * @returns `true` if the default task function was set, `false` otherwise. */ - readonly setDefaultTaskFunction: (name: string) => boolean + readonly setDefaultTaskFunction: (name: string) => Promise /** * Sets the worker choice strategy in this pool. *