Offload functions to worker threads with shared memory primitives for Node.js.
docs: document load balancing in README
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+33
-2
+33
-2
README.md
+33
-2
README.md
···
50
50
});
51
51
```
52
52
53
-
### `workers(size)`
53
+
### `workers(size?, opts?)`
54
54
55
-
Creates a pool of worker threads. Returns a `Runner` that dispatches tasks with round-robin scheduling. Disposable via `using` or `[Symbol.dispose]()`. Defaults to `os.availableParallelism()` workers when `size` is omitted.
55
+
Creates a pool of worker threads. Returns a `Runner` that dispatches tasks. Disposable via `using` or `[Symbol.dispose]()`. Defaults to `os.availableParallelism()` workers and round-robin scheduling when arguments are omitted.
56
56
57
57
```ts
58
58
import { workers } from 'moroutine';
···
90
90
// ...
91
91
}
92
92
```
93
+
94
+
#### Load Balancing
95
+
96
+
The pool uses round-robin scheduling by default. Pass a `balance` option to change the strategy:
97
+
98
+
```ts
99
+
import { workers, leastBusy } from 'moroutine';
100
+
101
+
{
102
+
using run = workers(4, { balance: leastBusy() });
103
+
// tasks dispatched to whichever worker has the fewest in-flight tasks
104
+
}
105
+
```
106
+
107
+
Built-in balancers:
108
+
- `roundRobin()` — cycles through workers in order (default)
109
+
- `leastBusy()` — picks the worker with the lowest active task count
110
+
111
+
Custom balancers implement the `Balancer` interface:
112
+
113
+
```ts
114
+
import type { Balancer } from 'moroutine';
115
+
116
+
const myBalancer: Balancer = {
117
+
select(workers, task) {
118
+
return workers[0]; // always use first worker
119
+
},
120
+
};
121
+
```
122
+
123
+
Each worker handle exposes `thread` (the underlying `worker_threads.Worker`) and `activeCount` for building custom strategies.
93
124
94
125
### Dedicated Workers
95
126