feat: add fastify hybrid pools example
[poolifier.git] / README.md
... / ...
CommitLineData
1<div align="center">
2 <img src="./images/logo.png" width="340px" height="266px"/>
3</div>
4
5<h1 align="center">Node.js Worker_Threads and Cluster Worker Pool</h1>
6
7<p align="center">
8 <a href="https://github.com/poolifier/poolifier/graphs/commit-activity">
9 <img alt="GitHub commit activity (master)" src="https://img.shields.io/github/commit-activity/m/poolifier/poolifier/master"></a>
10 <a href="https://www.npmjs.com/package/poolifier">
11 <img alt="Weekly Downloads" src="https://img.shields.io/npm/dw/poolifier"></a>
12 <a href="https://github.com/poolifier/poolifier/actions/workflows/ci.yml">
13 <img alt="Actions Status" src="https://github.com/poolifier/poolifier/actions/workflows/ci.yml/badge.svg"></a>
14 <a href="https://sonarcloud.io/dashboard?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://sonarcloud.io/dashboard?id=pioardi_poolifier">
17 <img alt="Quality Gate Status" src="https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=alert_status"></a>
18 <a href="https://standardjs.com">
19 <img alt="Javascript Standard Style Guide" src="https://img.shields.io/badge/code_style-standard-brightgreen.svg"></a>
20 <a href="https://gitter.im/poolifier/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge">
21 <img alt="Gitter chat" src="https://badges.gitter.im/poolifier/community.svg"></a>
22 <a href="https://opencollective.com/poolifier">
23 <img alt="Open Collective" src="https://opencollective.com/poolifier/tiers/badge.svg"></a>
24 <a href="http://makeapullrequest.com">
25 <img alt="PR Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square"></a>
26 <a href="https://img.shields.io/static/v1?label=dependencies&message=no%20dependencies&color=brightgreen">
27 <img alt="No dependencies" src="https://img.shields.io/static/v1?label=dependencies&message=no%20dependencies&color=brightgreen"></a>
28</p>
29
30## Why Poolifier?
31
32Poolifier 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.
33With poolifier you can improve your **performance** and resolve problems related to the event loop.
34Moreover you can execute your tasks using an API designed to improve the **developer experience**.
35Please consult our [general guidelines](#general-guidelines).
36
37- Easy to use :white_check_mark:
38- Performance [benchmarks](./benchmarks/README.md) :white_check_mark:
39- Fixed and dynamic pool size :white_check_mark:
40- Easy switch from a pool type to another :white_check_mark:
41- No runtime dependencies :white_check_mark:
42- Proper integration with node [async_hooks](https://nodejs.org/api/async_hooks.html) :white_check_mark:
43- Support CommonJS, ESM, and TypeScript :white_check_mark:
44- 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:
45- Support multiple task functions :white_check_mark:
46- Support sync and async task functions :white_check_mark:
47- Tasks distribution strategies :white_check_mark:
48- General guidelines on pool choice :white_check_mark:
49- Error handling out of the box :white_check_mark:
50- Widely tested :white_check_mark:
51- Active community :white_check_mark:
52- Code quality [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=bugs)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
53 [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=code_smells)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
54 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
55 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
56 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
57 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=pioardi_poolifier&metric=sqale_index)](https://sonarcloud.io/dashboard?id=pioardi_poolifier)
58- Code security [![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)
59
60## Table of contents
61
62- [Overview](#overview)
63- [Installation](#installation)
64- [Usage](#usage)
65- [Node versions](#node-versions)
66- [API](#api)
67- [General guidelines](#general-guidelines)
68- [Worker choice strategies](#worker-choice-strategies)
69- [Contribute](#contribute)
70- [Team](#team)
71- [License](#license)
72
73## Overview
74
75Poolifier 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.
76The first implementation is a fixed worker pool, with a defined number of workers that are started at creation time and will be reused.
77The 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.
78You have to implement your worker by extending the _ThreadWorker_ or _ClusterWorker_ class.
79
80## Installation
81
82```shell
83npm install poolifier --save
84```
85
86## Usage
87
88You can implement a [worker_threads](https://nodejs.org/api/worker_threads.html#class-worker) worker in a simple way by extending the class _ThreadWorker_:
89
90```js
91'use strict'
92const { ThreadWorker } = require('poolifier')
93
94function yourFunction(data) {
95 // this will be executed in the worker thread,
96 // the data will be received by using the execute method
97 return { ok: 1 }
98}
99
100module.exports = new ThreadWorker(yourFunction, {
101 maxInactiveTime: 60000
102})
103```
104
105Instantiate your pool based on your needs :
106
107```js
108'use strict'
109const { DynamicThreadPool, FixedThreadPool, PoolEvents, availableParallelism } = require('poolifier')
110
111// a fixed worker_threads pool
112const pool = new FixedThreadPool(availableParallelism(), './yourWorker.js', {
113 errorHandler: e => console.error(e),
114 onlineHandler: () => console.info('worker is online')
115})
116
117pool.emitter.on(PoolEvents.ready, () => console.info('Pool is ready'))
118pool.emitter.on(PoolEvents.busy, () => console.info('Pool is busy'))
119
120// or a dynamic worker_threads pool
121const pool = new DynamicThreadPool(Math.floor(availableParallelism() / 2), availableParallelism(), './yourWorker.js', {
122 errorHandler: e => console.error(e),
123 onlineHandler: () => console.info('worker is online')
124})
125
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'))
129
130// the execute method signature is the same for both implementations,
131// so you can easy switch from one to another
132pool
133 .execute()
134 .then(res => {
135 console.info(res)
136 })
137 .catch(err => {
138 console.error(err)
139 })
140```
141
142You can do the same with the classes _ClusterWorker_, _FixedClusterPool_ and _DynamicClusterPool_.
143
144**See [examples](./examples/) folder for more details**:
145
146- [Javascript](./examples/javascript/)
147- [Typescript](./examples/typescript/)
148 - [HTTP client pool](./examples/typescript/http-client-pool/)
149 - [HTTP server pool](./examples/typescript/http-server-pool/)
150 - [Express worker_threads pool](./examples/typescript/http-server-pool/express-worker_threads/)
151 - [Fastify worker_threads pool](./examples/typescript/http-server-pool/fastify-worker_threads/)
152 - [Fastify cluster pool](./examples/typescript/http-server-pool/fastify-cluster/)
153 - [Fastify hybrid pool](./examples/typescript/http-server-pool/fastify-hybrid/)
154 - [WebSocket server pool](./examples/typescript/websocket-server-pool/)
155 - [ws worker_threads pool](./examples/typescript/websocket-server-pool/ws-worker_threads/)
156 - [ws cluster pool](./examples/typescript/websocket-server-pool/ws-cluster/)
157
158Remember that workers can only send and receive structured-cloneable data.
159
160## Node versions
161
162Node versions >= 16.14.x are supported.
163
164## [API](./docs/api.md)
165
166## [General guidelines](./docs/general-guidelines.md)
167
168## [Worker choice strategies](./docs/worker-choice-strategies.md)
169
170## Contribute
171
172Choose your task here [2.6.x](https://github.com/orgs/poolifier/projects/1), propose an idea, a fix, an improvement.
173
174See [CONTRIBUTING](CONTRIBUTING.md) guidelines.
175
176## Team
177
178**Creator/Owner:**
179
180- [**Alessandro Pio Ardizio**](https://github.com/pioardi)
181
182**_Contributors_**
183
184- [**Shinigami92**](https://github.com/Shinigami92)
185- [**Jérôme Benoit**](https://github.com/jerome-benoit)
186
187## License
188
189[MIT](./LICENSE)