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