feat: Custom Balancer

docs/docs/advanced-topics/loadbalancer.mdx

@@ -0,0 +1,42 @@
+---
+id: Custom Load Balancers
+sidebar_position: 2
+---
+
+[Load Balancers](https://www.cloudflare.com/learning/performance/what-is-load-balancing/) are a crucial part of any distributed workload.
+Piscina by default uses a [Resource Based](https://www.cloudflare.com/en-gb/learning/performance/types-of-load-balancing-algorithms/) algorithm (least-busy)
+to distribute the load across the different workers set by the pool.
+
+### Choosing the Load Balancing Algorithm
+
+Choosing the right algorithm heavily depends on the requirements of each individual problem, and to assess
+them by testing the implementation against several variations of workloads.
+
+The algorithms can be grouped on:
+
+#### Dynamic
+
+Focused on taking decision based on heuristics from the workload.
+
+It aims to balance the work by adapting itself to the environment and distribute the workloads equally across the different workers/nodes attempting to make better use
+of resources or to minimize the time to finish each individual workload.
+
+> Piscina uses a Dynamic algorithm, based on how busy the worker is (least-busy)
+
+#### Static
+
+Aims to distribute the workload based on a group of predefined factors.
+It does not adapt to the environment, but rather aims to preserve the state of the distribution accordingly
+to the values set beforehand.
+
+This can be helpful under several situations where we want the workload to be distributed evenly or stick to a specific worker/node over time.
+
+> Round Robin, Ring Hash, are just examples of these algorithms
+
+It is heavily advised to understand the problem and the workload your pool will be facing, and tests heavily against the different algorithms that matches your
+use case with several combinations to better understand its impact and how to manage it.
+
+### Resources
+
+- [Load Balancing Algorithms](https://en.wikipedia.org/wiki/Load_balancing_(computing))
+- [Types of Load Balancing Algorithms](https://www.cloudflare.com/en-gb/learning/performance/types-of-load-balancing-algorithms/)

docs/docs/advanced-topics/performance.mdx

@@ -1,6 +1,6 @@
 ---
 id: Performance Notes
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 Workers are generally optimized for offloading synchronous,

docs/docs/api-reference/class.md

@@ -1,5 +1,5 @@
 ---
-id: Class
+id: Instance
 sidebar_position: 2
 ---
 
@@ -36,7 +36,6 @@ This class extends [`EventEmitter`](https://nodejs.org/api/events.html) from Nod
     :::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.
     :::
-
   - `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'`
@@ -91,8 +90,137 @@ This class extends [`EventEmitter`](https://nodejs.org/api/events.html) from Nod
     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.
 :::
+
+## `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));
+```

docs/docs/api-reference/event.md

@@ -27,4 +27,16 @@ 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.
+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.