Worker Pool Management

/**
 * Create a new worker pool
 * @param {string} [script] - Path to worker script file
 * @param {WorkerPoolOptions} [options] - Pool configuration options
 * @returns {Pool} New pool instance
 */
function pool(script, options) -> Pool

/**
 * Create a new worker pool with options only
 * @param {WorkerPoolOptions} [options] - Pool configuration options
 * @returns {Pool} New pool instance
 */
function pool(options) -> Pool

const workerpool = require('workerpool');

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

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

// Create pool with configuration options
const configuredPool = workerpool.pool({
  minWorkers: 2,
  maxWorkers: 4,
  workerType: 'thread'
});

// Create dedicated worker pool with options
const dedicatedConfiguredPool = workerpool.pool(__dirname + '/myWorker.js', {
  maxWorkers: 8,
  workerTerminateTimeout: 5000
});

/**
 * Execute a function on a worker
 * @param {string|function} method - Function name or function to execute
 * @param {array} [params] - Function arguments
 * @param {ExecOptions} [options] - Execution options
 * @returns {Promise} Promise resolving to execution result
 */
Pool.prototype.exec(method, params, options) -> Promise

// Dynamic function offloading
function fibonacci(n) {
  if (n < 2) return n;
  return fibonacci(n - 2) + fibonacci(n - 1);
}

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

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

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

// With transferable objects (browser/worker_threads only)
const buffer = new ArrayBuffer(1024);
const result4 = await pool.exec('processBuffer', [buffer], {
  transfer: [buffer]
});

/**
 * Create a proxy for worker methods
 * @returns {Promise<object>} Promise resolving to proxy object
 */
Pool.prototype.proxy() -> Promise<ProxyObject>

// Using proxy for cleaner syntax
const worker = await pool.proxy();

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

// All proxy methods return Promises
Promise.all([
  worker.task1(args1),
  worker.task2(args2),
  worker.task3(args3)
]).then(results => {
  console.log('All tasks completed:', results);
});

/**
 * Close all active workers
 * @param {boolean} [force=false] - Force immediate termination
 * @param {number} [timeout] - Termination timeout in milliseconds
 * @returns {Promise<void>} Promise resolving when all workers terminated
 */
Pool.prototype.terminate(force, timeout) -> Promise<void>

// Graceful termination (wait for current tasks to complete)
await pool.terminate();

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

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

// Handle termination errors
try {
  await pool.terminate();
  console.log('Pool terminated successfully');
} catch (error) {
  console.error('Termination error:', error);
}

/**
 * Retrieve statistics on tasks and workers
 * @returns {PoolStats} Object containing pool statistics
 */
Pool.prototype.stats() -> PoolStats

interface PoolStats {
  totalWorkers: number    // Total number of workers in pool
  busyWorkers: number     // Number of workers currently executing tasks
  idleWorkers: number     // Number of idle workers
  pendingTasks: number    // Number of tasks waiting in queue
  activeTasks: number     // Number of currently executing tasks
}

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

// Monitor pool performance
setInterval(() => {
  const stats = pool.stats();
  if (stats.pendingTasks > 10) {
    console.warn('High task queue detected:', stats.pendingTasks);
  }
}, 5000);

// Dynamic scaling decisions
const stats = pool.stats();
if (stats.pendingTasks > stats.totalWorkers * 2) {
  console.log('Consider increasing maxWorkers');
}

interface WorkerPoolOptions {
  /** Minimum number of workers to maintain */
  minWorkers?: number | 'max'
  
  /** Maximum number of workers (default: CPU count - 1) */
  maxWorkers?: number
  
  /** Maximum queued tasks before throwing error (default: Infinity) */
  maxQueueSize?: number
  
  /** Worker type selection */
  workerType?: 'auto' | 'web' | 'process' | 'thread'
  
  /** Timeout for worker termination in milliseconds (default: 1000) */
  workerTerminateTimeout?: number
  
  /** Arguments for child process workers */
  forkArgs?: string[]
  
  /** Options for child process workers */
  forkOpts?: object
  
  /** Options for web workers */
  workerOpts?: object
  
  /** Options for worker threads */
  workerThreadOpts?: object
  
  /** Emit stdout/stderr events from workers */
  emitStdStreams?: boolean
  
  /** Callback when creating workers */
  onCreateWorker?: (args: WorkerArg) => WorkerArg | undefined
  
  /** Callback when terminating workers */
  onTerminateWorker?: (args: WorkerArg) => void
}

// Minimum workers for instant availability
const pool = workerpool.pool({
  minWorkers: 2,      // Keep 2 workers always ready
  maxWorkers: 8       // Scale up to 8 workers under load
});

// High-throughput configuration
const highThroughputPool = workerpool.pool({
  minWorkers: 'max',  // Start with maxWorkers ready
  maxWorkers: 16,
  maxQueueSize: 1000,
  workerTerminateTimeout: 5000
});

// Browser-specific configuration
const browserPool = workerpool.pool({
  workerType: 'web',
  workerOpts: {
    type: 'module'  // For ES module workers
  }
});

// Node.js child process configuration
const processPool = workerpool.pool(__dirname + '/worker.js', {
  workerType: 'process',
  forkArgs: ['--max-old-space-size=4096'],
  forkOpts: {
    silent: false,
    env: { ...process.env, NODE_ENV: 'worker' }
  }
});