X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=src%2Fpools%2Fpool.ts;h=0df7549ace8ba8589e69fae51b3e9fd4d237736f;hb=8b7aa4204c27efd1dc699f7baea65b5262bd26b3;hp=ccb4b5b94ef858ad00c0eb5a28c490651854489e;hpb=75f30e744551af87736f998db9ad02be7206e89e;p=poolifier.git

diff --git a/src/pools/pool.ts b/src/pools/pool.ts
index ccb4b5b9..0df7549a 100644
--- a/src/pools/pool.ts
+++ b/src/pools/pool.ts
@@ -3,10 +3,13 @@ import type { EventEmitterAsyncResource } from 'node:events'
 import type { TransferListItem, WorkerOptions } from 'node:worker_threads'
 
 import type { TaskFunctionProperties } from '../utility-types.js'
-import type { TaskFunction } from '../worker/task-functions.js'
+import type {
+  TaskFunction,
+  TaskFunctionObject,
+} from '../worker/task-functions.js'
 import type {
   WorkerChoiceStrategy,
-  WorkerChoiceStrategyOptions
+  WorkerChoiceStrategyOptions,
 } from './selection-strategies/selection-strategies-types.js'
 import type {
   ErrorHandler,
@@ -15,7 +18,7 @@ import type {
   IWorkerNode,
   MessageHandler,
   OnlineHandler,
-  WorkerType
+  WorkerType,
 } from './worker.js'
 
 /**
@@ -32,7 +35,7 @@ export const PoolTypes: Readonly<{
   /**
    * Dynamic pool type.
    */
-  dynamic: 'dynamic'
+  dynamic: 'dynamic',
 } as const)
 
 /**
@@ -60,7 +63,7 @@ export const PoolEvents: Readonly<{
   destroy: 'destroy',
   error: 'error',
   taskError: 'taskError',
-  backPressure: 'backPressure'
+  backPressure: 'backPressure',
 } as const)
 
 /**
@@ -110,6 +113,24 @@ export interface PoolInfo {
     readonly average?: number
     readonly median?: number
   }
+  readonly elu?: {
+    idle: {
+      readonly minimum: number
+      readonly maximum: number
+      readonly average?: number
+      readonly median?: number
+    }
+    active: {
+      readonly minimum: number
+      readonly maximum: number
+      readonly average?: number
+      readonly median?: number
+    }
+    utilization: {
+      readonly average?: number
+      readonly median?: number
+    }
+  }
 }
 
 /**
@@ -118,31 +139,26 @@ export interface PoolInfo {
 export interface TasksQueueOptions {
   /**
    * 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
+   * @defaultValue false
    */
   readonly tasksStealingOnBackPressure?: boolean
   /**
    * Queued tasks finished timeout in milliseconds at worker node termination.
-   *
    * @defaultValue 2000
    */
   readonly tasksFinishedTimeout?: number
@@ -150,43 +166,36 @@ export interface TasksQueueOptions {
 
 /**
  * Options for a poolifier pool.
- *
  * @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 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 default worker choice strategy to use in this pool.
-   *
    * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
    */
   workerChoiceStrategy?: WorkerChoiceStrategy
@@ -200,13 +209,11 @@ export interface PoolOptions<Worker extends IWorker> {
   restartWorkerOnError?: boolean
   /**
    * Pool events integrated with async resource emission.
-   *
    * @defaultValue true
    */
   enableEvents?: boolean
   /**
    * Pool worker node tasks queue.
-   *
    * @defaultValue false
    */
   enableTasksQueue?: boolean
@@ -216,19 +223,16 @@ export interface PoolOptions<Worker extends IWorker> {
   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<string, unknown>
   /**
    * Cluster settings.
-   *
    * @see https://nodejs.org/api/cluster.html#cluster_cluster_settings
    */
   settings?: ClusterSettings
@@ -236,7 +240,6 @@ export interface PoolOptions<Worker extends IWorker> {
 
 /**
  * Contract definition for a poolifier pool.
- *
  * @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.
@@ -252,10 +255,9 @@ export interface IPool<
   readonly info: PoolInfo
   /**
    * Pool worker nodes.
-   *
    * @internal
    */
-  readonly workerNodes: Array<IWorkerNode<Worker, Data>>
+  readonly workerNodes: IWorkerNode<Worker, Data>[]
   /**
    * Pool event emitter integrated with async resource.
    * The async tracking tooling identifier is `poolifier:<PoolType>-<WorkerType>-pool`.
@@ -274,17 +276,28 @@ export interface IPool<
   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 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.
+   * @returns Promise with a task function response that will be fulfilled when the task is completed.
    */
   readonly execute: (
     data?: Data,
     name?: string,
     transferList?: readonly TransferListItem[]
   ) => Promise<Response>
+  /**
+   * Executes the specified function in the worker constructor with the tasks data iterable input parameter.
+   * @param data - The tasks iterable input data for the specified task function. This can only be an iterable of 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 with an array of task function responses that will be fulfilled when the tasks are completed.
+   */
+  readonly mapExecute: (
+    data: Iterable<Data>,
+    name?: string,
+    transferList?: readonly TransferListItem[]
+  ) => Promise<Response[]>
   /**
    * Starts the minimum number of workers in this pool.
    */
@@ -295,7 +308,6 @@ export interface IPool<
   readonly destroy: () => Promise<void>
   /**
    * 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.
    */
@@ -303,40 +315,35 @@ export interface IPool<
   /**
    * 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.
+   * @throws {@link https://nodejs.org/api/errors.html#class-typeerror} If the `fn` parameter is not a function or task function object.
    */
   readonly addTaskFunction: (
     name: string,
-    fn: TaskFunction<Data, Response>
+    fn: TaskFunction<Data, Response> | TaskFunctionObject<Data, Response>
   ) => Promise<boolean>
   /**
    * 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<boolean>
   /**
    * Lists the properties of task functions available in this pool.
-   *
    * @returns The properties of task functions available in this pool.
    */
   readonly listTaskFunctionsProperties: () => TaskFunctionProperties[]
   /**
    * 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.
    */
   readonly setDefaultTaskFunction: (name: string) => Promise<boolean>
   /**
    * Sets the default worker choice strategy in this pool.
-   *
    * @param workerChoiceStrategy - The default worker choice strategy.
    * @param workerChoiceStrategyOptions - The worker choice strategy options.
    */
@@ -346,7 +353,6 @@ export interface IPool<
   ) => void
   /**
    * Sets the worker choice strategy options in this pool.
-   *
    * @param workerChoiceStrategyOptions - The worker choice strategy options.
    * @returns `true` if the worker choice strategy options were set, `false` otherwise.
    */
@@ -355,7 +361,6 @@ export interface IPool<
   ) => boolean
   /**
    * Enables/disables the worker node tasks queue in this pool.
-   *
    * @param enable - Whether to enable or disable the worker node tasks queue.
    * @param tasksQueueOptions - The worker node tasks queue options.
    */
@@ -365,7 +370,6 @@ export interface IPool<
   ) => void
   /**
    * Sets the worker node tasks queue options in this pool.
-   *
    * @param tasksQueueOptions - The worker node tasks queue options.
    */
   readonly setTasksQueueOptions: (tasksQueueOptions: TasksQueueOptions) => void