0
# Worker Pool Management
1

2
Core functionality for creating and managing pools of workers to execute tasks in parallel. The Pool class handles task queuing, worker allocation, lifecycle management, and provides both dynamic function offloading and dedicated worker script support.
3

4
## Capabilities
5

6
### Pool Creation
7

8
Creates a new worker pool instance that can be used to execute tasks on background workers.
9

10
```javascript { .api }
11
/**
12
 * Create a new worker pool
13
 * @param {string} [script] - Path to worker script file
14
 * @param {WorkerPoolOptions} [options] - Pool configuration options
15
 * @returns {Pool} New pool instance
16
 */
17
function pool(script, options) -> Pool
18

19
/**
20
 * Create a new worker pool with options only
21
 * @param {WorkerPoolOptions} [options] - Pool configuration options
22
 * @returns {Pool} New pool instance
23
 */
24
function pool(options) -> Pool
25
```
26

27
**Usage Examples:**
28

29
```javascript
30
const workerpool = require('workerpool');
31

32
// Create default pool for dynamic function offloading
33
const pool = workerpool.pool();
34

35
// Create pool with dedicated worker script
36
const dedicatedPool = workerpool.pool(__dirname + '/myWorker.js');
37

38
// Create pool with configuration options
39
const configuredPool = workerpool.pool({
40
  minWorkers: 2,
41
  maxWorkers: 4,
42
  workerType: 'thread'
43
});
44

45
// Create dedicated worker pool with options
46
const dedicatedConfiguredPool = workerpool.pool(__dirname + '/myWorker.js', {
47
  maxWorkers: 8,
48
  workerTerminateTimeout: 5000
49
});
50
```
51

52
### Task Execution
53

54
Execute functions on workers with support for both dynamic function offloading and calling pre-registered worker methods.
55

56
```javascript { .api }
57
/**
58
 * Execute a function on a worker
59
 * @param {string|function} method - Function name or function to execute
60
 * @param {array} [params] - Function arguments
61
 * @param {ExecOptions} [options] - Execution options
62
 * @returns {Promise} Promise resolving to execution result
63
 */
64
Pool.prototype.exec(method, params, options) -> Promise
65
```
66

67
**Usage Examples:**
68

69
```javascript
70
// Dynamic function offloading
71
function fibonacci(n) {
72
  if (n < 2) return n;
73
  return fibonacci(n - 2) + fibonacci(n - 1);
74
}
75

76
const result = await pool.exec(fibonacci, [10]);
77
console.log(result); // 55
78

79
// Call pre-registered worker method
80
const result2 = await pool.exec('processData', [{ key: 'value' }]);
81

82
// With event listener for worker events
83
const result3 = await pool.exec('longRunningTask', [data], {
84
  on: function(payload) {
85
    console.log('Progress:', payload);
86
  }
87
});
88

89
// With transferable objects (browser/worker_threads only)
90
const buffer = new ArrayBuffer(1024);
91
const result4 = await pool.exec('processBuffer', [buffer], {
92
  transfer: [buffer]
93
});
94
```
95

96
### Worker Proxy
97

98
Create a proxy object that provides direct access to worker methods as if they were local functions, with automatic Promise wrapping.
99

100
```javascript { .api }
101
/**
102
 * Create a proxy for worker methods
103
 * @returns {Promise<object>} Promise resolving to proxy object
104
 */
105
Pool.prototype.proxy() -> Promise<ProxyObject>
106
```
107

108
**Usage Examples:**
109

110
```javascript
111
// Using proxy for cleaner syntax
112
const worker = await pool.proxy();
113

114
// Call worker methods directly
115
const result1 = await worker.fibonacci(10);
116
const result2 = await worker.processData({ key: 'value' });
117
const result3 = await worker.calculatePi(1000);
118

119
// All proxy methods return Promises
120
Promise.all([
121
  worker.task1(args1),
122
  worker.task2(args2),
123
  worker.task3(args3)
124
]).then(results => {
125
  console.log('All tasks completed:', results);
126
});
127
```
128

129
### Pool Termination
130

131
Terminate all workers in the pool, optionally forcing immediate termination or setting a timeout.
132

133
```javascript { .api }
134
/**
135
 * Close all active workers
136
 * @param {boolean} [force=false] - Force immediate termination
137
 * @param {number} [timeout] - Termination timeout in milliseconds
138
 * @returns {Promise<void>} Promise resolving when all workers terminated
139
 */
140
Pool.prototype.terminate(force, timeout) -> Promise<void>
141
```
142

143
**Usage Examples:**
144

145
```javascript
146
// Graceful termination (wait for current tasks to complete)
147
await pool.terminate();
148

149
// Force immediate termination
150
await pool.terminate(true);
151

152
// Graceful with timeout fallback
153
await pool.terminate(false, 10000); // 10 second timeout
154

155
// Handle termination errors
156
try {
157
  await pool.terminate();
158
  console.log('Pool terminated successfully');
159
} catch (error) {
160
  console.error('Termination error:', error);
161
}
162
```
163

164
### Pool Statistics
165

166
Retrieve real-time statistics about worker and task status for monitoring and debugging.
167

168
```javascript { .api }
169
/**
170
 * Retrieve statistics on tasks and workers
171
 * @returns {PoolStats} Object containing pool statistics
172
 */
173
Pool.prototype.stats() -> PoolStats
174

175
interface PoolStats {
176
  totalWorkers: number    // Total number of workers in pool
177
  busyWorkers: number     // Number of workers currently executing tasks
178
  idleWorkers: number     // Number of idle workers
179
  pendingTasks: number    // Number of tasks waiting in queue
180
  activeTasks: number     // Number of currently executing tasks
181
}
182
```
183

184
**Usage Examples:**
185

186
```javascript
187
// Get current pool status
188
const stats = pool.stats();
189
console.log(`Pool status: ${stats.busyWorkers}/${stats.totalWorkers} workers busy`);
190
console.log(`Queue: ${stats.pendingTasks} pending, ${stats.activeTasks} active`);
191

192
// Monitor pool performance
193
setInterval(() => {
194
  const stats = pool.stats();
195
  if (stats.pendingTasks > 10) {
196
    console.warn('High task queue detected:', stats.pendingTasks);
197
  }
198
}, 5000);
199

200
// Dynamic scaling decisions
201
const stats = pool.stats();
202
if (stats.pendingTasks > stats.totalWorkers * 2) {
203
  console.log('Consider increasing maxWorkers');
204
}
205
```
206

207
## Pool Configuration Options
208

209
```javascript { .api }
210
interface WorkerPoolOptions {
211
  /** Minimum number of workers to maintain */
212
  minWorkers?: number | 'max'
213
  
214
  /** Maximum number of workers (default: CPU count - 1) */
215
  maxWorkers?: number
216
  
217
  /** Maximum queued tasks before throwing error (default: Infinity) */
218
  maxQueueSize?: number
219
  
220
  /** Worker type selection */
221
  workerType?: 'auto' | 'web' | 'process' | 'thread'
222
  
223
  /** Timeout for worker termination in milliseconds (default: 1000) */
224
  workerTerminateTimeout?: number
225
  
226
  /** Arguments for child process workers */
227
  forkArgs?: string[]
228
  
229
  /** Options for child process workers */
230
  forkOpts?: object
231
  
232
  /** Options for web workers */
233
  workerOpts?: object
234
  
235
  /** Options for worker threads */
236
  workerThreadOpts?: object
237
  
238
  /** Emit stdout/stderr events from workers */
239
  emitStdStreams?: boolean
240
  
241
  /** Callback when creating workers */
242
  onCreateWorker?: (args: WorkerArg) => WorkerArg | undefined
243
  
244
  /** Callback when terminating workers */
245
  onTerminateWorker?: (args: WorkerArg) => void
246
}
247
```
248

249
**Configuration Examples:**
250

251
```javascript
252
// Minimum workers for instant availability
253
const pool = workerpool.pool({
254
  minWorkers: 2,      // Keep 2 workers always ready
255
  maxWorkers: 8       // Scale up to 8 workers under load
256
});
257

258
// High-throughput configuration
259
const highThroughputPool = workerpool.pool({
260
  minWorkers: 'max',  // Start with maxWorkers ready
261
  maxWorkers: 16,
262
  maxQueueSize: 1000,
263
  workerTerminateTimeout: 5000
264
});
265

266
// Browser-specific configuration
267
const browserPool = workerpool.pool({
268
  workerType: 'web',
269
  workerOpts: {
270
    type: 'module'  // For ES module workers
271
  }
272
});
273

274
// Node.js child process configuration
275
const processPool = workerpool.pool(__dirname + '/worker.js', {
276
  workerType: 'process',
277
  forkArgs: ['--max-old-space-size=4096'],
278
  forkOpts: {
279
    silent: false,
280
    env: { ...process.env, NODE_ENV: 'worker' }
281
  }
282
});
283
```