README.md: Small refinements
[poolifier.git] / README.md
CommitLineData
f2b5671a 1<div align="center">
4518016c 2<img src="./docs/logo.png" width="475" height="400"/>
ddaa3a76 3</div>
4
1d4f79e7
APA
5<h2 align="center">Node Thread Pool :arrow_double_up: :on:</h2>
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
31b90205 30Poolifier is used to perform heavy CPU bound 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).
50aa7901
S
31With poolifier you can improve your **performance** and resolve problems related to the event loop.
32Moreover you can execute your CPU tasks using an API designed to improve the **developer experience**.
e76f5485 33
ddaa3a76 34- Performance :racehorse:
f2b5671a 35- 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 36- Easy to use :couple:
38553e6e 37- Easy switch from a pool to another, easy to tune :heavy_check_mark:
38- Dynamic pool size :heavy_check_mark:
d28c7996 39- No runtime dependencies :heavy_check_mark:
38553e6e 40- Proper async integration with node async hooks :heavy_check_mark:
41- Support for worker threads and cluster node modules :heavy_check_mark:
38553e6e 42- Support sync and async tasks :heavy_check_mark:
43- General guidance on pools to use :heavy_check_mark:
44- Widely tested :heavy_check_mark:
45- Error handling out of the box :heavy_check_mark:
ed93dc74 46- Active community :heavy_check_mark:
5fd75a2e 47- 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
48 [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=code_smells)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
49 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
50 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
51 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
52 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=sqale_index)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
ddaa3a76 53
50aa7901 54## Contents
e76f5485 55
34a572eb 56<h3 align="center">
50aa7901
S
57 <a href="#overview">Overview</a>
58 <span> · </span>
34a572eb 59 <a href="#installation">Installation</a>
60 <span> · </span>
61 <a href="#usage">Usage</a>
62 <span> · </span>
50aa7901
S
63 <a href="#node-versions"> Node versions</a>
64 <span> · </span>
34a572eb 65 <a href="#api">API</a>
66 <span> · </span>
50aa7901 67 <a href="#choose-your-pool">Choose your pool</a>
48211d04 68 <span> · </span>
34a572eb 69 <a href="#contribute">Contribute</a>
70 <span> · </span>
50aa7901 71 <a href="#team">Team</a>
34a572eb 72 <span> · </span>
73 <a href="#license">License</a>
74</h3>
75
50aa7901 76## Overview
13031992 77
31b90205
JB
78Node 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.
79The first implementation is a static worker pool, with a defined number of workers that are started at creation time and will be reused.
80The 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.
81You have to implement your worker extending the ThreadWorker or ClusterWorker class
50aa7901
S
82
83## Installation
84
85```shell
27c5fb75 86npm install poolifier --save
1a4ec243 87```
1a4ec243 88
50aa7901
S
89## Usage
90
31b90205 91You can implement a worker-threads worker in a simple way by extending the class ThreadWorker:
1a4ec243
APA
92
93```js
94'use strict'
d2eb4964 95const { ThreadWorker } = require('poolifier')
1a4ec243 96
106744f7 97function yourFunction (data) {
98 // this will be executed in the worker thread,
99 // the data will be received by using the execute method
100 return { ok: 1 }
101}
102
50aa7901
S
103module.exports = new ThreadWorker(yourFunction, {
104 maxInactiveTime: 60000,
105 async: false
106})
1a4ec243
APA
107```
108
1f9a5a44 109Instantiate your pool based on your needed :
1a4ec243
APA
110
111```js
112'use strict'
d2eb4964 113const { FixedThreadPool, DynamicThreadPool } = require('poolifier')
1a4ec243 114
31b90205 115// a fixed worker-threads pool
1a4ec243 116const pool = new FixedThreadPool(15,
106744f7 117 './yourWorker.js',
118 { errorHandler: (e) => console.error(e), onlineHandler: () => console.log('worker is online') })
1a4ec243 119
31b90205 120// or a dynamic worker-threads pool
1a4ec243 121const pool = new DynamicThreadPool(10, 100,
106744f7 122 './yourWorker.js',
123 { errorHandler: (e) => console.error(e), onlineHandler: () => console.log('worker is online') })
124
1a4ec243
APA
125pool.emitter.on('FullPool', () => console.log('Pool is full'))
126
127// the execute method signature is the same for both implementations,
128// so you can easy switch from one to another
129pool.execute({}).then(res => {
130 console.log(res)
777b7824 131}).catch ....
1a4ec243
APA
132
133```
134
17a9a094 135You can do the same with the classes ClusterWorker, FixedClusterPool and DynamicClusterPool.
31b90205 136
17a9a094
JB
137**See examples folder for more details (in particular if you want to use a pool for [multiple functions](./examples/multiFunctionExample.js)).**
138**Now TypeScript is also supported, find how to use it into the example folder**.
1a4ec243 139
50aa7901 140## Node versions
34a572eb 141
50aa7901 142You can use node versions 12.x, 13.x, 14.x
1a4ec243 143
50aa7901 144## API
34a572eb 145
31b90205 146### `pool = new FixedThreadPool/FixedClusterPool(numberOfThreads/numberOfWorkers, filePath, opts)`
50aa7901 147
31b90205 148`numberOfThreads/numberOfWorkers` (mandatory) Num of workers for this worker pool
50aa7901 149`filePath` (mandatory) Path to a file with a worker implementation
34a572eb 150`opts` (optional) An object with these properties :
50aa7901 151
31b90205
JB
152- `errorHandler` - A function that will listen for error event on each worker
153- `onlineHandler` - A function that will listen for online event on each worker
154- `exitHandler` - A function that will listen for exit event on each worker
50aa7901 155- `maxTasks` - This is just to avoid not useful warnings message, is used to set [maxListeners](https://nodejs.org/dist/latest-v12.x/docs/api/events.html#events_emitter_setmaxlisteners_n) on event emitters (workers are event emitters)
34a572eb 156
31b90205 157### `pool = new DynamicThreadPool/DynamicClusterPool(min, max, filePath, opts)`
50aa7901 158
31b90205
JB
159`min` (mandatory) Same as FixedThreadPool/FixedClusterPool numberOfThreads/numberOfWorkers, this number of workers will be always active
160`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).
161`filePath` (mandatory) Same as FixedThreadPool/FixedClusterPool
162`opts` (optional) Same as FixedThreadPool/FixedClusterPool
34a572eb 163
164### `pool.execute(data)`
50aa7901
S
165
166Execute method is available on both pool implementations (return type : Promise):
167`data` (mandatory) An object that you want to pass to your worker implementation
34a572eb 168
169### `pool.destroy()`
34a572eb 170
50aa7901
S
171Destroy method is available on both pool implementations.
172This method will call the terminate method on each worker.
34a572eb 173
31b90205 174### `class YourWorker extends ThreadWorker/ClusterWorker`
50aa7901 175
31b90205 176`fn` (mandatory) The function that you want to execute on the worker
50aa7901
S
177`opts` (optional) An object with these properties:
178
31b90205 179- `maxInactiveTime` - Max time to wait tasks to work on (in ms), after this period the new worker will die.
3832ad95
S
180 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.
181 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.
182 If `killBehavior` is set to `KillBehaviors.SOFT` your tasks have no timeout and your workers will not be terminated until your task is completed.
183 Default: 60.000 ms
15eacd5d 184
50aa7901 185- `async` - true/false, true if your function contains async pieces else false
15eacd5d 186- `killBehavior` - Dictates if your async unit (worker/process) will be deleted in case that a task is active on it.
31b90205 187 **SOFT**: If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker **won't** be deleted.
3832ad95
S
188 **HARD**: If `lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker will be deleted.
189 This option only apply to the newly created workers.
190 Default: `SOFT`
50aa7901
S
191
192## Choose your pool
34a572eb 193
31b90205 194Performance is one of the main target of these worker pool implementations, we want to have a strong focus on this.
48211d04 195We already have a bench folder where you can find some comparisons.
31b90205 196To 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.
50aa7901 197Increasing the memory footprint, your application will be ready to accept more CPU bound tasks, but during idle time your application will consume more memory.
31b90205
JB
198One 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.
199For 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 200But in general, **always profile your application**
48211d04 201
50aa7901 202## Contribute
34a572eb 203
50aa7901
S
204See guidelines [CONTRIBUTING](CONTRIBUTING.md)
205Choose your task here [2.0.0](https://github.com/pioardi/poolifier/projects/1), propose an idea, a fix, an improvement.
1a4ec243 206
50aa7901 207## Team
1a4ec243 208
39deb558 209<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
210<!-- prettier-ignore-start -->
211<!-- markdownlint-disable -->
212
213**Creator/Owner:**
39deb558 214
50aa7901
S
215- [**Alessandro Pio Ardizio**](https://github.com/pioardi)
216
217**_Contributors_**
218
219- [**Shinigami92**](https://github.com/Shinigami92)
220- [**Jérôme Benoit**](https://github.com/jerome-benoit)
39deb558 221
50aa7901 222## License
1a4ec243 223
9507c1d4 224[MIT](./LICENSE)