X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=src%2Fpools%2Fpool.ts;h=c2d5498753c61a385fa43bb2a68163b305ad03a2;hb=260bb73734384fc982006e15359ca1c43463cc55;hp=f6f3de36fe13ae6efced690a8637c431c4405a1d;hpb=ea4b5fd037c5fe09eb6a2810332ad6bed1b5bc7f;p=poolifier.git

diff --git a/src/pools/pool.ts b/src/pools/pool.ts
index f6f3de36..c2d54987 100644
--- a/src/pools/pool.ts
+++ b/src/pools/pool.ts
@@ -2,10 +2,14 @@ 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 { TaskFunctionProperties } from '../utility-types.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,
@@ -14,13 +18,16 @@ import type {
   IWorkerNode,
   MessageHandler,
   OnlineHandler,
-  WorkerType
+  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.
    */
@@ -28,7 +35,7 @@ export const PoolTypes = Object.freeze({
   /**
    * Dynamic pool type.
    */
-  dynamic: 'dynamic'
+  dynamic: 'dynamic',
 } as const)
 
 /**
@@ -39,7 +46,16 @@ export type PoolType = keyof typeof PoolTypes
 /**
  * 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',
@@ -47,7 +63,7 @@ export const PoolEvents = Object.freeze({
   destroy: 'destroy',
   error: 'error',
   taskError: 'taskError',
-  backPressure: 'backPressure'
+  backPressure: 'backPressure',
 } as const)
 
 /**
@@ -64,7 +80,7 @@ export interface PoolInfo {
   readonly worker: WorkerType
   readonly started: boolean
   readonly ready: boolean
-  readonly strategy: WorkerChoiceStrategy
+  readonly defaultStrategy: WorkerChoiceStrategy
   readonly strategyRetries: number
   readonly minSize: number
   readonly maxSize: number
@@ -97,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
+    }
+  }
 }
 
 /**
@@ -105,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
@@ -137,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 worker choice strategy to use in this pool.
-   *
+   * The default worker choice strategy to use in this pool.
    * @defaultValue WorkerChoiceStrategies.ROUND_ROBIN
    */
   workerChoiceStrategy?: WorkerChoiceStrategy
@@ -187,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
@@ -203,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
@@ -223,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.
@@ -239,12 +255,11 @@ export interface IPool<
   readonly info: PoolInfo
   /**
    * Pool worker nodes.
-   *
    * @internal
    */
-  readonly workerNodes: Array<IWorkerNode<Worker, Data>>
+  readonly workerNodes: IWorkerNode<Worker, Data>[]
   /**
-   * Event emitter integrated with async resource on which events can be listened to.
+   * Pool event emitter integrated with async resource.
    * The async tracking tooling identifier is `poolifier:<PoolType>-<WorkerType>-pool`.
    *
    * Events that can currently be listened to:
@@ -261,7 +276,6 @@ 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.
@@ -270,7 +284,7 @@ export interface IPool<
   readonly execute: (
     data?: Data,
     name?: string,
-    transferList?: TransferListItem[]
+    transferList?: readonly TransferListItem[]
   ) => Promise<Response>
   /**
    * Starts the minimum number of workers in this pool.
@@ -282,7 +296,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.
    */
@@ -290,41 +303,36 @@ 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 names of task function available in this pool.
-   *
-   * @returns The names of task function available in this pool.
+   * Lists the properties of task functions available in this pool.
+   * @returns The properties of task functions available in this pool.
    */
-  readonly listTaskFunctionNames: () => string[]
+  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 worker choice strategy in this pool.
-   *
-   * @param workerChoiceStrategy - The worker choice strategy.
+   * Sets the default worker choice strategy in this pool.
+   * @param workerChoiceStrategy - The default worker choice strategy.
    * @param workerChoiceStrategyOptions - The worker choice strategy options.
    */
   readonly setWorkerChoiceStrategy: (
@@ -333,15 +341,14 @@ 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.
    */
   readonly setWorkerChoiceStrategyOptions: (
     workerChoiceStrategyOptions: WorkerChoiceStrategyOptions
-  ) => void
+  ) => 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.
    */
@@ -351,7 +358,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