Removed max tasks (#225)
[poolifier.git] / README.md
CommitLineData
f2b5671a 1<div align="center">
eea03e6e 2<img src="./docs/logo.png" width="340px" height="266px"/>
ddaa3a76 3</div>
4
063f8c5b 5<h2 align="center">Node Thread Pool and Cluster Pool :arrow_double_up: :on:</h2>
1d4f79e7
APA
6
7<p align="center">
8 <a href="https://www.npmjs.com/package/poolifier">
9 <img alt="Weekly Downloads" src="https://img.shields.io/npm/dw/poolifier"></a>
10 <a href="https://github.com/pioardi/node-pool/actions">
11 <img alt="Actions Status" src="https://github.com/pioardi/node-pool/workflows/NodeCI/badge.svg"></a>
12 <a href="https://sonarcloud.io/dashboard?id=pioardi_poolifier">
13 <img alt="Quality Gate Status" src="https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=alert_status"></a>
14 <a href="https://sonarcloud.io/component_measures/metric/coverage/list?id=pioardi_poolifier">
15 <img alt="Code coverage" src="https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=coverage"></a>
16 <a href="https://standardjs.com">
17 <img alt="Javascript Standard Style Guide" src="https://img.shields.io/badge/code_style-standard-brightgreen.svg"></a>
18 <a href="https://gitter.im/poolifier/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge">
19 <img alt="Gitter chat" src="https://badges.gitter.im/poolifier/community.svg"></a>
20 <a href="https://badgen.net/dependabot/dependabot/dependabot-core/?icon=dependabot">
21 <img alt="Dependabot" src="https://badgen.net/dependabot/dependabot/dependabot-core/?icon=dependabot"></a>
22 <a href="http://makeapullrequest.com">
23 <img alt="PR Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square"></a>
24 <a href="https://img.shields.io/static/v1?label=dependencies&message=no%20dependencies&color=brightgreen">
25 <img alt="No dependencies" src="https://img.shields.io/static/v1?label=dependencies&message=no%20dependencies&color=brightgreen"></a>
1d4f79e7
APA
26</p>
27
50aa7901 28## Why Poolifier?
e76f5485 29
c868b39b 30Poolifier is used to perform CPU intensive and I/O intensive tasks on nodejs servers, it implements worker pools (yes, more worker pool implementations, so you can choose which one fit better for you) using [worker-threads](https://nodejs.org/api/worker_threads.html#worker_threads_worker_threads) and cluster pools using [Node.js cluster](https://nodejs.org/api/cluster.html) modules.
50aa7901 31With poolifier you can improve your **performance** and resolve problems related to the event loop.
063f8c5b 32Moreover you can execute your tasks using an API designed to improve the **developer experience**.
33Please consult our guidelines to <a href="#choose-your-pool">choose your pool</a>
e76f5485 34
64060857 35- Performance :racehorse: [benchmarks](./benchmarks/README.md)
f2b5671a 36- Security :bank: :cop: [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=security_rating)](https://sonarcloud.io/dashboard?id=pioardi_poolifier) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
b1b24f66 37- Easy to use :couple:
38553e6e 38- Easy switch from a pool to another, easy to tune :heavy_check_mark:
39- Dynamic pool size :heavy_check_mark:
d28c7996 40- No runtime dependencies :heavy_check_mark:
38553e6e 41- Proper async integration with node async hooks :heavy_check_mark:
42- Support for worker threads and cluster node modules :heavy_check_mark:
38553e6e 43- Support sync and async tasks :heavy_check_mark:
44- General guidance on pools to use :heavy_check_mark:
45- Widely tested :heavy_check_mark:
46- Error handling out of the box :heavy_check_mark:
ed93dc74 47- Active community :heavy_check_mark:
5fd75a2e 48- Code quality :octocat: [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=bugs)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
d28c7996
JB
49 [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=code_smells)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
50 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
51 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
52 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
53 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=sqale_index)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
ddaa3a76 54
50aa7901 55## Contents
e76f5485 56
34a572eb 57<h3 align="center">
50aa7901
S
58 <a href="#overview">Overview</a>
59 <span> · </span>
34a572eb 60 <a href="#installation">Installation</a>
61 <span> · </span>
62 <a href="#usage">Usage</a>
63 <span> · </span>
50aa7901
S
64 <a href="#node-versions"> Node versions</a>
65 <span> · </span>
34a572eb 66 <a href="#api">API</a>
67 <span> · </span>
50aa7901 68 <a href="#choose-your-pool">Choose your pool</a>
48211d04 69 <span> · </span>
34a572eb 70 <a href="#contribute">Contribute</a>
71 <span> · </span>
50aa7901 72 <a href="#team">Team</a>
34a572eb 73 <span> · </span>
74 <a href="#license">License</a>
75</h3>
76
50aa7901 77## Overview
13031992 78
31b90205
JB
79Node pool contains two [worker-threads](https://nodejs.org/api/worker_threads.html#worker_threads_worker_threads)/[cluster worker](https://nodejs.org/api/cluster.html#cluster_class_worker) pool implementations, you don't have to deal with worker-threads/cluster worker complexity.
80The first implementation is a static worker pool, with a defined number of workers that are started at creation time and will be reused.
81The second implementation is a dynamic worker pool with a number of worker started at creation time (these workers will be always active and reused) and other workers created when the load will increase (with an upper limit, these workers will be reused when active), the new created workers will be stopped after a configurable period of inactivity.
82You have to implement your worker extending the ThreadWorker or ClusterWorker class
50aa7901
S
83
84## Installation
85
86```shell
27c5fb75 87npm install poolifier --save
1a4ec243 88```
1a4ec243 89
50aa7901
S
90## Usage
91
31b90205 92You can implement a worker-threads worker in a simple way by extending the class ThreadWorker:
1a4ec243
APA
93
94```js
95'use strict'
d2eb4964 96const { ThreadWorker } = require('poolifier')
1a4ec243 97
deb85c12 98function yourFunction (data) {
106744f7 99 // this will be executed in the worker thread,
100 // the data will be received by using the execute method
101 return { ok: 1 }
102}
103
50aa7901
S
104module.exports = new ThreadWorker(yourFunction, {
105 maxInactiveTime: 60000,
106 async: false
107})
1a4ec243
APA
108```
109
1f9a5a44 110Instantiate your pool based on your needed :
1a4ec243
APA
111
112```js
113'use strict'
d2eb4964 114const { FixedThreadPool, DynamicThreadPool } = require('poolifier')
1a4ec243 115
31b90205 116// a fixed worker-threads pool
1a4ec243 117const pool = new FixedThreadPool(15,
106744f7 118 './yourWorker.js',
119 { errorHandler: (e) => console.error(e), onlineHandler: () => console.log('worker is online') })
1a4ec243 120
31b90205 121// or a dynamic worker-threads pool
1a4ec243 122const pool = new DynamicThreadPool(10, 100,
106744f7 123 './yourWorker.js',
124 { errorHandler: (e) => console.error(e), onlineHandler: () => console.log('worker is online') })
125
1a4ec243
APA
126pool.emitter.on('FullPool', () => console.log('Pool is full'))
127
128// the execute method signature is the same for both implementations,
129// so you can easy switch from one to another
130pool.execute({}).then(res => {
131 console.log(res)
777b7824 132}).catch ....
1a4ec243
APA
133
134```
135
17a9a094 136You can do the same with the classes ClusterWorker, FixedClusterPool and DynamicClusterPool.
31b90205 137
17a9a094
JB
138**See examples folder for more details (in particular if you want to use a pool for [multiple functions](./examples/multiFunctionExample.js)).**
139**Now TypeScript is also supported, find how to use it into the example folder**.
1a4ec243 140
ec2ccfc8 141Remember that workers can only send and receive serializable data.
deb85c12 142
50aa7901 143## Node versions
34a572eb 144
50aa7901 145You can use node versions 12.x, 13.x, 14.x
1a4ec243 146
50aa7901 147## API
34a572eb 148
31b90205 149### `pool = new FixedThreadPool/FixedClusterPool(numberOfThreads/numberOfWorkers, filePath, opts)`
50aa7901 150
31b90205 151`numberOfThreads/numberOfWorkers` (mandatory) Num of workers for this worker pool
50aa7901 152`filePath` (mandatory) Path to a file with a worker implementation
34a572eb 153`opts` (optional) An object with these properties :
50aa7901 154
31b90205
JB
155- `errorHandler` - A function that will listen for error event on each worker
156- `onlineHandler` - A function that will listen for online event on each worker
157- `exitHandler` - A function that will listen for exit event on each worker
34a572eb 158
31b90205 159### `pool = new DynamicThreadPool/DynamicClusterPool(min, max, filePath, opts)`
50aa7901 160
31b90205
JB
161`min` (mandatory) Same as FixedThreadPool/FixedClusterPool numberOfThreads/numberOfWorkers, this number of workers will be always active
162`max` (mandatory) Max number of workers that this pool can contain, the new created workers will die after a threshold (default is 1 minute, you can override it in your worker implementation).
163`filePath` (mandatory) Same as FixedThreadPool/FixedClusterPool
164`opts` (optional) Same as FixedThreadPool/FixedClusterPool
34a572eb 165
166### `pool.execute(data)`
50aa7901
S
167
168Execute method is available on both pool implementations (return type : Promise):
169`data` (mandatory) An object that you want to pass to your worker implementation
34a572eb 170
171### `pool.destroy()`
34a572eb 172
50aa7901
S
173Destroy method is available on both pool implementations.
174This method will call the terminate method on each worker.
34a572eb 175
31b90205 176### `class YourWorker extends ThreadWorker/ClusterWorker`
50aa7901 177
31b90205 178`fn` (mandatory) The function that you want to execute on the worker
50aa7901
S
179`opts` (optional) An object with these properties:
180
31b90205 181- `maxInactiveTime` - Max time to wait tasks to work on (in ms), after this period the new worker will die.
3832ad95
S
182 The last active time of your worker unit will be updated when a task is submitted to a worker or when a worker terminate a task.
183 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 and the worker is killed if is not part of the minimum size of the pool.
184 If `killBehavior` is set to `KillBehaviors.SOFT` your tasks have no timeout and your workers will not be terminated until your task is completed.
185 Default: 60.000 ms
15eacd5d 186
50aa7901 187- `async` - true/false, true if your function contains async pieces else false
15eacd5d 188- `killBehavior` - Dictates if your async unit (worker/process) will be deleted in case that a task is active on it.
31b90205 189 **SOFT**: If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker **won't** be deleted.
3832ad95
S
190 **HARD**: If `lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker will be deleted.
191 This option only apply to the newly created workers.
192 Default: `SOFT`
50aa7901
S
193
194## Choose your pool
34a572eb 195
31b90205 196Performance is one of the main target of these worker pool implementations, we want to have a strong focus on this.
88c8a0de 197We already have a bench folder where you can find some comparisons.
4b8093f6 198**Thread pools** ( FixedThreadPool and DynamicThreadPool ) are suggested to run CPU intensive tasks, you can still run I/O intensive tasks into thread pools, but performance enhancement is expected to be minimal.
063f8c5b 199Thread pools are built on top of Node.js [worker-threads](https://nodejs.org/api/worker_threads.html#worker_threads_worker_threads) module.
200
201**Cluster pools** (FixedClusterPool and DynamicClusterPool) are suggested to run I/O intensive tasks, again you can still run CPU intensive tasks into cluster pools, but performance enhancement is expected to be minimal.
202Cluster pools are built on top of Node.js [cluster](https://nodejs.org/api/cluster.html) module.
203
31b90205 204To choose your pool consider that with a FixedThreadPool/FixedClusterPool or a DynamicThreadPool/DynamicClusterPool (in this case is important the min parameter passed to the constructor) your application memory footprint will increase.
063f8c5b 205Increasing the memory footprint, your application will be ready to accept more tasks, but during idle time your application will consume more memory.
31b90205
JB
206One good choose from my point of view is to profile your application using Fixed/Dynamic worker pool, and to see your application metrics when you increase/decrease the num of workers.
207For example you could keep the memory footprint low choosing a DynamicThreadPool/DynamicClusterPool with 5 workers, and allow to create new workers until 50/100 when needed, this is the advantage to use the DynamicThreadPool/DynamicClusterPool.
50aa7901 208But in general, **always profile your application**
48211d04 209
50aa7901 210## Contribute
34a572eb 211
50aa7901
S
212See guidelines [CONTRIBUTING](CONTRIBUTING.md)
213Choose your task here [2.0.0](https://github.com/pioardi/poolifier/projects/1), propose an idea, a fix, an improvement.
1a4ec243 214
50aa7901 215## Team
1a4ec243 216
39deb558 217<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
218<!-- prettier-ignore-start -->
219<!-- markdownlint-disable -->
220
221**Creator/Owner:**
39deb558 222
50aa7901
S
223- [**Alessandro Pio Ardizio**](https://github.com/pioardi)
224
225**_Contributors_**
226
227- [**Shinigami92**](https://github.com/Shinigami92)
228- [**Jérôme Benoit**](https://github.com/jerome-benoit)
39deb558 229
50aa7901 230## License
1a4ec243 231
9507c1d4 232[MIT](./LICENSE)