Merge dependabot/npm_and_yarn/examples/typescript/websocket-server-pool/ws-worker_thr...
[poolifier.git] / docs / api.md
CommitLineData
a47027a0
JB
1# [API](https://poolifier.github.io/poolifier/)
2
3## Table of contents
4
5- [Pool](#pool)
6 - [`pool = new FixedThreadPool/FixedClusterPool(numberOfThreads/numberOfWorkers, filePath, opts)`](#pool--new-fixedthreadpoolfixedclusterpoolnumberofthreadsnumberofworkers-filepath-opts)
7 - [`pool = new DynamicThreadPool/DynamicClusterPool(min, max, filePath, opts)`](#pool--new-dynamicthreadpooldynamicclusterpoolmin-max-filepath-opts)
7d91a8cd 8 - [`pool.execute(data, name, transferList)`](#poolexecutedata-name-transferlist)
47352846 9 - [`pool.start()`](#poolstart)
a47027a0 10 - [`pool.destroy()`](#pooldestroy)
9eae3c69
JB
11 - [`pool.hasTaskFunction(name)`](#poolhastaskfunctionname)
12 - [`pool.addTaskFunction(name, fn)`](#pooladdtaskfunctionname-fn)
13 - [`pool.removeTaskFunction(name)`](#poolremovetaskfunctionname)
6703b9f4 14 - [`pool.listTaskFunctionNames()`](#poollisttaskfunctionnames)
9eae3c69 15 - [`pool.setDefaultTaskFunction(name)`](#poolsetdefaulttaskfunctionname)
a47027a0
JB
16 - [`PoolOptions`](#pooloptions)
17 - [`ThreadPoolOptions extends PoolOptions`](#threadpooloptions-extends-pooloptions)
18 - [`ClusterPoolOptions extends PoolOptions`](#clusterpooloptions-extends-pooloptions)
19- [Worker](#worker)
20 - [`class YourWorker extends ThreadWorker/ClusterWorker`](#class-yourworker-extends-threadworkerclusterworker)
21 - [`YourWorker.hasTaskFunction(name)`](#yourworkerhastaskfunctionname)
22 - [`YourWorker.addTaskFunction(name, fn)`](#yourworkeraddtaskfunctionname-fn)
23 - [`YourWorker.removeTaskFunction(name)`](#yourworkerremovetaskfunctionname)
6703b9f4 24 - [`YourWorker.listTaskFunctionNames()`](#yourworkerlisttaskfunctionnames)
a47027a0
JB
25 - [`YourWorker.setDefaultTaskFunction(name)`](#yourworkersetdefaulttaskfunctionname)
26
27## Pool
28
29### `pool = new FixedThreadPool/FixedClusterPool(numberOfThreads/numberOfWorkers, filePath, opts)`
30
8c445a4e
JB
31`numberOfThreads/numberOfWorkers` (mandatory) Number of workers for this pool.
32`filePath` (mandatory) Path to a file with a worker implementation.
33`opts` (optional) An object with the pool options properties described below.
a47027a0
JB
34
35### `pool = new DynamicThreadPool/DynamicClusterPool(min, max, filePath, opts)`
36
8c445a4e 37`min` (mandatory) Same as _FixedThreadPool_/_FixedClusterPool_ numberOfThreads/numberOfWorkers, this number of workers will be always active.
a36b9e1f 38`max` (mandatory) Max number of workers that this pool can contain, the newly created workers will die after a threshold (default is 1 minute, you can override it in your worker implementation).
8c445a4e
JB
39`filePath` (mandatory) Path to a file with a worker implementation.
40`opts` (optional) An object with the pool options properties described below.
a47027a0 41
7d91a8cd 42### `pool.execute(data, name, transferList)`
a47027a0 43
8c445a4e 44`data` (optional) An object that you want to pass to your worker implementation.
637100d9 45`name` (optional) A string with the task function name that you want to execute on the worker. Default: `'default'`
679e657a 46`transferList` (optional) An array of transferable objects that you want to transfer to your [worker_threads](https://nodejs.org/api/worker_threads.html) worker implementation.
a47027a0
JB
47
48This method is available on both pool implementations and returns a promise with the task function execution response.
49
47352846
JB
50### `pool.start()`
51
52This method is available on both pool implementations and will start the minimum number of workers.
53
a47027a0
JB
54### `pool.destroy()`
55
56This method is available on both pool implementations and will call the terminate method on each worker.
57
30500265
JB
58### `pool.hasTaskFunction(name)`
59
679e657a 60`name` (mandatory) The task function name.
30500265
JB
61
62This method is available on both pool implementations and returns a boolean.
63
9eae3c69
JB
64### `pool.addTaskFunction(name, fn)`
65
66`name` (mandatory) The task function name.
67`fn` (mandatory) The task function.
68
69This method is available on both pool implementations and returns a boolean promise.
70
71### `pool.removeTaskFunction(name)`
72
73`name` (mandatory) The task function name.
74
75This method is available on both pool implementations and returns a boolean promise.
76
6703b9f4 77### `pool.listTaskFunctionNames()`
90d7d101
JB
78
79This method is available on both pool implementations and returns an array of the task function names.
80
9eae3c69
JB
81### `pool.setDefaultTaskFunction(name)`
82
83`name` (mandatory) The task function name.
84
85This method is available on both pool implementations and returns a boolean promise.
86
a47027a0
JB
87### `PoolOptions`
88
89An object with these properties:
90
d293923f
JB
91- `onlineHandler` (optional) - A function that will listen for online event on each worker.
92 Default: `() => {}`
93- `messageHandler` (optional) - A function that will listen for message event on each worker.
94 Default: `() => {}`
95- `errorHandler` (optional) - A function that will listen for error event on each worker.
96 Default: `() => {}`
97- `exitHandler` (optional) - A function that will listen for exit event on each worker.
98 Default: `() => {}`
99
a47027a0
JB
100- `workerChoiceStrategy` (optional) - The worker choice strategy to use in this pool:
101
102 - `WorkerChoiceStrategies.ROUND_ROBIN`: Submit tasks to worker in a round robin fashion
103 - `WorkerChoiceStrategies.LEAST_USED`: Submit tasks to the worker with the minimum number of executed, executing and queued tasks
104 - `WorkerChoiceStrategies.LEAST_BUSY`: Submit tasks to the worker with the minimum tasks total execution and wait time
a71b05bc 105 - `WorkerChoiceStrategies.LEAST_ELU`: Submit tasks to the worker with the minimum event loop utilization (ELU)
2904fcdb 106 - `WorkerChoiceStrategies.WEIGHTED_ROUND_ROBIN`: Submit tasks to worker by using a [weighted round robin scheduling algorithm](./worker-choice-strategies.md#weighted-round-robin) based on tasks execution time
bde1a004 107 - `WorkerChoiceStrategies.INTERLEAVED_WEIGHTED_ROUND_ROBIN`: Submit tasks to worker by using an [interleaved weighted round robin scheduling algorithm](./worker-choice-strategies.md#interleaved-weighted-round-robin-experimental) based on tasks execution time (experimental)
2904fcdb 108 - `WorkerChoiceStrategies.FAIR_SHARE`: Submit tasks to worker by using a [fair share scheduling algorithm](./worker-choice-strategies.md#fair-share) based on tasks execution time (the default) or ELU active time
a47027a0
JB
109
110 `WorkerChoiceStrategies.WEIGHTED_ROUND_ROBIN`, `WorkerChoiceStrategies.INTERLEAVED_WEIGHTED_ROUND_ROBIN` and `WorkerChoiceStrategies.FAIR_SHARE` strategies are targeted to heavy and long tasks.
111 Default: `WorkerChoiceStrategies.ROUND_ROBIN`
112
113- `workerChoiceStrategyOptions` (optional) - The worker choice strategy options object to use in this pool.
114 Properties:
115
8c0b113f 116 - `retries` (optional) - The number of retries to perform if no worker is eligible.
a47027a0 117 - `measurement` (optional) - The measurement to use in worker choice strategies: `runTime`, `waitTime` or `elu`.
06916f85
JB
118 - `runTime` (optional) - Use the tasks [simple moving median](./worker-choice-strategies.md#simple-moving-median) runtime instead of the tasks simple moving average runtime in worker choice strategies.
119 - `waitTime` (optional) - Use the tasks [simple moving median](./worker-choice-strategies.md#simple-moving-median) wait time instead of the tasks simple moving average wait time in worker choice strategies.
120 - `elu` (optional) - Use the tasks [simple moving median](./worker-choice-strategies.md#simple-moving-median) ELU instead of the tasks simple moving average ELU in worker choice strategies.
a47027a0
JB
121 - `weights` (optional) - The worker weights to use in weighted round robin worker choice strategies: `{ 0: 200, 1: 300, ..., n: 100 }`.
122
8c0b113f 123 Default: `{ retries: 6, runTime: { median: false }, waitTime: { median: false }, elu: { median: false } }`
a47027a0 124
ce0ab2d7 125- `startWorkers` (optional) - Start the minimum number of workers at pool initialization.
d293923f 126 Default: `true`
a47027a0
JB
127- `restartWorkerOnError` (optional) - Restart worker on uncaught error in this pool.
128 Default: `true`
b5604034 129- `enableEvents` (optional) - Events integrated with async resource emission enablement in this pool.
a47027a0
JB
130 Default: `true`
131- `enableTasksQueue` (optional) - Tasks queue per worker enablement in this pool.
132 Default: `false`
133
134- `tasksQueueOptions` (optional) - The worker tasks queue options object to use in this pool.
135 Properties:
136
fa3cc835 137 - `size` (optional) - The maximum number of tasks that can be queued on a worker before flagging it as back pressured. It must be a positive integer.
5137e2ae 138 - `concurrency` (optional) - The maximum number of tasks that can be executed concurrently on a worker. It must be a positive integer.
af98b972
JB
139 - `taskStealing` (optional) - Task stealing enablement on empty queue.
140 - `tasksStealingOnBackPressure` (optional) - Tasks stealing enablement under back pressure.
445264e8 141
dbd73092 142 Default: `{ size: (pool maximum size)^2, concurrency: 1, taskStealing: true, tasksStealingOnBackPressure: true }`
a47027a0
JB
143
144#### `ThreadPoolOptions extends PoolOptions`
145
146- `workerOptions` (optional) - An object with the worker options to pass to worker. See [worker_threads](https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options) for more details.
147
148#### `ClusterPoolOptions extends PoolOptions`
149
150- `env` (optional) - An object with the environment variables to pass to worker. See [cluster](https://nodejs.org/api/cluster.html#cluster_cluster_fork_env) for more details.
151
152- `settings` (optional) - An object with the cluster settings. See [cluster](https://nodejs.org/api/cluster.html#cluster_cluster_settings) for more details.
153
154## Worker
155
156### `class YourWorker extends ThreadWorker/ClusterWorker`
157
8c445a4e 158`taskFunctions` (mandatory) The task function or task functions object `{ name_1: fn_1, ..., name_n: fn_n }` that you want to execute on the worker.
a47027a0
JB
159`opts` (optional) An object with these properties:
160
968dbbe7
JB
161- `killBehavior` (optional) - Dictates if your worker will be deleted in case a task is active on it.
162 **KillBehaviors.SOFT**: If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still executing or queued, then the worker **won't** be deleted.
163 **KillBehaviors.HARD**: If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still executing or queued, then the worker will be deleted.
164 This option only apply to the newly created workers.
165 Default: `KillBehaviors.SOFT`
166
c20084b6 167- `maxInactiveTime` (optional) - Maximum waiting time in milliseconds for tasks on newly created workers. After this time newly created workers will die. It must be a positive integer greater or equal than 5.
a47027a0
JB
168 The last active time of your worker will be updated when it terminates a task.
169 If `killBehavior` is set to `KillBehaviors.HARD` this value represents also the timeout for the tasks that you submit to the pool, when this timeout expires your tasks is interrupted before completion and removed. The worker is killed if is not part of the minimum size of the pool.
170 If `killBehavior` is set to `KillBehaviors.SOFT` your tasks have no timeout and your workers will not be terminated until your task is completed.
171 Default: `60000`
172
968dbbe7
JB
173- `killHandler` (optional) - A function that will be called when a worker is killed.
174 Default: `() => {}`
a47027a0
JB
175
176#### `YourWorker.hasTaskFunction(name)`
177
8c445a4e 178`name` (mandatory) The task function name.
a47027a0 179
30500265 180This method is available on both worker implementations and returns `{ status: boolean, error?: Error }`.
a47027a0
JB
181
182#### `YourWorker.addTaskFunction(name, fn)`
183
8c445a4e
JB
184`name` (mandatory) The task function name.
185`fn` (mandatory) The task function.
a47027a0 186
30500265 187This method is available on both worker implementations and returns `{ status: boolean, error?: Error }`.
a47027a0
JB
188
189#### `YourWorker.removeTaskFunction(name)`
190
8c445a4e 191`name` (mandatory) The task function name.
a47027a0 192
30500265 193This method is available on both worker implementations and returns `{ status: boolean, error?: Error }`.
a47027a0 194
6703b9f4 195#### `YourWorker.listTaskFunctionNames()`
a47027a0
JB
196
197This method is available on both worker implementations and returns an array of the task function names.
198
199#### `YourWorker.setDefaultTaskFunction(name)`
200
8c445a4e 201`name` (mandatory) The task function name.
a47027a0 202
30500265 203This method is available on both worker implementations and returns `{ status: boolean, error?: Error }`.