X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=src%2Fpools%2Fpool.ts;h=711a71bedb25205bef8b1fdbdaf4528866e92879;hb=37b32d84b2a0d8f8addad8c5e6a306c7dd22d58d;hp=1a05f633250adb8e88c72a63cda565c3265205bc;hpb=6b83e544b1827a8a04898c3032dab73fe19687e6;p=poolifier.git

diff --git a/src/pools/pool.ts b/src/pools/pool.ts
index 1a05f633..711a71be 100644
--- a/src/pools/pool.ts
+++ b/src/pools/pool.ts
@@ -42,11 +42,13 @@ export class PoolEmitter extends EventEmitter {}
  * Enumeration of pool events.
  */
 export const PoolEvents = Object.freeze({
-  full: 'full',
   ready: 'ready',
   busy: 'busy',
+  full: 'full',
+  destroy: 'destroy',
   error: 'error',
-  taskError: 'taskError'
+  taskError: 'taskError',
+  backPressure: 'backPressure'
 } as const)
 
 /**
@@ -61,6 +63,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
@@ -77,31 +80,51 @@ export interface PoolInfo {
   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 average?: number
     readonly median?: number
   }
   readonly waitTime?: {
     readonly minimum: number
     readonly maximum: number
-    readonly average: 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.
+   *
+   * @defaultValue true
+   */
+  readonly taskStealing?: boolean
+  /**
+   * Whether to enable tasks stealing on back pressure.
+   *
+   * @defaultValue true
+   */
+  readonly tasksStealingOnBackPressure?: boolean
 }
 
 /**
@@ -110,22 +133,36 @@ export interface TasksQueueOptions {
  * @typeParam Worker - Type of worker.
  */
 export interface PoolOptions<Worker extends IWorker> {
+  /**
+   * A function that will listen for online event on each worker.
+   *
+   * @defaultValue `() => {}`
+   */
+  onlineHandler?: OnlineHandler<Worker>
   /**
    * A function that will listen for message event on each worker.
+   *
+   * @defaultValue `() => {}`
    */
   messageHandler?: MessageHandler<Worker>
   /**
    * A function that will listen for error event on each worker.
+   *
+   * @defaultValue `() => {}`
    */
   errorHandler?: ErrorHandler<Worker>
-  /**
-   * A function that will listen for online event on each worker.
-   */
-  onlineHandler?: OnlineHandler<Worker>
   /**
    * A function that will listen for exit event on each worker.
+   *
+   * @defaultValue `() => {}`
    */
   exitHandler?: ExitHandler<Worker>
+  /**
+   * Whether to start the minimum number of workers at pool initialization.
+   *
+   * @defaultValue true
+   */
+  startWorkers?: boolean
   /**
    * The worker choice strategy to use in this pool.
    *
@@ -147,13 +184,13 @@ export interface PoolOptions<Worker extends IWorker> {
    */
   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
 }
@@ -176,18 +213,30 @@ export interface IPool<
   readonly info: PoolInfo
   /**
    * Pool worker nodes.
+   *
+   * @internal
    */
   readonly workerNodes: Array<IWorkerNode<Worker, Data>>
+  /**
+   * 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.
    *
    * Events that can currently be listened to:
    *
-   * - `'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 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.
+   * - `'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.
+   * - `'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
   /**
@@ -203,10 +252,20 @@ export interface IPool<
     name?: string,
     transferList?: TransferListItem[]
   ) => Promise<Response>
+  /**
+   * Starts the minimum number of workers in this pool.
+   */
+  readonly start: () => void
   /**
    * Terminates all workers in this pool.
    */
   readonly destroy: () => Promise<void>
+  /**
+   * Lists the names of task function available in this pool.
+   *
+   * @returns The names of task function available in this pool.
+   */
+  readonly listTaskFunctions: () => string[]
   /**
    * Sets the worker choice strategy in this pool.
    *
@@ -226,19 +285,19 @@ export interface IPool<
     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.
    */
   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.
    */
   readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void
 }