Merge branch 'master' into combined-prs-branch
[poolifier.git] / README.md
CommitLineData
f2b5671a 1<div align="center">
0feeec4a 2 <img src="./images/logo.png" width="340px" height="266px"/>
ddaa3a76 3</div>
4
29527e83
JB
5<div align="center">
6
7# Node.js Worker_Threads and Cluster Worker Pool
8
9</div>
1d4f79e7 10
2030d177 11<div align="center">
29527e83
JB
12
13[![GitHub commit activity (master)](https://img.shields.io/github/commit-activity/m/poolifier/poolifier/master?color=brightgreen&logo=github)](https://github.com/poolifier/poolifier/graphs/commit-activity)
14[![Weekly Downloads](https://badgen.net/npm/dw/poolifier?icon=npm)](https://www.npmjs.com/package/poolifier)
4e91d15c 15[![CI Workflow](https://github.com/poolifier/poolifier/actions/workflows/ci.yml/badge.svg)](https://github.com/poolifier/poolifier/actions/workflows/ci.yml)
58c0dd01
JB
16[![Code Coverage](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=coverage)](https://sonarcloud.io/dashboard?id=poolifier_poolifier)
17[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=alert_status)](https://sonarcloud.io/dashboard?id=poolifier_poolifier)
29527e83 18[![Javascript Standard Style Guide](<https://badgen.net/static/code style/standard/green>)](https://standardjs.com)
67c552d6 19[![Discord](https://badgen.net/discord/online-members/vXxZhyb3b6?icon=discord&label=discord&color=green)](https://discord.gg/vXxZhyb3b6)
29527e83 20[![Open Collective](https://opencollective.com/poolifier/tiers/badge.svg)](https://opencollective.com/poolifier)
ae3ab61d 21[![PRs Welcome](https://badgen.net/static/PRs/welcome/green)](https://makeapullrequest.com)
f0c6203d 22[![No Dependencies](<https://badgen.net/static/dependencies/no dependencies/green>)](<https://badgen.net/static/dependencies/no dependencies/green>)
29527e83 23
2030d177 24</div>
1d4f79e7 25
74750c7f 26## Why Poolifier?
e76f5485 27
6ec11f90 28Poolifier is used to perform CPU and/or I/O intensive tasks on Node.js servers, it implements worker pools using [worker_threads](https://nodejs.org/api/worker_threads.html) and [cluster](https://nodejs.org/api/cluster.html) Node.js modules.
50aa7901 29With poolifier you can improve your **performance** and resolve problems related to the event loop.
063f8c5b 30Moreover you can execute your tasks using an API designed to improve the **developer experience**.
b492f20e 31Please consult our [general guidelines](#general-guidelines).
e76f5485 32
bd2ff6e0 33- Easy to use :white_check_mark:
03babf6f 34- Fixed and dynamic pool size :white_check_mark:
6ec11f90 35- Easy switch from a pool type to another :white_check_mark:
5bc19860 36- Performance [benchmarks](./benchmarks/README.md) :white_check_mark:
82be29c0 37- No runtime dependencies :white_check_mark:
d0ed34c9 38- Proper integration with Node.js [async_hooks](https://nodejs.org/api/async_hooks.html) :white_check_mark:
e30fb225 39- Support for CommonJS, ESM and TypeScript :white_check_mark:
6ec11f90 40- Support for [worker_threads](https://nodejs.org/api/worker_threads.html) and [cluster](https://nodejs.org/api/cluster.html) Node.js modules :white_check_mark:
aad54ad2 41- Support for multiple task functions :white_check_mark:
1f3f7256 42- Support for task functions [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations at runtime :white_check_mark:
aad54ad2 43- Support for sync and async task functions :white_check_mark:
89a4abfd 44- Tasks distribution strategies :white_check_mark:
84de2e11 45- Lockless tasks queueing :white_check_mark:
72695f86 46- Queued tasks rescheduling:
65542a35 47 - Task stealing on idle :white_check_mark:
72695f86 48 - Tasks stealing under back pressure :white_check_mark:
dd951876 49 - Tasks redistribution on worker error :white_check_mark:
b492f20e 50- General guidelines on pool choice :white_check_mark:
82be29c0 51- Error handling out of the box :white_check_mark:
6ec11f90 52- Widely tested :white_check_mark:
82be29c0 53- Active community :white_check_mark:
58c0dd01
JB
54- Code quality [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=bugs)](https://sonarcloud.io/dashboard?id=poolifier_poolifier)
55 [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=code_smells)](https://sonarcloud.io/dashboard?id=poolifier_poolifier)
56 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=poolifier_poolifier)
57 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=poolifier_poolifier)
58 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=poolifier_poolifier)
59 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=sqale_index)](https://sonarcloud.io/dashboard?id=poolifier_poolifier)
60- Code security [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=security_rating)](https://sonarcloud.io/dashboard?id=poolifier_poolifier) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=poolifier_poolifier&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=poolifier_poolifier)
ddaa3a76 61
4f8e444d
JB
62## Table of contents
63
64- [Overview](#overview)
65- [Installation](#installation)
66- [Usage](#usage)
8ea47589 67- [Node.js versions](#nodejs-versions)
4f8e444d
JB
68- [API](#api)
69- [General guidelines](#general-guidelines)
70- [Worker choice strategies](#worker-choice-strategies)
71- [Contribute](#contribute)
72- [Team](#team)
73- [License](#license)
34a572eb 74
50aa7901 75## Overview
13031992 76
22c0d9a2 77Poolifier contains two [worker_threads](https://nodejs.org/api/worker_threads.html#class-worker)/[cluster](https://nodejs.org/api/cluster.html#cluster_class_worker) worker pool implementations, you don't have to deal with [worker_threads](https://nodejs.org/api/worker_threads.html)/[cluster](https://nodejs.org/api/cluster.html) complexity.
03babf6f 78The first implementation is a fixed worker pool, with a defined number of workers that are started at creation time and will be reused.
a36b9e1f 79The 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 newly created workers will be stopped after a configurable period of inactivity.
22c0d9a2 80You have to implement your worker by extending the _ThreadWorker_ or _ClusterWorker_ class.
50aa7901
S
81
82## Installation
83
84```shell
27c5fb75 85npm install poolifier --save
1a4ec243 86```
1a4ec243 87
50aa7901
S
88## Usage
89
6ec11f90 90You can implement a [worker_threads](https://nodejs.org/api/worker_threads.html#class-worker) worker in a simple way by extending the class _ThreadWorker_:
1a4ec243
APA
91
92```js
d35e5717 93import { ThreadWorker } from 'poolifier'
1a4ec243 94
78cea37e 95function yourFunction(data) {
106744f7 96 // this will be executed in the worker thread,
97 // the data will be received by using the execute method
98 return { ok: 1 }
99}
100
50aa7901 101module.exports = new ThreadWorker(yourFunction, {
124119cf 102 maxInactiveTime: 60000
50aa7901 103})
1a4ec243
APA
104```
105
0feeec4a 106Instantiate your pool based on your needs :
1a4ec243
APA
107
108```js
d35e5717 109import { DynamicThreadPool, FixedThreadPool, PoolEvents, availableParallelism } from 'poolifier'
1a4ec243 110
2fbe1783 111// a fixed worker_threads pool
6961ca9a 112const pool = new FixedThreadPool(availableParallelism(), './yourWorker.js', {
0eee77cb 113 errorHandler: (e) => console.error(e),
53795b86
JB
114 onlineHandler: () => console.info('worker is online')
115})
1a4ec243 116
8538ea4c
JB
117pool.emitter?.on(PoolEvents.ready, () => console.info('Pool is ready'))
118pool.emitter?.on(PoolEvents.busy, () => console.info('Pool is busy'))
164d950a 119
2fbe1783 120// or a dynamic worker_threads pool
31a7d5be 121const pool = new DynamicThreadPool(Math.floor(availableParallelism() / 2), availableParallelism(), './yourWorker.js', {
0eee77cb 122 errorHandler: (e) => console.error(e),
53795b86
JB
123 onlineHandler: () => console.info('worker is online')
124})
106744f7 125
8538ea4c
JB
126pool.emitter?.on(PoolEvents.full, () => console.info('Pool is full'))
127pool.emitter?.on(PoolEvents.ready, () => console.info('Pool is ready'))
128pool.emitter?.on(PoolEvents.busy, () => console.info('Pool is busy'))
1a4ec243
APA
129
130// the execute method signature is the same for both implementations,
74ecb519 131// so you can easily switch from one to another
8351c9af 132pool
8923de44 133 .execute()
0eee77cb 134 .then((res) => {
8351c9af
JB
135 console.info(res)
136 })
0eee77cb 137 .catch((err) => {
8351c9af
JB
138 console.error(err)
139 })
1a4ec243
APA
140```
141
6ec11f90 142You can do the same with the classes _ClusterWorker_, _FixedClusterPool_ and _DynamicClusterPool_.
31b90205 143
b0834e9d 144**See [examples](./examples/) for more details**:
b2b02b3d 145
7a923e5b 146- [Javascript](./examples/javascript/)
b2b02b3d 147- [Typescript](./examples/typescript/)
5ba0cd3c 148 - [HTTP client pool](./examples/typescript/http-client-pool/)
9aef1431 149 - [SMTP client pool](./examples/typescript/smtp-client-pool/)
fac9ce96 150 - [HTTP server pool](./examples/typescript/http-server-pool/)
d2bc8d80 151 - [Express worker_threads pool](./examples/typescript/http-server-pool/express-worker_threads/)
15a9c195 152 - [Express cluster pool](./examples/typescript/http-server-pool/express-cluster/)
d0ed34c9 153 - [Express hybrid pool](./examples/typescript/http-server-pool/express-hybrid/)
d2bc8d80
JB
154 - [Fastify worker_threads pool](./examples/typescript/http-server-pool/fastify-worker_threads/)
155 - [Fastify cluster pool](./examples/typescript/http-server-pool/fastify-cluster/)
3b311539 156 - [Fastify hybrid pool](./examples/typescript/http-server-pool/fastify-hybrid/)
9e623684 157 - [WebSocket server pool](./examples/typescript/websocket-server-pool/)
d2bc8d80 158 - [ws worker_threads pool](./examples/typescript/websocket-server-pool/ws-worker_threads/)
72855e92 159 - [ws cluster pool](./examples/typescript/websocket-server-pool/ws-cluster/)
02999424 160 - [ws hybrid pool](./examples/typescript/websocket-server-pool/ws-hybrid/)
1a4ec243 161
6677a3d3 162Remember that workers can only send and receive structured-cloneable data.
deb85c12 163
8ea47589 164## Node.js versions
34a572eb 165
277c49bf 166Node.js versions >= 18.x.x are supported.
1a4ec243 167
b492f20e 168## [API](./docs/api.md)
4680c1b2 169
4f8e444d
JB
170## [General guidelines](./docs/general-guidelines.md)
171
172## [Worker choice strategies](./docs/worker-choice-strategies.md)
48211d04 173
50aa7901 174## Contribute
34a572eb 175
f097c79b 176Choose your task [here](https://github.com/orgs/poolifier/projects/1), propose an idea, a fix, an improvement.
1a4ec243 177
e6973c72 178See [CONTRIBUTING](./CONTRIBUTING.md) guidelines.
0feeec4a 179
50aa7901 180## Team
1a4ec243 181
39deb558 182**Creator/Owner:**
39deb558 183
50aa7901
S
184- [**Alessandro Pio Ardizio**](https://github.com/pioardi)
185
5c47fa7c 186**Maintainers:**
50aa7901 187
50aa7901 188- [**Jérôme Benoit**](https://github.com/jerome-benoit)
39deb558 189
5c47fa7c
JB
190**Contributors:**
191
192- [**Shinigami92**](https://github.com/Shinigami92)
193
50aa7901 194## License
1a4ec243 195
9507c1d4 196[MIT](./LICENSE)