Merge branch 'feat/custom_balancer' into feat/decouple-events

piscinajs · Sep 20, 2024 · 2fb79f2 · 2fb79f2
2 parents 2f374d6 + f329b81
commit 2fb79f2
Show file tree

Hide file tree

Showing 17 changed files with 1,707 additions and 6,877 deletions.
diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml
@@ -0,0 +1,29 @@
+name: Backport
+on:
+  pull_request_target:
+    types:
+      - closed
+      - labeled
+
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  backport:
+    runs-on: ubuntu-latest
+    if: >
+      github.event.pull_request.merged
+      && (
+        github.event.action == 'closed'
+        || (
+          github.event.action == 'labeled'
+          && contains(github.event.label.name, 'backport')
+        )
+      )
+    name: Backport
+    steps:
+      - name: Backport
+        uses: tibdex/backport@v2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,54 @@
+name: 'Documentation'
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    permissions:
+      contents: read
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Use Node.js LTS
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+          cache: 'yarn'
+          cache-dependency-path: docs/package.json
+
+      - name: Install Dependencies
+        run: |
+          cd docs
+          yarn install --frozen-lockfile
+
+      - name: build
+        run: |
+          cd docs
+          yarn build
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    permissions:
+      pages: write
+      id-token: write
+    name: Deploy to GH Pages
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml
@@ -1,9 +1,9 @@
 on:
   push:
     branches:
-     - current
-     - next
-     - 'v*'
+      - current
+      - next
+      - 'v*'
   pull_request:
 
 name: CI

diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
@@ -22,5 +22,5 @@ jobs:
             days-before-pr-stale: 30
             days-before-issue-close: 5
             days-before-pr-close: 10
-            exempt-issue-labels: never-stale,v4.x,v5.x
-            exempt-pr-labels: wip,v4.x,v5.x
+            exempt-issue-labels: never-stale,v4.x,v5.x,good-first-issue,help-wanted,semver-major,semver-minor
+            exempt-pr-labels: wip,never-stale,v4.x,v5.x,semver-major,semver-minor
diff --git a/README.md b/README.md
@@ -17,10 +17,14 @@
 
 Written in TypeScript.
 
-For Node.js 16.x and higher.
+For Node.js 18.x and higher.
 
 [MIT Licensed][].
 
+## Documentation
+
+- [Website](https://piscinajs.github.io/piscina/)
+
 ## Piscina API
 
 ### Example
@@ -339,9 +343,9 @@ This class extends [`EventEmitter`][] from Node.js.
     alternative implementation. See [Custom Task Queues][] for additional detail.
   * `niceIncrement`: (`number`) An optional value that decreases priority for
     the individual threads, i.e. the higher the value, the lower the priority
-    of the Worker threads. This value is only used on Linux and requires the
-    optional [`nice-napi`][] module to be installed.
-    See [`nice(2)`][] for more details.
+    of the Worker threads. This value is used on Unix/Windows and requires the
+    optional [`@napi-rs/nice`][https://www.npmjs.com/package/@napi-rs/nice] module to be installed.
+    See [`nice(2)`][https://linux.die.net/man/2/nice] for more details.
   * `trackUnmanagedFds`: (`boolean`) An optional setting that, when `true`, will
     cause Workers to track file descriptors managed using `fs.open()` and
     `fs.close()`, and will close them automatically when the Worker exits.
@@ -818,8 +822,8 @@ are no one set of options that are going to work best.
 
 On Linux systems that support [`nice(2)`][], Piscina is capable of setting
 the priority of every worker in the pool. To use this mechanism, an additional
-optional native addon dependency (`nice-napi`, `npm i nice-napi`) is required.
-Once [`nice-napi`][] is installed, creating a `Piscina` instance with the
+optional native addon dependency (`@napi-rs/nice`, `npm i @napi-rs/nice`) is required.
+Once [`@napi-rs/nice`][] is installed, creating a `Piscina` instance with the
 `niceIncrement` configuration option will set the priority for the pool:
 
 ```js
@@ -853,107 +857,14 @@ documentation that threads are being used. It would be ideal if those
 would make it possible for users to provide an existing `Piscina` instance
 as a configuration option in lieu of always creating their own.
 
-
-## Release Notes
-
-### 4.1.0
-
-#### Features
-
-* add `needsDrain` property ([#368](https://github.com/piscinajs/piscina/issues/368)) ([2d49b63](https://github.com/piscinajs/piscina/commit/2d49b63368116c172a52e2019648049b4d280162))
-* correctly handle process.exit calls outside of a task ([#361](https://github.com/piscinajs/piscina/issues/361)) ([8e6d16e](https://github.com/piscinajs/piscina/commit/8e6d16e1dc23f8bb39772ed954f6689852ad435f))
-
-
-#### Bug Fixes
-
-* Fix types for TypeScript 4.7 ([#239](https://github.com/piscinajs/piscina/issues/239)) ([a38fb29](https://github.com/piscinajs/piscina/commit/a38fb292e8fcc45cc20abab8668f82d908a24dc0))
-* use CJS imports ([#374](https://github.com/piscinajs/piscina/issues/374)) ([edf8dc4](https://github.com/piscinajs/piscina/commit/edf8dc4f1a19e9b49e266109cdb70d9acc86f3ca))
-
-### 4.0.0
-
-* Drop Node.js 14.x support
-* Add Node.js 20.x to CI
-
-### 3.2.0
-
-* Adds a new `PISCINA_DISABLE_ATOMICS` environment variable as an alternative way of
-  disabling Piscina's internal use of the `Atomics` API. (https://github.com/piscinajs/piscina/pull/163)
-* Fixes a bug with transferable objects. (https://github.com/piscinajs/piscina/pull/155)
-* Fixes CI issues with TypeScript. (https://github.com/piscinajs/piscina/pull/161)
-
-### 3.1.0
-
-* Deprecates `piscina.runTask()`; adds `piscina.run()` as an alternative.
-  https://github.com/piscinajs/piscina/commit/d7fa24d7515789001f7237ad6ae9ad42d582fc75
-* Allows multiple exported handler functions from a single file.
-  https://github.com/piscinajs/piscina/commit/d7fa24d7515789001f7237ad6ae9ad42d582fc75
-
-### 3.0.0
-
-* Drops Node.js 10.x support
-* Updates minimum TypeScript target to ES2019
-
-### 2.1.0
-
-* Adds name property to indicate `AbortError` when tasks are
-  canceled using an `AbortController` (or similar)
-* More examples
-
-### 2.0.0
-
-* Added unmanaged file descriptor tracking
-* Updated dependencies
-
-### 1.6.1
-
-* Bug fix: Reject if AbortSignal is already aborted
-* Bug Fix: Use once listener for abort event
-
-### 1.6.0
-
-* Add the `niceIncrement` configuration parameter.
-
-### 1.5.1
-
-* Bug fixes around abortable task selection.
-
-### 1.5.0
-
-* Added `Piscina.move()`
-* Added Custom Task Queues
-* Added utilization metric
-* Wait for workers to be ready before considering them as candidates
-* Additional examples
-
-### 1.4.0
-
-* Added `maxQueue = 'auto'` to autocalculate the maximum queue size.
-* Added more examples, including an example of implementing a worker
-  as a Node.js native addon.
-
-### 1.3.0
-
-* Added the `'drain'` event
-
-### 1.2.0
-
-* Added support for ESM and file:// URLs
-* Added `env`, `argv`, `execArgv`, and `workerData` options
-* More examples
-
-### 1.1.0
-
-* Added support for Worker Thread `resourceLimits`
-
-### 1.0.0
-
-* Initial release!
-
 ## The Team
 
 * James M Snell <[email protected]>
 * Anna Henningsen <[email protected]>
 * Matteo Collina <[email protected]>
+* Rafael Gonzaga <[email protected]>
+* Robert Nagy <[email protected]>
+* Carlos Fuentes <[email protected]>
 
 ## Acknowledgements
 
@@ -964,7 +875,7 @@ Piscina development is sponsored by [NearForm Research][].
 [`postMessage`]: https://nodejs.org/api/worker_threads.html#worker_threads_port_postmessage_value_transferlist
 [`examples/task-queue`]: https://github.com/jasnell/piscina/blob/master/examples/task-queue/index.js
 [`nice(2)`]: https://linux.die.net/man/2/nice
-[`nice-napi`]: https://npmjs.org/package/nice-napi
+[`@napi-rs/nice`]: https://npmjs.org/package/@napi-rs/nice
 [`runTime`]: #property-runtime-readonly
 [Custom Task Queues]: #custom_task_queues
 [ES modules]: https://nodejs.org/api/esm.html

diff --git a/docs/docs/advanced-topics/performance.mdx b/docs/docs/advanced-topics/performance.mdx
@@ -83,18 +83,21 @@ are no one set of options that are going to work best.
 
 ### Thread priority on Linux systems
 
-On Linux systems that support [`nice(2)`][], Piscina is capable of setting
+On Unix systems that support [`nice(2)`][https://linux.die.net/man/2/nice] and Windows, Piscina is capable of setting
 the priority of every worker in the pool. To use this mechanism, an additional
-optional native addon dependency (`nice-napi`, `npm i nice-napi`) is required.
-Once [`nice-napi`][] is installed, creating a `Piscina` instance with the
-`niceIncrement` configuration option will set the priority for the pool:
+optional native addon dependency (`@napi-rs/nice`, `npm i @napi-rs/nice`) is required.
+Once [`@napi-rs/nice`][https://www.npmjs.com/package/@napi-rs/nice] is installed, creating a `Piscina`instance with the`niceIncrement` configuration option will set the priority for the pool:
 
 ```js
-const Piscina = require('piscina');
+const Piscina = require('piscina')
+const { WindowsThreadPriority } = require('@napi-rs/nice')
 const pool = new Piscina({
   worker: '/absolute/path/to/worker.js',
-  niceIncrement: 20
-});
+  niceIncrement:
+    process.platform !== 'win32'
+      ? 20
+      : WindowsThreadPriority.ThreadPriorityHighest,
+})
 ```
 
 The higher the `niceIncrement`, the lower the CPU scheduling priority will be

diff --git a/docs/docs/api-reference/class.md b/docs/docs/api-reference/class.md
@@ -79,9 +79,9 @@ This class extends [`EventEmitter`](https://nodejs.org/api/events.html) from Nod
     alternative implementation. See [Custom Task Queues](https://github.com/piscinajs/piscina#custom_task_queues) for additional detail.
   - `niceIncrement`: (`number`) An optional value that decreases priority for
     the individual threads, i.e. the higher the value, the lower the priority
-    of the Worker threads. This value is only used on Linux and requires the
-    optional [`nice-napi`](https://npmjs.org/package/nice-napi) module to be installed.
-    See [`nice(2)`](https://linux.die.net/man/2/nice) for more details.
+    of the Worker threads. This value is used on Unix/Windows and requires the
+    optional [`@napi-rs/nice`](https://npmjs.org/package/@napi-rs/nice) module to be installed.
+    See [`nice(2)`](https://linux.die.net/man/2/nice) and [`SetThreadPriority`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadpriority) for more details.
   - `trackUnmanagedFds`: (`boolean`) An optional setting that, when `true`, will
     cause Workers to track file descriptors managed using `fs.open()` and
     `fs.close()`, and will close them automatically when the Worker exits.

diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -8,15 +8,15 @@ const config: Config = {
   favicon: 'img/favicon.ico',
 
   // Set the production url of your site here
-  url: 'https://your-docusaurus-site.example.com',
+  url: 'https://piscinajs.github.io',
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: '/',
+  baseUrl: '/piscina/',
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
-  organizationName: 'Piscina', // Usually your GitHub org/user name.
-  projectName: 'piscina.js', // Usually your repo name.
+  organizationName: 'Piscinajs', // Usually your GitHub org/user name.
+  projectName: 'piscina', // Usually your repo name.
 
   onBrokenLinks: 'throw',
   onBrokenMarkdownLinks: 'warn',