Primeiro commit do projeto Angular
This commit is contained in:
+39
@@ -0,0 +1,39 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
slug: /
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
Piscina.js is a powerful Node.js worker pool library that allows you to efficiently run CPU-intensive tasks in parallel using worker threads. It provides a simple API for offloading computationally expensive tasks to a pool of worker threads, thereby improving the performance and scalability of your Node.js applications.
|
||||
|
||||
## Why Piscina?
|
||||
|
||||
In the early days of worker threads, the Node.js core team encountered an issue where a user's application was spinning up thousands of concurrent worker threads, leading to performance issues. While this specific issue helped identify a minor memory leak in the worker implementation, it highlighted a broader problem: the misuse of worker threads due to a lack of understanding.
|
||||
|
||||
While worker threads have matured and their usage has become more widespread, there is still a need for better examples and education around their correct usage. This realization led to the creation of Piscina, an open-source project sponsored by [NearForm Research](https://www.nearform.com/), focused on providing guidance and best practices for using worker threads in Node.js applications.
|
||||
|
||||
With worker threads now a well-established feature in Node.js, Piscina aims to bridge the gap between the potential of worker threads and their practical implementation.
|
||||
|
||||
## Key features
|
||||
|
||||
✔ Fast communication between threads\
|
||||
✔ Covers both fixed-task and variable-task scenarios\
|
||||
✔ Supports flexible pool sizes\
|
||||
✔ Proper async tracking integration\
|
||||
✔ Tracking statistics for run and wait times\
|
||||
✔ Cancellation Support\
|
||||
✔ Supports enforcing memory resource limits\
|
||||
✔ Supports CommonJS, ESM, and TypeScript\
|
||||
✔ Custom task queues\
|
||||
✔ Optional CPU scheduling priorities on Linux
|
||||
|
||||
## Sponsors
|
||||
|
||||
Looking to support the development of Piscina? Consider sponsoring us on [Open Collective](https://opencollective.com/piscinajs). We appreciate all levels of support!
|
||||
|
||||
### Bronze Sponsors
|
||||
|
||||
<a href="https://www.lambdatest.com/?utm_source=piscinajs&utm_medium=sponsor" target="_blank">
|
||||
<img src="https://www.lambdatest.com/blue-logo.png" style={{ verticalAlign: "middle" }} width="250" height="45" />
|
||||
</a>
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
---
|
||||
id: API Overview
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
| API | Description |
|
||||
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Class: `Piscina`** | This class extends [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) from Node.js. |
|
||||
| **Constructor: `new Piscina([options])`** | Creates a new instance of the `Piscina` class. [List of available options](./class.md) |
|
||||
| **Method: `run(task[, options])`** | Schedules a task to be run on a Worker thread. |
|
||||
| **Method: `runTask(task[, transferList][, filename][, abortSignal])`** | **Deprecated** -- Use `run(task, options)` instead. |
|
||||
| **Method: `destroy()`** | Stops all Workers and rejects all `Promises` for pending tasks. |
|
||||
| **Method: `close([options])`** | Stops all Workers gracefully. |
|
||||
| **Event: `'error'`** | Emitted when uncaught exceptions occur inside Worker threads or unexpected messages are sent from Worker threads. |
|
||||
| **Event: `'drain'`** | Emitted whenever the `queueSize` reaches `0`. |
|
||||
| **Event: `'needsDrain'`** | Triggered once the total capacity of the pool is exceeded by the number of tasks enqueued that are pending execution. |
|
||||
| **Event: `'message'`** | Emitted whenever a message is received from a worker thread. |
|
||||
| **Property: `completed` (readonly)** | The current number of completed tasks. |
|
||||
| **Property: `duration` (readonly)** | The length of time (in milliseconds) since this `Piscina` instance was created. |
|
||||
| **Property: `options` (readonly)** | A copy of the options that are currently being used by this instance. |
|
||||
| **Property: `runTime` (readonly)** | A histogram summary object summarizing the collected run times of completed tasks. |
|
||||
| **Property: `threads` (readonly)** | An Array of the `Worker` instances used by this pool. |
|
||||
| **Property: `queueSize` (readonly)** | The current number of tasks waiting to be assigned to a Worker thread. |
|
||||
| **Property: `needsDrain` (readonly)** | Boolean value that specifies whether the capacity of the pool has been exceeded by the number of tasks submitted. |
|
||||
| **Property: `utilization` (readonly)** | A point-in-time ratio comparing the approximate total mean run time of completed tasks to the total runtime capacity of the pool. |
|
||||
| **Property: `waitTime` (readonly)** | A histogram summary object summarizing the collected times tasks spent waiting in the queue. |
|
||||
| **Static Property: `isWorkerThread` (readonly)** | Is `true` if this code runs inside a `Piscina` threadpool as a Worker. |
|
||||
| **Static Property: `version` (readonly)** | Provides the current version of this library as a semver string. |
|
||||
| **Static Method: `move(value)`** | By default, any value returned by a worker function will be cloned when returned back to the Piscina pool, even if that object is capable of being transferred. The `Piscina.move()` method can be used to wrap and mark transferable values such that they will be transferred rather than cloned. |
|
||||
| **Interface: `Transferable`** | Objects may implement the `Transferable` interface to create their own custom transferable objects. |
|
||||
+329
@@ -0,0 +1,329 @@
|
||||
---
|
||||
id: Instance
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
## Class: `Piscina`
|
||||
|
||||
Piscina works by creating a pool of Node.js Worker Threads to which
|
||||
one or more tasks may be dispatched. Each worker thread executes a
|
||||
single exported function defined in a separate file. Whenever a
|
||||
task is dispatched to a worker, the worker invokes the exported
|
||||
function and reports the return value back to Piscina when the
|
||||
function completes.
|
||||
|
||||
This class extends [`EventEmitter`](https://nodejs.org/api/events.html) from Node.js.
|
||||
|
||||
### Constructor: `new Piscina([options])`
|
||||
|
||||
- The following optional configuration is supported:
|
||||
|
||||
- `filename`: (`string | null`) Provides the default source for the code that
|
||||
runs the tasks on Worker threads. This should be an absolute path or an
|
||||
absolute `file://` URL to a file that exports a JavaScript `function` or
|
||||
`async function` as its default export or `module.exports`. [ES modules](https://nodejs.org/api/esm.html)
|
||||
are supported.
|
||||
- `name`: (`string | null`) Provides the name of the default exported worker
|
||||
function. The default is `'default'`, indicating the default export of the
|
||||
worker module.
|
||||
- `minThreads`: (`number`) Sets the minimum number of threads that are always
|
||||
running for this thread pool. The default is the number provided by [`os.availableParallelism`](https://nodejs.org/api/os.html#osavailableparallelism).
|
||||
- `maxThreads`: (`number`) Sets the maximum number of threads that are
|
||||
running for this thread pool. The default is the number provided by [`os.availableParallelism`](https://nodejs.org/api/os.html#osavailableparallelism) \* 1.5.
|
||||
- `idleTimeout`: (`number`) A timeout in milliseconds that specifies how long
|
||||
a `Worker` is allowed to be idle, i.e. not handling any tasks, before it is
|
||||
shut down. By default, this is immediate. If `Infinity` is passed as the value,
|
||||
the `Worker` never shuts down.
|
||||
:::info
|
||||
The default `idleTimeout` can lead to some performance loss in the application because of the overhead involved with stopping and starting new worker threads. To improve performance, try setting the `idleTimeout` explicitly.
|
||||
:::
|
||||
:::info
|
||||
Be careful when when setting `idleTimeout` to `Infinity`, as this will prevent the worker from shutting down, even when idle, potentially leading to resource overuse.
|
||||
:::
|
||||
- `maxQueue`: (`number` | `string`) The maximum number of tasks that may be
|
||||
scheduled to run, but not yet running due to lack of available threads, at
|
||||
a given time. By default, there is no limit. The special value `'auto'`
|
||||
may be used to have Piscina calculate the maximum as the square of `maxThreads`.
|
||||
When `'auto'` is used, the calculated `maxQueue` value may be found by checking
|
||||
the [`options.maxQueue`](#property-options-readonly) property.
|
||||
- `concurrentTasksPerWorker`: (`number`) Specifies how many tasks can share
|
||||
a single Worker thread simultaneously. The default is `1`. This generally
|
||||
only makes sense to specify if there is some kind of asynchronous component
|
||||
to the task. Keep in mind that Worker threads are generally not built for
|
||||
handling I/O in parallel.
|
||||
- `atomics`: (`sync` | `async` | `disabled`) Use the [`Atomics`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Atomics) API for faster communication
|
||||
between threads. This is on by default. You can disable `Atomics` globally by
|
||||
setting the environment variable `PISCINA_DISABLE_ATOMICS` to `1` .
|
||||
If `atomics` is `sync`, it will cause to pause threads (stoping all execution)
|
||||
between tasks. Ideally, threads should wait for all operations to finish before
|
||||
returning control to the main thread (avoid having open handles within a thread). If still want to have the possibility
|
||||
of having open handles or handle asynchrnous tasks, you can set the environment variable `PISCINA_ENABLE_ASYNC_ATOMICS` to `1` or setting `options.atomics` to `async`.
|
||||
|
||||
:::info
|
||||
**Note**: The `async` mode comes with performance penalties and can lead to undesired behaviour if open handles are not tracked correctly.
|
||||
Workers should be designed to wait for all operations to finish before returning control to the main thread, if any background operations are still running
|
||||
`async` can be of help (e.g. for cache warming, etc).
|
||||
:::
|
||||
|
||||
- `resourceLimits`: (`object`) See [Node.js new Worker options](https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options)
|
||||
- `maxOldGenerationSizeMb`: (`number`) The maximum size of each worker threads
|
||||
main heap in MB.
|
||||
- `maxYoungGenerationSizeMb`: (`number`) The maximum size of a heap space for
|
||||
recently created objects.
|
||||
- `codeRangeSizeMb`: (`number`) The size of a pre-allocated memory range used
|
||||
for generated code.
|
||||
- `stackSizeMb` : (`number`) The default maximum stack size for the thread.
|
||||
Small values may lead to unusable Worker instances. Default: 4
|
||||
- `env`: (`object`) If set, specifies the initial value of `process.env` inside
|
||||
the worker threads. See [Node.js new Worker options](https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options) for details.
|
||||
- `argv`: (`any[]`) List of arguments that will be stringified and appended to
|
||||
`process.argv` in the worker. See [Node.js new Worker options](https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options) for details.
|
||||
- `execArgv`: (`string[]`) List of Node.js CLI options passed to the worker.
|
||||
See [Node.js new Worker options](https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options) for details.
|
||||
- `workerData`: (`any`) Any JavaScript value that can be cloned and made
|
||||
available as `require('piscina').workerData`. See [Node.js new Worker options](https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options)
|
||||
for details. Unlike regular Node.js Worker Threads, `workerData` must not
|
||||
specify any value requiring a `transferList`. This is because the `workerData`
|
||||
will be cloned for each pooled worker.
|
||||
- `taskQueue`: (`TaskQueue`) By default, Piscina uses a first-in-first-out
|
||||
queue for submitted tasks. The `taskQueue` option can be used to provide an
|
||||
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 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.
|
||||
Defaults to `true`. (This option is only supported on Node.js 12.19+ and
|
||||
all Node.js versions higher than 14.6.0).
|
||||
- `closeTimeout`: (`number`) An optional time (in milliseconds) to wait for the pool to
|
||||
complete all in-flight tasks when `close()` is called. The default is `30000`
|
||||
- `recordTiming`: (`boolean`) By default, run and wait time will be recorded
|
||||
for the pool. To disable, set to `false`.
|
||||
- `workerHistogram`: (`boolean`) By default `false`. It will hint the Worker pool to record statistics for each individual Worker
|
||||
- `loadBalancer`: ([`PiscinaLoadBalancer`](#piscinaloadbalancer)) By default, Piscina uses a least-busy algorithm. The `loadBalancer`
|
||||
option can be used to provide an alternative implementation. See [Custom Load Balancers](../advanced-topics/loadbalancer.mdx) for additional detail.
|
||||
|
||||
:::caution
|
||||
Use caution when setting resource limits. Setting limits that are too low may
|
||||
result in the `Piscina` worker threads being unusable.
|
||||
:::
|
||||
|
||||
:::info
|
||||
**Note on Explicit Resource Management**: Piscina does has support for `Symbol.dispose` and `Symbol.asyncDispose` for explicit resource management for its usage with the `using` keyword.
|
||||
This is only avaiable on Node.js 24 and higher.
|
||||
|
||||
For more information, see the [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management).
|
||||
:::
|
||||
|
||||
## `PiscinaHistogram`
|
||||
|
||||
The `PiscinaHistogram` allows you to access the histogram data for the pool of worker threads.
|
||||
It can be reset upon request in case of a need to clear the data.
|
||||
|
||||
**Example**:
|
||||
|
||||
```js
|
||||
import { Piscina } from 'piscina';
|
||||
|
||||
const pool = new Piscina({
|
||||
filename: resolve(__dirname, 'path/to/worker.js'),
|
||||
});
|
||||
|
||||
const firstBatch = [];
|
||||
|
||||
for (let n = 0; n < 10; n++) {
|
||||
firstBatch.push(pool.run('42'));
|
||||
}
|
||||
|
||||
await Promise.all(firstBatch);
|
||||
|
||||
console.log(pool.histogram.runTime); // Print run time histogram summary
|
||||
console.log(pool.histogram.waitTime); // Print wait time histogram summary
|
||||
|
||||
// If in need to reset the histogram data for a new set of tasks
|
||||
pool.histogram.resetRunTime();
|
||||
pool.histogram.resetWaitTime();
|
||||
|
||||
const secondBatch = [];
|
||||
|
||||
for (let n = 0; n < 10; n++) {
|
||||
secondBatch.push(pool.run('42'));
|
||||
}
|
||||
|
||||
await Promise.all(secondBatch);
|
||||
|
||||
// The histogram data will only contain the data for the second batch of tasks
|
||||
console.log(pool.histogram.runTime);
|
||||
console.log(pool.histogram.waitTime);
|
||||
```
|
||||
|
||||
### Interface: `PiscinaLoadBalancer`
|
||||
|
||||
- `runTime`: (`PiscinaHistogramSummary`) Run Time Histogram Summary. Time taken to execute a task.
|
||||
- `waitTime`: (`PiscinaHistogramSummary`) Wait Time Histogram Summary. Time between a task being submitted and the task starting to run.
|
||||
|
||||
> **Note**: The histogram data is only available if `recordTiming` is set to `true`.
|
||||
|
||||
```ts
|
||||
type PiscinaHistogram = {
|
||||
runTime: PiscinaHistogramSummary;
|
||||
waitTime: PiscinaHistogramSummary;
|
||||
resetRunTime(): void; // Reset Run Time Histogram
|
||||
resetWaitTime(): void; // Reset Wait Time Histogram
|
||||
```
|
||||
|
||||
### Interface: `PiscinaHistogramSummary`
|
||||
|
||||
```ts
|
||||
type PiscinaHistogramSummary = {
|
||||
average: number;
|
||||
mean: number;
|
||||
stddev: number;
|
||||
min: number;
|
||||
max: number;
|
||||
p0_001: number;
|
||||
p0_01: number;
|
||||
p0_1: number;
|
||||
p1: number;
|
||||
p2_5: number;
|
||||
p10: number;
|
||||
p25: number;
|
||||
p50: number;
|
||||
p75: number;
|
||||
p90: number;
|
||||
p97_5: number;
|
||||
p99: number;
|
||||
p99_9: number;
|
||||
p99_99: number;
|
||||
p99_999: number;
|
||||
}
|
||||
```
|
||||
|
||||
## `PiscinaLoadBalancer`
|
||||
|
||||
The `PiscinaLoadBalancer` interface is used to implement custom load balancing algorithm that determines which worker thread should be assigned a task.
|
||||
|
||||
> For more information, see [Custom Load Balancers](../advanced-topics/loadbalancer.mdx).
|
||||
|
||||
### Interface: `PiscinaLoadBalancer`
|
||||
|
||||
```ts
|
||||
type PiscinaLoadBalancer = (
|
||||
task: PiscinaTask, // Task to be distributed
|
||||
workers: PiscinaWorker[] // Array of Worker instances
|
||||
) => PiscinaWorker | null; // Worker instance to be assigned the task
|
||||
```
|
||||
|
||||
If the `PiscinaLoadBalancer` returns `null`, `Piscina` will attempt to spawn a new worker, otherwise the task will be queued until a worker is available.
|
||||
|
||||
### Interface: `PiscinaTask`
|
||||
|
||||
```ts
|
||||
interface PiscinaTask {
|
||||
taskId: number; // Unique identifier for the task
|
||||
filename: string; // Filename of the worker module
|
||||
name: string; // Name of the worker function
|
||||
created: number; // Timestamp when the task was created
|
||||
isAbortable: boolean; // Indicates if the task can be aborted through AbortSignal
|
||||
}
|
||||
```
|
||||
|
||||
### Interface: `PiscinaWorker`
|
||||
|
||||
```ts
|
||||
interface PiscinaWorker {
|
||||
id: number; // Unique identifier for the worker
|
||||
currentUsage: number; // Number of tasks currently running on the worker
|
||||
isRunningAbortableTask: boolean; // Indicates if the worker is running an abortable task
|
||||
histogram: HistogramSummary | null; // Worker histogram
|
||||
terminating: boolean; // Indicates if the worker is terminating
|
||||
destroyed: boolean; // Indicates if the worker has been destroyed
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Custom Load Balancer
|
||||
|
||||
#### JavaScript
|
||||
<a id="custom-load-balancer-example-js"> </a>
|
||||
|
||||
```js
|
||||
const { Piscina } = require('piscina');
|
||||
|
||||
function LeastBusyBalancer(opts) {
|
||||
const { maximumUsage } = opts;
|
||||
|
||||
return (task, workers) => {
|
||||
let candidate = null;
|
||||
let checkpoint = maximumUsage;
|
||||
for (const worker of workers) {
|
||||
if (worker.currentUsage === 0) {
|
||||
candidate = worker;
|
||||
break;
|
||||
}
|
||||
|
||||
if (worker.isRunningAbortableTask) continue;
|
||||
|
||||
if (!task.isAbortable && worker.currentUsage < checkpoint) {
|
||||
candidate = worker;
|
||||
checkpoint = worker.currentUsage;
|
||||
}
|
||||
}
|
||||
|
||||
return candidate;
|
||||
};
|
||||
}
|
||||
|
||||
const piscina = new Piscina({
|
||||
loadBalancer: LeastBusyBalancer({ maximumUsage: 2 }),
|
||||
});
|
||||
|
||||
piscina
|
||||
.runTask({ filename: 'worker.js', name: 'default' })
|
||||
.then((result) => console.log(result))
|
||||
.catch((err) => console.error(err));
|
||||
```
|
||||
|
||||
#### TypeScript
|
||||
<a id="custom-load-balancer-example-ts"> </a>
|
||||
|
||||
```ts
|
||||
import { Piscina } from 'piscina';
|
||||
|
||||
function LeastBusyBalancer(
|
||||
opts: LeastBusyBalancerOptions
|
||||
): PiscinaLoadBalancer {
|
||||
const { maximumUsage } = opts;
|
||||
|
||||
return (task, workers) => {
|
||||
let candidate: PiscinaWorker | null = null;
|
||||
let checkpoint = maximumUsage;
|
||||
for (const worker of workers) {
|
||||
if (worker.currentUsage === 0) {
|
||||
candidate = worker;
|
||||
break;
|
||||
}
|
||||
|
||||
if (worker.isRunningAbortableTask) continue;
|
||||
|
||||
if (!task.isAbortable && worker.currentUsage < checkpoint) {
|
||||
candidate = worker;
|
||||
checkpoint = worker.currentUsage;
|
||||
}
|
||||
}
|
||||
|
||||
return candidate;
|
||||
};
|
||||
}
|
||||
|
||||
const piscina = new Piscina({
|
||||
loadBalancer: LeastBusyBalancer({ maximumUsage: 2 }),
|
||||
});
|
||||
|
||||
piscina
|
||||
.runTask({ filename: 'worker.js', name: 'default' })
|
||||
.then((result) => console.log(result))
|
||||
.catch((err) => console.error(err));
|
||||
```
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
---
|
||||
id: Events
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
## Event: `'error'`
|
||||
|
||||
An `'error'` event is emitted by instances of this class when:
|
||||
|
||||
- Uncaught exceptions occur inside Worker threads that do not currently handle
|
||||
tasks.
|
||||
- Unexpected messages are sent from from Worker threads.
|
||||
|
||||
All other errors are reported by rejecting the `Promise` returned from
|
||||
`run()` or `runTask()`, including rejections reported by the handler function
|
||||
itself.
|
||||
|
||||
## Event: `'drain'`
|
||||
|
||||
A `'drain'` event is emitted whenever the `queueSize` reaches `0`.
|
||||
|
||||
## Event: `'needsDrain'`
|
||||
|
||||
Similar to [`Piscina#needsDrain`](https://github.com/piscinajs/piscina#property-needsdrain-readonly);
|
||||
this event is triggered once the total capacity of the pool is exceeded
|
||||
by number of tasks enqueued that are pending of execution.
|
||||
|
||||
## Event: `'message'`
|
||||
|
||||
A `'message'` event is emitted whenever a message is received from a worker thread.
|
||||
|
||||
## Event: `'workerCreate'`
|
||||
|
||||
Event that is triggered when a new worker is created.
|
||||
|
||||
As argument, it receives the worker instance.
|
||||
|
||||
## Event: `'workerDestroy'`
|
||||
|
||||
Event that is triggered when a worker is destroyed.
|
||||
|
||||
As argument, it receives the worker instance that has been destroyed.
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
---
|
||||
id: Interface
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
## Interface: `Transferable`
|
||||
|
||||
Objects may implement the `Transferable` interface to create their own
|
||||
custom transferable objects. This is useful when an object being
|
||||
passed into or from a worker contains a deeply nested transferable
|
||||
object such as an `ArrayBuffer` or `MessagePort`.
|
||||
|
||||
`Transferable` objects expose two properties inspected by Piscina
|
||||
to determine how to transfer the object. These properties are
|
||||
named using the special static `Piscina.transferableSymbol` and
|
||||
`Piscina.valueSymbol` properties:
|
||||
|
||||
* The `Piscina.transferableSymbol` property provides the object
|
||||
(or objects) that are to be included in the `transferList`.
|
||||
|
||||
* The `Piscina.valueSymbol` property provides a surrogate value
|
||||
to transmit in place of the `Transferable` itself.
|
||||
|
||||
Both properties are required.
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
const {
|
||||
move,
|
||||
transferableSymbol,
|
||||
valueSymbol
|
||||
} = require('piscina');
|
||||
|
||||
module.exports = () => {
|
||||
const obj = {
|
||||
a: { b: new Uint8Array(5); },
|
||||
c: { new Uint8Array(10); },
|
||||
|
||||
get [transferableSymbol]() {
|
||||
// Transfer the two underlying ArrayBuffers
|
||||
return [this.a.b.buffer, this.c.buffer];
|
||||
}
|
||||
|
||||
get [valueSymbol]() {
|
||||
return { a: { b: this.a.b }, c: this.c };
|
||||
}
|
||||
};
|
||||
return move(obj);
|
||||
};
|
||||
```
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
---
|
||||
id: Methods
|
||||
sidebar_position: 3
|
||||
---
|
||||
## Method: `run(task[, options])`
|
||||
|
||||
Schedules a task to be run on a Worker thread.
|
||||
|
||||
* `task`: Any value. This will be passed to the function that is exported from
|
||||
`filename`.
|
||||
* `options`:
|
||||
* `transferList`: An optional lists of objects that is passed to
|
||||
[`postMessage()`] when posting `task` to the Worker, which are transferred
|
||||
rather than cloned.
|
||||
* `filename`: Optionally overrides the `filename` option passed to the
|
||||
constructor for this task. If no `filename` was specified to the constructor,
|
||||
this is mandatory.
|
||||
* `name`: Optionally overrides the exported worker function used for the task.
|
||||
* `abortSignal`: An `AbortSignal` instance. If passed, this can be used to
|
||||
cancel a task. If the task is already running, the corresponding `Worker`
|
||||
thread will be stopped.
|
||||
(More generally, any `EventEmitter` or `EventTarget` that emits `'abort'`
|
||||
events can be passed here.) Abortable tasks cannot share threads regardless
|
||||
of the `concurrentTasksPerWorker` options.
|
||||
|
||||
This returns a `Promise` for the return value of the (async) function call
|
||||
made to the function exported from `filename`. If the (async) function throws
|
||||
an error, the returned `Promise` will be rejected with that error.
|
||||
If the task is aborted, the returned `Promise` is rejected with an error
|
||||
as well.
|
||||
|
||||
## Method: `runTask(task[, transferList][, filename][, abortSignal])`
|
||||
|
||||
**Deprecated** -- Use `run(task, options)` instead.
|
||||
|
||||
Schedules a task to be run on a Worker thread.
|
||||
|
||||
* `task`: Any value. This will be passed to the function that is exported from
|
||||
`filename`.
|
||||
* `transferList`: An optional lists of objects that is passed to
|
||||
[`postMessage()`] when posting `task` to the Worker, which are transferred
|
||||
rather than cloned.
|
||||
* `filename`: Optionally overrides the `filename` option passed to the
|
||||
constructor for this task. If no `filename` was specified to the constructor,
|
||||
this is mandatory.
|
||||
* `signal`: An [`AbortSignal`][] instance. If passed, this can be used to
|
||||
cancel a task. If the task is already running, the corresponding `Worker`
|
||||
thread will be stopped.
|
||||
(More generally, any `EventEmitter` or `EventTarget` that emits `'abort'`
|
||||
events can be passed here.) Abortable tasks cannot share threads regardless
|
||||
of the `concurrentTasksPerWorker` options.
|
||||
|
||||
This returns a `Promise` for the return value of the (async) function call
|
||||
made to the function exported from `filename`. If the (async) function throws
|
||||
an error, the returned `Promise` will be rejected with that error.
|
||||
If the task is aborted, the returned `Promise` is rejected with an error
|
||||
as well.
|
||||
|
||||
## Method: `destroy()`
|
||||
|
||||
Stops all Workers and rejects all `Promise`s for pending tasks.
|
||||
|
||||
This returns a `Promise` that is fulfilled once all threads have stopped.
|
||||
|
||||
## Method: `close([options])`
|
||||
|
||||
* `options`:
|
||||
* `force`: A `boolean` value that indicates whether to abort all tasks that
|
||||
are enqueued but not started yet. The default is `false`.
|
||||
|
||||
It stops all Workers gracefully.
|
||||
|
||||
This returns a `Promise` that is fulfilled once all tasks that were started
|
||||
have completed and all threads have stopped.
|
||||
|
||||
This method is similar to `destroy()`, but with the difference that `close()`
|
||||
will wait for the worker tasks to finish, while `destroy()`
|
||||
will abort them immediately.
|
||||
+133
@@ -0,0 +1,133 @@
|
||||
---
|
||||
id: Properties
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
## Property: `completed` (readonly)
|
||||
|
||||
The current number of completed tasks.
|
||||
|
||||
## Property: `duration` (readonly)
|
||||
|
||||
The length of time (in milliseconds) since this `Piscina` instance was
|
||||
created.
|
||||
|
||||
## Property: `options` (readonly)
|
||||
|
||||
A copy of the options that are currently being used by this instance. This
|
||||
object has the same properties as the options object passed to the constructor.
|
||||
|
||||
## Property: `runTime` (readonly)
|
||||
|
||||
A histogram summary object summarizing the collected run times of completed
|
||||
tasks. All values are expressed in milliseconds.
|
||||
|
||||
* `runTime.average` {`number`} The average run time of all tasks
|
||||
* `runTime.mean` {`number`} The mean run time of all tasks
|
||||
* `runTime.stddev` {`number`} The standard deviation of collected run times
|
||||
* `runTime.min` {`number`} The fastest recorded run time
|
||||
* `runTime.max` {`number`} The slowest recorded run time
|
||||
|
||||
All properties following the pattern `p{N}` where N is a number (e.g. `p1`, `p99`)
|
||||
represent the percentile distributions of run time observations. For example,
|
||||
`p99` is the 99th percentile indicating that 99% of the observed run times were
|
||||
faster or equal to the given value.
|
||||
|
||||
```js
|
||||
{
|
||||
average: 1880.25,
|
||||
mean: 1880.25,
|
||||
stddev: 1.93,
|
||||
min: 1877,
|
||||
max: 1882.0190887451172,
|
||||
p0_001: 1877,
|
||||
p0_01: 1877,
|
||||
p0_1: 1877,
|
||||
p1: 1877,
|
||||
p2_5: 1877,
|
||||
p10: 1877,
|
||||
p25: 1877,
|
||||
p50: 1881,
|
||||
p75: 1881,
|
||||
p90: 1882,
|
||||
p97_5: 1882,
|
||||
p99: 1882,
|
||||
p99_9: 1882,
|
||||
p99_99: 1882,
|
||||
p99_999: 1882
|
||||
}
|
||||
```
|
||||
|
||||
## Property: `threads` (readonly)
|
||||
|
||||
An Array of the `Worker` instances used by this pool.
|
||||
|
||||
## Property: `queueSize` (readonly)
|
||||
|
||||
The current number of tasks waiting to be assigned to a Worker thread.
|
||||
|
||||
## Property: `needsDrain` (readonly)
|
||||
|
||||
Boolean value that specifies whether the capacity of the pool has
|
||||
been exceeded by the number of tasks submitted.
|
||||
|
||||
This property is helpful to make decisions towards creating backpressure
|
||||
over the number of tasks submitted to the pool.
|
||||
|
||||
## Property: `utilization` (readonly)
|
||||
|
||||
A point-in-time ratio comparing the approximate total mean run time
|
||||
of completed tasks to the total runtime capacity of the pool.
|
||||
|
||||
A pools runtime capacity is determined by multiplying the `duration`
|
||||
by the `options.maxThread` count. This provides an absolute theoretical
|
||||
maximum aggregate compute time that the pool would be capable of.
|
||||
|
||||
The approximate total mean run time is determined by multiplying the
|
||||
mean run time of all completed tasks by the total number of completed
|
||||
tasks. This number represents the approximate amount of time the
|
||||
pool as been actively processing tasks.
|
||||
|
||||
The utilization is then calculated by dividing the approximate total
|
||||
mean run time by the capacity, yielding a fraction between `0` and `1`.
|
||||
|
||||
## Property: `waitTime` (readonly)
|
||||
|
||||
A histogram summary object summarizing the collected times tasks spent
|
||||
waiting in the queue. All values are expressed in milliseconds.
|
||||
|
||||
* `waitTime.average` {`number`} The average wait time of all tasks
|
||||
* `waitTime.mean` {`number`} The mean wait time of all tasks
|
||||
* `waitTime.stddev` {`number`} The standard deviation of collected wait times
|
||||
* `waitTime.min` {`number`} The fastest recorded wait time
|
||||
* `waitTime.max` {`number`} The longest recorded wait time
|
||||
|
||||
All properties following the pattern `p{N}` where N is a number (e.g. `p1`, `p99`)
|
||||
represent the percentile distributions of wait time observations. For example,
|
||||
`p99` is the 99th percentile indicating that 99% of the observed wait times were
|
||||
faster or equal to the given value.
|
||||
|
||||
```js
|
||||
{
|
||||
average: 1880.25,
|
||||
mean: 1880.25,
|
||||
stddev: 1.93,
|
||||
min: 1877,
|
||||
max: 1882.0190887451172,
|
||||
p0_001: 1877,
|
||||
p0_01: 1877,
|
||||
p0_1: 1877,
|
||||
p1: 1877,
|
||||
p2_5: 1877,
|
||||
p10: 1877,
|
||||
p25: 1877,
|
||||
p50: 1881,
|
||||
p75: 1881,
|
||||
p90: 1882,
|
||||
p97_5: 1882,
|
||||
p99: 1882,
|
||||
p99_9: 1882,
|
||||
p99_99: 1882,
|
||||
p99_999: 1882
|
||||
}
|
||||
```
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
id: Static Properties and Methods
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
## Static property: `isWorkerThread` (readonly)
|
||||
|
||||
Is `true` if this code runs inside a `Piscina` threadpool as a Worker.
|
||||
|
||||
## Static property: `version` (readonly)
|
||||
|
||||
Provides the current version of this library as a semver string.
|
||||
|
||||
## Static method: `move(value)`
|
||||
|
||||
By default, any value returned by a worker function will be cloned when
|
||||
returned back to the Piscina pool, even if that object is capable of
|
||||
being transfered. The `Piscina.move()` method can be used to wrap and
|
||||
mark transferable values such that they will by transfered rather than
|
||||
cloned.
|
||||
|
||||
The `value` may be any object supported by Node.js to be transferable
|
||||
(e.g. `ArrayBuffer`, any `TypedArray`, or `MessagePort`), or any object
|
||||
implementing the `Transferable` interface.
|
||||
|
||||
```js
|
||||
const { move } = require('piscina');
|
||||
|
||||
module.exports = () => {
|
||||
return move(new ArrayBuffer(10));
|
||||
}
|
||||
```
|
||||
|
||||
The `move()` method will throw if the `value` is not transferable.
|
||||
|
||||
The object returned by the `move()` method should not be set as a
|
||||
nested value in an object. If it is used, the `move()` object itself
|
||||
will be cloned as opposed to transfering the object it wraps.
|
||||
+9
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: "ChangeLog"
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
import Changelog from '../../../CHANGELOG.md'
|
||||
|
||||
<Changelog/>
|
||||
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
---
|
||||
id: Release Notes
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
### 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!
|
||||
Reference in New Issue
Block a user