- Proper async integration with node async hooks :white_check_mark:
- Support for worker threads and cluster node modules :white_check_mark:
- Support sync and async tasks :white_check_mark:
+- Tasks distribution strategies :white_check_mark:
- General guidance on pools to use :white_check_mark:
- Widely tested :white_check_mark:
- Error handling out of the box :white_check_mark:
## Node versions
-Node versions >= 16.x are supported.
+Node versions >= 16.14.x are supported.
## [API](https://poolifier.github.io/poolifier/)
-### `pool = new FixedThreadPool/FixedClusterPool(numberOfThreads/numberOfWorkers, filePath, opts)`
+### Pool options
-`numberOfThreads/numberOfWorkers` (mandatory) Number of workers for this pool
-`filePath` (mandatory) Path to a file with a worker implementation
-`opts` (optional) An object with these properties:
+An object with these properties:
- `messageHandler` (optional) - A function that will listen for message event on each worker
- `errorHandler` (optional) - A function that will listen for error event on each worker
- `exitHandler` (optional) - A function that will listen for exit event on each worker
- `workerChoiceStrategy` (optional) - The worker choice strategy to use in this pool:
- - `WorkerChoiceStrategies.ROUND_ROBIN`: Submit tasks to worker in a round robbin fashion
- - `WorkerChoiceStrategies.LESS_USED`: Submit tasks to the less used worker
- - `WorkerChoiceStrategies.LESS_BUSY`: Submit tasks to the less busy worker
- - `WorkerChoiceStrategies.WEIGHTED_ROUND_ROBIN`: Submit tasks to worker using a weighted round robin scheduling algorithm based on tasks execution time
- - `WorkerChoiceStrategies.FAIR_SHARE`: Submit tasks to worker using a fair share tasks scheduling algorithm based on tasks execution time
+ - `WorkerChoiceStrategies.ROUND_ROBIN`: Submit tasks to worker in a round robin fashion
+ - `WorkerChoiceStrategies.LEAST_USED`: Submit tasks to the worker with the minimum number of running and ran tasks
+ - `WorkerChoiceStrategies.LEAST_BUSY`: Submit tasks to the worker with the minimum tasks total execution time
+ - `WorkerChoiceStrategies.WEIGHTED_ROUND_ROBIN`: Submit tasks to worker by using a weighted round robin scheduling algorithm based on tasks execution time
+ - `WorkerChoiceStrategies.INTERLEAVED_WEIGHTED_ROUND_ROBIN`: Submit tasks to worker by using an interleaved weighted round robin scheduling algorithm based on tasks execution time (experimental)
+ - `WorkerChoiceStrategies.FAIR_SHARE`: Submit tasks to worker by using a fair share tasks scheduling algorithm based on tasks execution time
- `WorkerChoiceStrategies.WEIGHTED_ROUND_ROBIN` and `WorkerChoiceStrategies.FAIR_SHARE` strategies are targeted to heavy and long tasks.
+ `WorkerChoiceStrategies.WEIGHTED_ROUND_ROBIN`, `WorkerChoiceStrategies.INTERLEAVED_WEIGHTED_ROUND_ROBIN` and `WorkerChoiceStrategies.FAIR_SHARE` strategies are targeted to heavy and long tasks.
Default: `WorkerChoiceStrategies.ROUND_ROBIN`
- `workerChoiceStrategyOptions` (optional) - The worker choice strategy options object to use in this pool.
Properties:
- - `medRunTime` (optional) - Use the tasks median run time instead of the tasks average run time in worker choice strategies.
+ - `medRunTime` (optional) - Use the tasks median runtime instead of the tasks average runtime in worker choice strategies.
- `weights` (optional) - The worker weights to use in the weighted round robin worker choice strategy: `{ 0: 200, 1: 300, ..., n: 100 }`
Default: `{ medRunTime: false }`
+- `restartWorkerOnError` (optional) - Restart worker on uncaught error in this pool.
+ Default: true
- `enableEvents` (optional) - Events emission enablement in this pool.
Default: true
- `enableTasksQueue` (optional) - Tasks queue per worker enablement in this pool.
Default: `{ concurrency: 1 }`
+ #### Thread pool specific options
+
+ - `workerOptions` (optional) - An object with the worker options. See [worker_threads](https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options) for more details.
+
+ #### Cluster pool specific options
+
+ - `env` (optional) - An object with the environment variables to pass to the worker. See [cluster](https://nodejs.org/api/cluster.html#cluster_cluster_fork_env) for more details.
+
+ - `settings` (optional) - An object with the cluster settings. See [cluster](https://nodejs.org/api/cluster.html#cluster_cluster_settings) for more details.
+
+### `pool = new FixedThreadPool/FixedClusterPool(numberOfThreads/numberOfWorkers, filePath, opts)`
+
+`numberOfThreads/numberOfWorkers` (mandatory) Number of workers for this pool
+`filePath` (mandatory) Path to a file with a worker implementation
+`opts` (optional) An object with the pool options properties described above
+
### `pool = new DynamicThreadPool/DynamicClusterPool(min, max, filePath, opts)`
`min` (mandatory) Same as FixedThreadPool/FixedClusterPool numberOfThreads/numberOfWorkers, this number of workers will be always active
`max` (mandatory) Max number of workers that this pool can contain, the new created workers will die after a threshold (default is 1 minute, you can override it in your worker implementation).
-`filePath` (mandatory) Same as FixedThreadPool/FixedClusterPool
-`opts` (optional) Same as FixedThreadPool/FixedClusterPool
+`filePath` (mandatory) Path to a file with a worker implementation
+`opts` (optional) An object with the pool options properties described above
-### `pool.execute(data)`
+### `pool.execute(data, name)`
`data` (optional) An object that you want to pass to your worker implementation
+`name` (optional) A string with the task function name that you want to execute on the worker. Default: `default`
This method is available on both pool implementations and returns a promise.
### `pool.destroy()`
### `class YourWorker extends ThreadWorker/ClusterWorker`
-`taskFunctions` (mandatory) The task function(s) that you want to execute on the worker
+`taskFunctions` (mandatory) The task function or task functions object that you want to execute on the worker
`opts` (optional) An object with these properties:
- `maxInactiveTime` (optional) - Max time to wait tasks to work on in milliseconds, after this period the new worker will die.
## Contribute
-Choose your task here [2.4.x](https://github.com/orgs/poolifier/projects/1), propose an idea, a fix, an improvement.
+Choose your task here [2.5.x](https://github.com/orgs/poolifier/projects/1), propose an idea, a fix, an improvement.
See [CONTRIBUTING](CONTRIBUTING.md) guidelines.
repositories / poolifier.git / blobdiff