From 7a7ad378d64a4a4e69d0862d5f077289d3111e65 Mon Sep 17 00:00:00 2001 From: PP Date: Tue, 14 Mar 2023 10:53:36 +0800 Subject: [PATCH] doc: update readme --- LICENSE | 21 +++++++++ README.md | 131 +++++++++++++++++++++++++++++++++++++-------------- package.json | 10 ++-- 3 files changed, 123 insertions(+), 39 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..27ca760 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) [year] [fullname] + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index be69079..f2ff4af 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,13 @@ -# node-threads-pool -[![David deps][david-image]][david-url] +# Node-Threads-Pool + +Node-Threads-Pool is a Node.js library that provides a simple and efficient way to execute tasks in child threads. It creates a pool of threads that can be used to parallelize the execution of CPU-intensive tasks, making it possible to take advantage of multi-core processors. + +The library is designed to be easy to use and to integrate with existing projects. It provides a simple API that allows you to create a thread pool and run tasks in child threads, and it also supports passing data between threads. + [![node version][node-image]][node-url] [![npm download][download-image]][download-url] [![npm license][license-image]][download-url] -[david-image]: https://img.shields.io/david/pengxigua/node-threads-pool.svg?style=flat-square [david-url]: https://david-dm.org/pengxigua/node-threads-pool [node-image]: https://img.shields.io/badge/node.js-%3E=_12-green.svg?style=flat-square [node-url]: http://nodejs.org/download/ @@ -12,73 +15,125 @@ [download-url]: https://npmjs.org/package/node-threads-pool [license-image]: https://img.shields.io/npm/l/node-threads-pool.svg -# Installation + +Installation +------------ + +You can install Node-Threads-Pool using NPM: + ``` npm install node-threads-pool ``` -# Usage +Usage +----- + +To use Node-Threads-Pool, you need to create an instance of the `Eve` class, which represents the thread pool. + +```javascript +// main.js + +const { Eve } = require('node-threads-pool'); -``` const tp = new Eve(filename, threadCount); -``` -+ @param {String} filename: The path to the Worker’s main script or module. [Detail description](https://nodejs.org/docs/latest-v12.x/api/worker_threads.html#worker_threads_new_worker_filename_options) -+ @param {Number} threadCount: The number of threads in the thread pool -``` -tp.run(workerData); -``` -+ @param {Object} workerData: Any JavaScript value that will be cloned and made available as require('worker_threads').workerData. [Detail description](https://nodejs.org/docs/latest-v12.x/api/worker_threads.html#worker_threads_new_worker_filename_options) -+ @return {Promise} The result ``` -const thread = new Thread(func); -``` -+ @param {Function} func: some code -# Example +The `Eve` constructor takes two arguments: the path to the worker script and the number of threads to create. The `run` method takes one argument, which is the data to be passed to the worker script. + -## 1. Open 20 threads to perform some calculations +* `filename`: The path to the worker's main script or module. See [the Node.js documentation](https://nodejs.org/docs/latest-v12.x/api/worker_threads.html#worker_threads_new_worker_filename_options) for more details. +* `threadCount`: The number of threads in the thread pool. +To run a task in a worker thread, use the `run` method: + +```javascript // main.js + +tp.run(workerData) + .then(result => { + // handle the result + }) + .catch(err => { + // handle the error + }) +``` + +You can create a new thread directly using the `Thread` class: + +```javascript +// thread.js + +const {Thread} = require('node-threads-pool'); + +new Thread(async (data) => { + // Do some work with data + const result = await doSomething(data); + return result; +}); ``` -const {Eve} = require('node-threads-pool'); -const tp = new Eve('thread.js', 20); +The `Thread` constructor takes a single argument, which is the function to be executed in the child thread. The function should return a Promise that resolves with the result of the computation. + +Example +------- + +Here are some examples of how to use Node Threads Pool. + +### Example 1: Running calculations in 20 threads + +This example shows how to create a pool of 20 worker threads to perform some calculations: + +```javascript +// main.js +const os = require('os'); +const { Eve } = require('node-threads-pool'); + +const tp = new Eve('thread.js', os.cpus().length); + module.exports = async (data) => { return await tp.run(data); }; -``` + // thread.js -``` -const {Thread} = require('node-threads-pool'); +const { Thread } = require('node-threads-pool'); const thread = new Thread(async (data) => { return await doSomething(data); }); ``` -Or write to the same JS file -// main.js -``` -const {Eve, Thread, isMainThread} = require('node-threads-pool'); +Alternatively, you can write to the same JS file: + +```javascript +// main.js +const { Eve, Thread, isMainThread } = require('node-threads-pool'); +const os = require('os'); if(isMainThread) { - const tp = new Eve(__filename, 20); - module.exports = async function(data) { + + const tp = new Eve('thread.js', os.cpus().length); + + module.exports = async (data) => { return await tp.run(data); }; + } else { + new Thread(async (data) => { return await doSomething(data); }); + } ``` -## 2. Render PUG to HTML -``` +### Example 2: Rendering Pug to HTML + +This example shows how to use Node Threads Pool to render Pug templates to HTML: +```javascript const pug = require('pug'); const os = require('os'); const {Eve, Thread, isMainThread} = require('node-threads-pool'); @@ -98,9 +153,15 @@ if(!isMainThread) { }); }; } - ``` -## Test + +Test +----- ``` npm run eve -``` \ No newline at end of file +``` + +License +------- + +Node-Threads-Pool is licensed under the MIT License. (see [LICENSE](https://github.com/PxGo/node-threads-pool/blob/main/LICENSE)) diff --git a/package.json b/package.json index 528f549..ca65bc9 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "node-threads-pool", - "version": "2.0.3", - "description": "worker threads pool", + "version": "2.0.4", + "description": "Node-Threads-Pool is a tool for creating thread pools in Node.js, making it easy to implement efficient parallel computing. With Node-Threads-Pool, you can easily create and manage multiple threads, allocate tasks to worker threads in the thread pool, and maximize CPU resources to improve application performance.", "main": "index.js", "scripts": { "eve": "node ./example/eve-example.js", @@ -9,15 +9,17 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/pengxiguaa/node-threads-pool.git" + "url": "git+https://github.com/pxgo/node-threads-pool.git" }, "keywords": [ + "worker", + "thread", "workers", "workers_threads", "threads", "pool" ], - "author": "pengxiguaa", + "author": "PxGo", "license": "MIT", "bugs": { "url": "https://github.com/pengxiguaa/node-threads-pool/issues"