docs: generate documentation
[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:
af98b972 47 - Task stealing on empty queue :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
93'use strict'
d2eb4964 94const { ThreadWorker } = require('poolifier')
1a4ec243 95
78cea37e 96function yourFunction(data) {
106744f7 97 // this will be executed in the worker thread,
98 // the data will be received by using the execute method
99 return { ok: 1 }
100}
101
50aa7901 102module.exports = new ThreadWorker(yourFunction, {
124119cf 103 maxInactiveTime: 60000
50aa7901 104})
1a4ec243
APA
105```
106
0feeec4a 107Instantiate your pool based on your needs :
1a4ec243
APA
108
109```js
110'use strict'
6961ca9a 111const { DynamicThreadPool, FixedThreadPool, PoolEvents, availableParallelism } = require('poolifier')
1a4ec243 112
2fbe1783 113// a fixed worker_threads pool
6961ca9a 114const pool = new FixedThreadPool(availableParallelism(), './yourWorker.js', {
0eee77cb 115 errorHandler: (e) => console.error(e),
53795b86
JB
116 onlineHandler: () => console.info('worker is online')
117})
1a4ec243 118
8538ea4c
JB
119pool.emitter?.on(PoolEvents.ready, () => console.info('Pool is ready'))
120pool.emitter?.on(PoolEvents.busy, () => console.info('Pool is busy'))
164d950a 121
2fbe1783 122// or a dynamic worker_threads pool
31a7d5be 123const pool = new DynamicThreadPool(Math.floor(availableParallelism() / 2), availableParallelism(), './yourWorker.js', {
0eee77cb 124 errorHandler: (e) => console.error(e),
53795b86
JB
125 onlineHandler: () => console.info('worker is online')
126})
106744f7 127
8538ea4c
JB
128pool.emitter?.on(PoolEvents.full, () => console.info('Pool is full'))
129pool.emitter?.on(PoolEvents.ready, () => console.info('Pool is ready'))
130pool.emitter?.on(PoolEvents.busy, () => console.info('Pool is busy'))
1a4ec243
APA
131
132// the execute method signature is the same for both implementations,
74ecb519 133// so you can easily switch from one to another
8351c9af 134pool
8923de44 135 .execute()
0eee77cb 136 .then((res) => {
8351c9af
JB
137 console.info(res)
138 })
0eee77cb 139 .catch((err) => {
8351c9af
JB
140 console.error(err)
141 })
1a4ec243
APA
142```
143
6ec11f90 144You can do the same with the classes _ClusterWorker_, _FixedClusterPool_ and _DynamicClusterPool_.
31b90205 145
b0834e9d 146**See [examples](./examples/) for more details**:
b2b02b3d 147
7a923e5b 148- [Javascript](./examples/javascript/)
b2b02b3d 149- [Typescript](./examples/typescript/)
5ba0cd3c 150 - [HTTP client pool](./examples/typescript/http-client-pool/)
9aef1431 151 - [SMTP client pool](./examples/typescript/smtp-client-pool/)
fac9ce96 152 - [HTTP server pool](./examples/typescript/http-server-pool/)
d2bc8d80 153 - [Express worker_threads pool](./examples/typescript/http-server-pool/express-worker_threads/)
15a9c195 154 - [Express cluster pool](./examples/typescript/http-server-pool/express-cluster/)
d0ed34c9 155 - [Express hybrid pool](./examples/typescript/http-server-pool/express-hybrid/)
d2bc8d80
JB
156 - [Fastify worker_threads pool](./examples/typescript/http-server-pool/fastify-worker_threads/)
157 - [Fastify cluster pool](./examples/typescript/http-server-pool/fastify-cluster/)
3b311539 158 - [Fastify hybrid pool](./examples/typescript/http-server-pool/fastify-hybrid/)
9e623684 159 - [WebSocket server pool](./examples/typescript/websocket-server-pool/)
d2bc8d80 160 - [ws worker_threads pool](./examples/typescript/websocket-server-pool/ws-worker_threads/)
72855e92 161 - [ws cluster pool](./examples/typescript/websocket-server-pool/ws-cluster/)
02999424 162 - [ws hybrid pool](./examples/typescript/websocket-server-pool/ws-hybrid/)
1a4ec243 163
6677a3d3 164Remember that workers can only send and receive structured-cloneable data.
deb85c12 165
8ea47589 166## Node.js versions
34a572eb 167
277c49bf 168Node.js versions >= 18.x.x are supported.
1a4ec243 169
b492f20e 170## [API](./docs/api.md)
4680c1b2 171
4f8e444d
JB
172## [General guidelines](./docs/general-guidelines.md)
173
174## [Worker choice strategies](./docs/worker-choice-strategies.md)
48211d04 175
50aa7901 176## Contribute
34a572eb 177
f097c79b 178Choose your task [here](https://github.com/orgs/poolifier/projects/1), propose an idea, a fix, an improvement.
1a4ec243 179
e6973c72 180See [CONTRIBUTING](./CONTRIBUTING.md) guidelines.
0feeec4a 181
50aa7901 182## Team
1a4ec243 183
39deb558 184**Creator/Owner:**
39deb558 185
50aa7901
S
186- [**Alessandro Pio Ardizio**](https://github.com/pioardi)
187
5c47fa7c 188**Maintainers:**
50aa7901 189
50aa7901 190- [**Jérôme Benoit**](https://github.com/jerome-benoit)
39deb558 191
5c47fa7c
JB
192**Contributors:**
193
194- [**Shinigami92**](https://github.com/Shinigami92)
195
50aa7901 196## License
1a4ec243 197
9507c1d4 198[MIT](./LICENSE)