# workpool

**Repository Path**: kingecg/workpool

## Basic Information

- **Project Name**: workpool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Worker Pool

基于 Node.js Worker Threads 的线程池库，支持在 Worker 线程中运行用户自定义函数。

## 特性

- 线程池管理，自动调度任务
- 支持 Worker 脚本的 `init` / `destroy` 生命周期方法
- 单线程多任务并发执行
- 基于 Promise 的异步 API
- **动态扩缩容**：支持配置最小/最大线程数
- **空闲回收**：线程空闲超时后自动销毁
- **老生代识别**：跟踪线程任务执行次数，识别老生代线程
- **内存限制**：当空闲线程内存超过限制时自动销毁

## 安装

```bash
npm install
```

## 使用

### 1. 创建 Worker 脚本

在 `scripts/` 目录下创建你的 worker 脚本：

```javascript
// scripts/myWorker.js

// 可选：初始化方法，创建线程时自动调用
async function init() {
  console.log('[Worker] init');
}

// 可选：销毁方法，线程结束时自动调用
async function destroy() {
  console.log('[Worker] destroy');
}

// 要执行的任务函数
async function add(a, b) {
  return a + b;
}

async function multiply(a, b) {
  return a * b;
}

module.exports = {
  init,
  destroy,
  add,
  multiply
};
```

### 2. 使用线程池

```javascript
const { WorkerPool } = require('workerpool');
const path = require('path');

async function main() {
  // 创建线程池
  const pool = new WorkerPool(path.join(__dirname, 'scripts/myWorker.js'), {
    // 线程数配置
    minThreads: 2,           // 最小线程数，默认 1
    maxThreads: 8,           // 最大线程数，默认 CPU 核数

    // 任务并发配置
    maxTasks: 2,             // 每个线程最大并发任务数，默认 Infinity

    // 空闲超时配置 (毫秒)
    idleTimeout: 60000,      // 空闲超时时间，默认 60000ms (60秒)

    // 老生代配置
    oldGenThreshold: 100,    // 任务数达到此值认为是老生代，默认 100

    // 内存限制 (MB)
    maxMemory: 512            // 内存限制，超过时销毁空闲线程，默认 null
  });

  // 运行任务
  const result = await pool.run('add', 1, 2);       // => 3
  const result2 = await pool.run('multiply', 3, 4); // => 12

  // 批量运行
  const results = await Promise.all([
    pool.run('add', 1, 2),
    pool.run('add', 3, 4),
    pool.run('multiply', 5, 6)
  ]); // => [3, 7, 30]

  // 获取统计信息
  console.log(pool.getStats());

  // 销毁线程池
  await pool.destroy();
}

main();
```

## API

### `WorkerPool(scriptPath, options)`

创建线程池实例。

**参数：**
- `scriptPath` (string): Worker 脚本路径
- `options` (object, 可选):
  - `minThreads` (number): 最小线程数，默认 `1`
  - `maxThreads` (number): 最大线程数，默认 `os.cpus().length`
  - `maxTasks` (number): 每个线程最大并发任务数，默认 `Infinity`
  - `idleTimeout` (number): 空闲超时时间(毫秒)，默认 `60000`
  - `oldGenThreshold` (number): 老生代阈值，任务数达到此值认为是老生代，默认 `100`
  - `maxMemory` (number): 内存限制(MB)，超过时销毁空闲线程，默认 `null`

### `pool.run(funcName, ...args)`

在 Worker 线程中运行函数。

**参数：**
- `funcName` (string): 要执行的函数名
- `...args`: 传递给函数的参数

**返回：** Promise

### `pool.getStats()`

获取线程池统计信息。

**返回：**
```javascript
{
  totalWorkers: 4,        // 总线程数
  availableWorkers: 2,   // 可用线程数
  busyWorkers: 1,         // 忙碌线程数
  queueLength: 5,         // 等待队列长度
  pendingTasks: 3,        // 进行中的任务数
  minThreads: 2,
  maxThreads: 8,
  idleTimeout: 60000,
  oldGenThreshold: 100,
  maxMemory: 512
}
```

### `pool.destroy()`

销毁线程池，终止所有 Worker 线程。

## 事件

```javascript
// Worker 被移除时触发
pool.on('worker:remove', (info) => {
  console.log('Worker removed:', info);
  // {
  //   workerId: 'worker-0',
  //   reason: 'idle timeout' | 'memory limit exceeded',
  //   taskCount: 50,
  //   generation: 'young' | 'old'
  // }
});

// 错误事件
pool.on('error', (err) => {
  console.error('Worker pool error:', err);
});
```

## 示例

```bash
npm run example
```

## 工作原理

### 动态扩缩容
- 线程池根据任务队列长度自动创建新线程（不超过 `maxThreads`）
- 当线程空闲时间超过 `idleTimeout` 且当前线程数大于 `minThreads` 时，自动销毁线程

### 老生代识别
- 线程任务执行次数达到 `oldGenThreshold` 后，标记为 `old`（老生代）
- 老生代线程在空闲时优先被回收

### 内存限制
- Worker 定期上报内存使用情况
- 当空闲线程内存超过 `maxMemory` 且存在其他空闲线程时，触发回收

## 项目结构

```
workerpool/
├── src/
│   ├── index.js        # 入口
│   ├── WorkerPool.js   # 线程池核心类
│   └── worker.js       # Worker 线程脚本
├── scripts/
│   └── example.js      # 示例 worker
├── example.js          # 使用示例
└── package.json
```

## 依赖

- Node.js >= 14.0.0 (需要 Worker Threads 支持)