Documenation and improvements

diff --git a/.github/CONTRIBUTING.MD b/.github/CONTRIBUTING.MD
new file mode 100644 (file)
index 0000000..0636dca
--- /dev/null
+++ b/.github/CONTRIBUTING.MD
@@ -0,0 +1,26 @@
+<h2 id="contribute">How to contribute</h2>
+
+[![JavaScript Style Guide](https://cdn.rawgit.com/standard/standard/master/badge.svg)](https://github.com/standard/standard)<br>
+This repo use standard js style , please use it if you want to contribute <br>
+Take tasks from todo list, develop a new feature or fix a bug and do a pull request.<br>
+Another thing that you can do to contribute is to build something on top of ring-election and link ring-election to your project <br>
+
+Please ask your PR to be merged on <strong>develop</strong> branch . <br>
+
+<strong>How to run tests</strong><br>
+
+<strong>Unit tests </strong> <br>
+
+```bash
+  npm run test
+```
+
+
+<strong> How to check if your new code is standard style </strong><br>
+```bash
+  npm run standard
+```
+<strong>How to lint your code</strong><br>
+```bash
+  npm run lint
+```
\ No newline at end of file

diff --git a/README.MD b/README.MD
index 1e661a2de4636df54c5d43100d82721e896183ba..53234a7310dfb9b0223a6d6d4f0022dbdd094eab 100644 (file)
--- a/README.MD
+++ b/README.MD
@@ -1,17 +1,33 @@
 # Node Pool :arrow_double_up: :on:
-[![JavaScript Style Guide](https://cdn.rawgit.com/standard/standard/master/badge.svg)](https://github.com/standard/standard)
+[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 [![Dependabot](https://badgen.net/dependabot/dependabot/dependabot-core/?icon=dependabot)](https://badgen.net/dependabot/dependabot/dependabot-core/?icon=dependabot)
 [![Actions Status](https://github.com/pioardi/node-pool/workflows/NodeCI/badge.svg)](https://github.com/pioardi/node-pool/actions)
 
+<h2>Contents </h2>
+<h3 align="center">
+  <a href="#installation">Installation</a>
+  <span> · </span>
+  <a href="#usage">Usage</a>
+  <span> · </span>
+  <a href="#api">API</a>
+  <span> · </span>
+  <a href="#contribute">Contribute</a>
+  <span> · </span>
+  <a href="#nv">Compatibility</a>
+  <span> · </span>
+  <a href="#license">License</a>
+</h3>
+
 Node pool contains two <a href="https://nodejs.org/api/worker_threads.html#worker_threads_worker_threads">worker-threads </a> pool implementations , you don' t have to deal with worker-threads complexity. <br>
 The first implementation is a static thread pool , with a defined number of threads that are started at creation time .<br>
-The second implementation is a dynamic thread pool with a number of threads started at creation time and other threads created when the load will increase ( with an upper limit ). <br>
+The second implementation is a dynamic thread pool with a number of threads started at creation time and other threads created when the load will increase ( with an upper limit ), the new created threads will be stopped after a threshold. <br>
+You have to implement your worker extending the ThreadWorker class<br>
+<h2 id="installation">Installation</h2>
 
-## Installation
 ```
 npm install node-pool --save
 ```
-# Usage
+<h2 id="usage">Usage</h2>
 
 You can implement a worker in a simple way , extending the class ThreadWorker : 
 
@@ -22,9 +38,10 @@ const { ThreadWorker } = require('node-pool')
 class MyWorker extends ThreadWorker {
   constructor () {
     super((data) => {
-      // this will be executed in the worker thread, the data will be received by using the execute method
+      // this will be executed in the worker thread,
+      // the data will be received by using the execute method
       return { ok: 1 }
-    })
+    }, { maxInactiveTime: 1000 * 60})
   }
 }
 module.exports = new MyWorker()
@@ -34,7 +51,7 @@ Instantiate your pool based on your needed :
 
 ```js
 'use strict'
-const { FixedThreadPool  } = require('node-pool')
+const { FixedThreadPool, DynamicThreadPool } = require('node-pool')
 
 // a fixed thread pool
 const pool = new FixedThreadPool(15,
@@ -55,14 +72,47 @@ pool.execute({}).then(res => {
 
 <strong> See examples folder for more details.</strong>
 
-## Node versions
+<h2 id="nv">Node versions</h2>
+
 You can use node version  10.x  with --experimental-worker flag, or you can use an higher version (i.e 12.x) <br>
 
-## API
+<h2 id="api">API</h2>
+
+### `pool = new FixedThreadPool(numThreads, filePath, opts)`
+`numThreads` (mandatory) Num of threads for this worker pool <br>
+`filePath` (mandatory) Path to a file with a worker implementation <br>
+`opts` (optional) An object with these properties :
+- `errorHandler` - A function that will listen for error event on each worker thread
+- `onlineHandler` - A function that will listen for online event on each worker thread
+- `exitHandler` - A function that will listen for exit event on each worker thread
+- `maxTasks` - This is just to avoid not useful warnings message, is used to set <a href="https://nodejs.org/dist/latest-v12.x/docs/api/events.html#events_emitter_setmaxlisteners_n">maxListeners</a> on event emitters ( workers are event emitters)
+
+### `pool = new DynamicThreadPool(min, max, filePath, opts)`
+`min` (mandatory) Same as FixedThreadPool numThreads , this number of threads will be always active <br>
+`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). <br>
+`filePath` (mandatory) Same as FixedThreadPool  <br>
+`opts` (optional) Same as FixedThreadPool <br>
+
+### `pool.execute(data)`
+Execute method is available on both pool implementations ( return type : Promise): <br>
+`data` (mandatory) An object that you want to pass to your worker implementation <br>
+
+### `pool.destroy()`
+Destroy method is available on both pool implementations.<br>
+This method will call the terminate method on each worker.
+
+
+### `class YourWorker extends ThreadWorker`
+`fn` (mandatory) The function that you want to execute on the worker thread <br>
+`opts` (optional) An object with these properties :
+- `maxInactiveTime` - Max time to wait tasks to work on ( in ms) , after this period the new worker threads will die.
+
+<h2 id="contribute">Contribute</h2>
+
+See guidelines [CONTRIBUTING](./.github/CONTRIBUTING.md)
 
-TODO
 
-## License
+<h2 id="license">License</h2>
 
 [MIT](https://github.com/pioardi/node-pool/blob/master/LICENSE)
 

diff --git a/lib/dynamic.js b/lib/dynamic.js
index e5a9c690b95a27bf161519cd7a6840ef01242bcf..36db0c75673ed7a70d4fe5e6e634b2754c38529f 100644 (file)
--- a/lib/dynamic.js
+++ b/lib/dynamic.js
@@ -1,6 +1,5 @@
 'use strict'
 const FixedThreadPool = require('./fixed')
-const { randomWorker } = require('./util')
 const EventEmitter = require('events')
 class MyEmitter extends EventEmitter {}
 
@@ -16,7 +15,6 @@ class DynamicThreadPool extends FixedThreadPool {
     *
     * @param {Number} min  Min number of threads that will be always active
     * @param {Number} max  Max number of threads that will be active
-    * @param {Object} an object with possible options for example maxConcurrency
   */
   constructor (min, max, filename, opts) {
     super(min, filename, opts)
@@ -39,7 +37,7 @@ class DynamicThreadPool extends FixedThreadPool {
     } else {
       if (this.workers.length === this.max) {
         this.emitter.emit('FullPool')
-        return randomWorker(this.tasks)
+        return super._chooseWorker()
       }
       // all workers are busy create a new worker
       const worker = this._newWorker()

diff --git a/lib/util.js b/lib/util.js
index bac53ec46c75c78cbe9d7b8b31a60fd6d8d2bd64..70a50744d684ef562eeae9ca9a5902feb5c27f72 100644 (file)
--- a/lib/util.js
+++ b/lib/util.js
@@ -11,8 +11,3 @@ const uuid = require('uuid/v4')
 module.exports.generateID = () => {
   return uuid()
 }
-
-module.exports.randomWorker = (collection) => {
-  const keys = Array.from(collection.keys())
-  return keys[Math.floor(Math.random() * keys.length)]
-}

diff --git a/lib/workers.js b/lib/workers.js
index ee03778d47d603711ee16e6b994e5955a49855d7..c192f1812c4a08cf8aa9cdc305a397c0740abdb5 100644 (file)
--- a/lib/workers.js
+++ b/lib/workers.js
@@ -37,6 +37,7 @@ class ThreadWorker extends AsyncResource {
       } else if (value.kill) {
         // here is time to kill this thread, just clearing the interval
         clearInterval(this.interval)
+        this.emitDestroy()
       }
     })
   }

diff --git a/package.json b/package.json
index ca55edc64dbcca5c234d89bf9c81bd8795774579..cfe41cbf540c80c65eaf9534ab8683e7901e1642 100644 (file)
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
   "main": "index.js",
   "scripts": {
     "build": "npm install",
-    "test": "standard && nyc mocha --experimental-worker --exit --timeout 10000 **/*test.js ",
+    "test": "standard && nyc mocha --experimental-worker --exit --timeout 10000 tests/*test.js ",
     "demontest": "nodemon --exec \"npm test\"",
     "coverage": "nyc report --reporter=text-lcov --timeout 5000 **/*test.js | coveralls",
     "standard-verbose": "npx standard --verbose",

diff --git a/tests/testWorker.js b/tests/testWorker.js
index d69230453564f04e0f36b0ea81cc3bf84d3f4b51..60e41d7941150df5e72bcebf0e75416e00690fb6 100644 (file)
--- a/tests/testWorker.js
+++ b/tests/testWorker.js
@@ -5,14 +5,14 @@ const { isMainThread } = require('worker_threads')
 class MyWorker extends ThreadWorker {
   constructor () {
     super((data) => {
-      for (let i = 0; i <= 100; i++) {
+      for (let i = 0; i <= 50; i++) {
         const o = {
           a: i
         }
         JSON.stringify(o)
       }
       return isMainThread
-    }, { maxInactiveTime: 1000 })
+    }, { maxInactiveTime: 500 })
   }
 }
 

diff --git a/tests/util.test.js b/tests/util.test.js
index 0cba02ce65fdcd1c6448d0015373a2a1e52067b6..71782ea16b25769755be0ee68138284015e28cb5 100644 (file)
--- a/tests/util.test.js
+++ b/tests/util.test.js
@@ -1,5 +1,5 @@
 const expect = require('expect')
-const { generateID, randomWorker } = require('../lib/util')
+const { generateID } = require('../lib/util')
 
 describe('Utility Tests ', () => {
   it('Generate an id', () => {
@@ -7,14 +7,4 @@ describe('Utility Tests ', () => {
     expect(res).toBeTruthy()
     expect(typeof res).toBe('string')
   })
-
-  it('Choose a random worker', () => {
-    const input = new Map()
-    input.set(1, 1)
-    input.set(2, 2)
-    input.set(3, 3)
-    const worker = randomWorker(input)
-    expect(worker).toBeTruthy()
-    expect(Array.from(input.keys()).includes(worker)).toBeTruthy()
-  })
 })