Simplify worker choosing (#138)
[poolifier.git] / README.md
CommitLineData
987e0026 1# Node Thread Pool :arrow_double_up: :on:
50aa7901 2
34a572eb 3[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
103df814 4[![Dependabot](https://badgen.net/dependabot/dependabot/dependabot-core/?icon=dependabot)](https://badgen.net/dependabot/dependabot/dependabot-core/?icon=dependabot)
58a76e22 5[![npm w](https://img.shields.io/npm/dw/poolifier)](https://www.npmjs.com/package/poolifier)
e7752b74 6[![Actions Status](https://github.com/pioardi/node-pool/workflows/NodeCI/badge.svg)](https://github.com/pioardi/node-pool/actions)
50aa7901
S
7[![Coverage Status](https://coveralls.io/repos/github/pioardi/poolifier/badge.svg?branch=master)](https://coveralls.io/github/pioardi/poolifier?branch=master)
8[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
9[![NODEP](https://img.shields.io/static/v1?label=dependencies&message=no%20dependencies&color=brightgreen)](https://img.shields.io/static/v1?label=dependencies&message=no%20dependencies&color=brightgreen)
6ba2673b 10[![Gitter](https://badges.gitter.im/poolifier/community.svg)](https://gitter.im/poolifier/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
b4b2dc8b 11
50aa7901 12## Why Poolifier?
e76f5485 13
50aa7901
S
14Poolifier is used to perform heavy CPU bound tasks on nodejs servers, it implements thread pools (yes, more thread 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).
15With poolifier you can improve your **performance** and resolve problems related to the event loop.
16Moreover you can execute your CPU tasks using an API designed to improve the **developer experience**.
e76f5485 17
50aa7901 18## Contents
e76f5485 19
34a572eb 20<h3 align="center">
50aa7901
S
21 <a href="#overview">Overview</a>
22 <span> · </span>
34a572eb 23 <a href="#installation">Installation</a>
24 <span> · </span>
25 <a href="#usage">Usage</a>
26 <span> · </span>
50aa7901
S
27 <a href="#node-versions"> Node versions</a>
28 <span> · </span>
34a572eb 29 <a href="#api">API</a>
30 <span> · </span>
50aa7901 31 <a href="#choose-your-pool">Choose your pool</a>
48211d04 32 <span> · </span>
34a572eb 33 <a href="#contribute">Contribute</a>
34 <span> · </span>
50aa7901 35 <a href="#team">Team</a>
34a572eb 36 <span> · </span>
37 <a href="#license">License</a>
38</h3>
39
50aa7901 40## Overview
13031992 41
50aa7901
S
42Node pool contains two [worker-threads](https://nodejs.org/api/worker_threads.html#worker_threads_worker_threads) pool implementations, you don't have to deal with worker-threads complexity.
43The first implementation is a static thread pool, with a defined number of threads that are started at creation time and will be reused.
44The second implementation is a dynamic thread pool with a number of threads started at creation time (these threads will be always active and reused) and other threads created when the load will increase (with an upper limit, these threads will be reused when active), the new created threads will be stopped after a configurable period of inactivity.
45You have to implement your worker extending the ThreadWorker class
46
47## Installation
48
49```shell
27c5fb75 50npm install poolifier --save
1a4ec243 51```
1a4ec243 52
50aa7901
S
53## Usage
54
55You can implement a worker in a simple way, extending the class ThreadWorker:
1a4ec243
APA
56
57```js
58'use strict'
d2eb4964 59const { ThreadWorker } = require('poolifier')
1a4ec243 60
106744f7 61function yourFunction (data) {
62 // this will be executed in the worker thread,
63 // the data will be received by using the execute method
64 return { ok: 1 }
65}
66
50aa7901
S
67module.exports = new ThreadWorker(yourFunction, {
68 maxInactiveTime: 60000,
69 async: false
70})
1a4ec243
APA
71```
72
1f9a5a44 73Instantiate your pool based on your needed :
1a4ec243
APA
74
75```js
76'use strict'
d2eb4964 77const { FixedThreadPool, DynamicThreadPool } = require('poolifier')
1a4ec243
APA
78
79// a fixed thread pool
80const pool = new FixedThreadPool(15,
106744f7 81 './yourWorker.js',
82 { errorHandler: (e) => console.error(e), onlineHandler: () => console.log('worker is online') })
1a4ec243
APA
83
84// or a dynamic thread pool
85const pool = new DynamicThreadPool(10, 100,
106744f7 86 './yourWorker.js',
87 { errorHandler: (e) => console.error(e), onlineHandler: () => console.log('worker is online') })
88
1a4ec243
APA
89pool.emitter.on('FullPool', () => console.log('Pool is full'))
90
91// the execute method signature is the same for both implementations,
92// so you can easy switch from one to another
93pool.execute({}).then(res => {
94 console.log(res)
777b7824 95}).catch ....
1a4ec243
APA
96
97```
98
50aa7901
S
99**See examples folder for more details (in particular if you want to use a pool for [multiple functions](./examples/multiFunctionExample.js)).**
100**Now type script is also supported, find how to use it into the example folder**
1a4ec243 101
50aa7901 102## Node versions
34a572eb 103
50aa7901 104You can use node versions 12.x, 13.x, 14.x
1a4ec243 105
50aa7901 106## API
34a572eb 107
108### `pool = new FixedThreadPool(numThreads, filePath, opts)`
50aa7901
S
109
110`numThreads` (mandatory) Num of threads for this worker pool
111`filePath` (mandatory) Path to a file with a worker implementation
34a572eb 112`opts` (optional) An object with these properties :
50aa7901 113
34a572eb 114- `errorHandler` - A function that will listen for error event on each worker thread
115- `onlineHandler` - A function that will listen for online event on each worker thread
116- `exitHandler` - A function that will listen for exit event on each worker thread
50aa7901 117- `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 118
119### `pool = new DynamicThreadPool(min, max, filePath, opts)`
50aa7901
S
120
121`min` (mandatory) Same as FixedThreadPool numThreads, this number of threads will be always active
122`max` (mandatory) Max number of workers that this pool can contain, the new created threads will die after a threshold (default is 1 minute, you can override it in your worker implementation).
123`filePath` (mandatory) Same as FixedThreadPool
124`opts` (optional) Same as FixedThreadPool
34a572eb 125
126### `pool.execute(data)`
50aa7901
S
127
128Execute method is available on both pool implementations (return type : Promise):
129`data` (mandatory) An object that you want to pass to your worker implementation
34a572eb 130
131### `pool.destroy()`
34a572eb 132
50aa7901
S
133Destroy method is available on both pool implementations.
134This method will call the terminate method on each worker.
34a572eb 135
136### `class YourWorker extends ThreadWorker`
50aa7901
S
137
138`fn` (mandatory) The function that you want to execute on the worker thread
139`opts` (optional) An object with these properties:
140
34a572eb 141- `maxInactiveTime` - Max time to wait tasks to work on ( in ms) , after this period the new worker threads will die.
50aa7901
S
142- `async` - true/false, true if your function contains async pieces else false
143
144## Choose your pool
34a572eb 145
50aa7901 146Performance is one of the main target of these thread pool implementations, we want to have a strong focus on this.
48211d04 147We already have a bench folder where you can find some comparisons.
50aa7901
S
148To choose your pool consider that with a FixedThreadPool or a DynamicThreadPool (in this case is important the min parameter passed to the constructor) your application memory footprint will increase.
149Increasing the memory footprint, your application will be ready to accept more CPU bound tasks, but during idle time your application will consume more memory.
150One good choose from my point of view is to profile your application using Fixed/Dynamic thread pool, and to see your application metrics when you increase/decrease the num of threads.
151For example you could keep the memory footprint low choosing a DynamicThreadPool with 5 threads, and allow to create new threads until 50/100 when needed, this is the advantage to use the DynamicThreadPool.
152But in general, **always profile your application**
48211d04 153
50aa7901 154## Contribute
34a572eb 155
50aa7901
S
156See guidelines [CONTRIBUTING](CONTRIBUTING.md)
157Choose your task here [2.0.0](https://github.com/pioardi/poolifier/projects/1), propose an idea, a fix, an improvement.
1a4ec243 158
50aa7901 159## Team
1a4ec243 160
39deb558 161<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
162<!-- prettier-ignore-start -->
163<!-- markdownlint-disable -->
164
165**Creator/Owner:**
39deb558 166
50aa7901
S
167- [**Alessandro Pio Ardizio**](https://github.com/pioardi)
168
169**_Contributors_**
170
171- [**Shinigami92**](https://github.com/Shinigami92)
172- [**Jérôme Benoit**](https://github.com/jerome-benoit)
39deb558 173
50aa7901 174## License
1a4ec243 175
9507c1d4 176[MIT](./LICENSE)