X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=README.md;h=0f7ba475c64b468f8ba0861d80bb377923721905;hb=231e02698fcad3821ef42aa56f3425375bd6676d;hp=52650f3e72b10aa40fc4bd427206e634ca836ad1;hpb=5a5fc090d6f7eb9248df1ba5c0ff4d001461b6d4;p=poolifier.git diff --git a/README.md b/README.md index 52650f3e..0f7ba475 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ Please consult our [general guidelines](#general-guidance). - 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: @@ -149,11 +150,9 @@ 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 @@ -161,13 +160,14 @@ Node versions >= 16.14.x are supported. - `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.LEAST_USED`: Submit tasks to the least used worker - - `WorkerChoiceStrategies.LEAST_BUSY`: Submit tasks to the least 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. @@ -178,6 +178,8 @@ Node versions >= 16.14.x are supported. 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. @@ -190,16 +192,33 @@ Node versions >= 16.14.x are supported. 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()` @@ -209,7 +228,7 @@ This method will call the terminate method on each worker. ### `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. @@ -264,7 +283,7 @@ But in general, **always profile your application**. ## 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.