# goroutine-pool

**Repository Path**: konyshe/goroutine-pool

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-22
- **Last Updated**: 2025-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Goroutine Pool - Go协程控制库

一个功能强大的Go协程管理库，支持协程的批量启动、等待、监控、CPU亲和性绑定、优先级控制和超时管理。

## 功能特性

### ✅ 1. 批量启动多个协程
- `Submit(task)` - 提交单个任务
- `SubmitMultiple(tasks)` - 批量提交多个任务

### ✅ 2. 等待所有协程结束
- `Wait()` - 阻塞等待所有任务完成

### ✅ 3. 每3秒反馈运行中的协程数量
- 自动监控功能，每3秒输出当前运行的协程数量
- `GetRunningCount()` - 手动获取当前运行协程数

### ✅ 4. 指定协程运行在指定CPU核心
- Linux系统：使用系统调用真正绑定到指定CPU核心
- 其他系统：锁定到OS线程（有限的亲和性）

### ✅ 5. 指定协程优先级
- `PriorityHigh` - 高优先级（立即执行）
- `PriorityNormal` - 普通优先级
- `PriorityLow` - 低优先级（延迟执行）

### ✅ 6. 指定协程运行时间
- 使用 `Timeout` 配置项设置最大运行时间
- 超时后自动取消任务

## 快速开始

### 安装

```bash
go get -u goroutine-pool
```

### 基本使用

```go
package main

import (
    "context"
    "fmt"
    "time"
    pool "goroutine-pool"
)

func main() {
    // 创建协程池
    p := pool.NewPool(100)

    // 创建任务
    task := &pool.Task{
        Name: "示例任务",
        Fn: func(ctx context.Context) error {
            fmt.Println("任务执行中...")
            time.Sleep(2 * time.Second)
            return nil
        },
        Config: pool.TaskConfig{
            CPUCore:  0,                    // 绑定到CPU 0
            Priority: pool.PriorityHigh,    // 高优先级
            Timeout:  5 * time.Second,      // 5秒超时
        },
    }

    // 提交任务
    p.Submit(task)

    // 等待完成
    p.Wait()
}
```

### 批量提交任务

```go
tasks := []*pool.Task{
    {
        Name: "任务1",
        Fn: func(ctx context.Context) error {
            // 任务逻辑
            return nil
        },
        Config: pool.TaskConfig{
            CPUCore:  0,
            Priority: pool.PriorityHigh,
            Timeout:  10 * time.Second,
        },
    },
    {
        Name: "任务2",
        Fn: func(ctx context.Context) error {
            // 任务逻辑
            return nil
        },
        Config: pool.TaskConfig{
            CPUCore:  1,
            Priority: pool.PriorityNormal,
            Timeout:  0, // 无限制
        },
    },
}

// 批量提交
p.SubmitMultiple(tasks)
p.Wait()
```

## 配置选项

### TaskConfig

| 字段 | 类型 | 说明 |
|------|------|------|
| CPUCore | int | CPU核心编号（-1表示不指定） |
| Priority | Priority | 优先级（Low/Normal/High） |
| Timeout | time.Duration | 超时时间（0表示无限制） |

### Priority 优先级

- `PriorityLow` - 低优先级，延迟10ms后执行
- `PriorityNormal` - 普通优先级，正常执行
- `PriorityHigh` - 高优先级，立即执行

## 运行示例

```bash
cd example
go run main.go
```

### 示例输出

```
=== Goroutine Pool 示例 ===
系统CPU核心数: 8

>>> 批量提交5个任务
[MONITOR] Started monitoring goroutines...
[TASK] 高优先级任务开始执行（绑定到CPU 0）
[TASK] 普通优先级任务开始执行（绑定到CPU 1）
[TASK] 超时任务开始执行（将在2秒后超时）
[TASK] 错误任务开始执行
[MONITOR] Running goroutines: 5
[TASK] 低优先级任务开始执行（不绑定CPU）
[TASK] 低优先级任务完成
[COMPLETED] 低优先级任务 finished successfully in 1.001s
[TASK] 错误任务完成
[COMPLETED] 错误任务 finished with error in 1.002s: 模拟任务错误
[TIMEOUT] 超时任务 timed out after 2.001s

>>> 动态添加更多任务
[TASK] 动态任务-0 开始执行，将运行 2s
...
[MONITOR] Running goroutines: 7
...

>>> 等待所有任务完成...
[MONITOR] Stopped monitoring goroutines

=== 所有任务已完成 ===
```

## API 文档

### Pool 方法

#### `NewPool(bufferSize int) *Pool`
创建新的协程池

参数：
- `bufferSize`: 任务缓冲区大小

#### `Submit(task *Task)`
提交单个任务

#### `SubmitMultiple(tasks []*Task)`
批量提交多个任务

#### `Wait()`
等待所有任务完成（阻塞）

#### `GetRunningCount() int64`
获取当前运行中的协程数量

## 平台支持

- **Linux**: 完整支持所有功能，包括真正的CPU亲和性
- **其他平台**: 支持基本功能，CPU亲和性降级为OS线程锁定

## 注意事项

1. CPU亲和性功能在Linux上效果最好
2. 优先级通过延迟执行实现，不是操作系统级别的优先级
3. 超时功能会取消任务的context，任务需要正确处理context取消
4. 协程池会自动捕获panic，避免单个任务崩溃影响整体

运行示例

  # 运行示例程序
  cd example && go run main.go

  # 运行测试
  go test -v

  # 运行基准测试
  go test -bench=. -benchmem

  核心特性

  1. 线程安全: 使用 atomic 和 mutex 保证并发安全
  2. Panic恢复: 自动捕获并恢复任务panic
  3. 实时监控: 每3秒输出协程运行状态
  4. 跨平台: 支持Linux和其他平台（功能降级）
  5. 灵活配置: CPU绑定、优先级、超时都可独立配置

## 许可证

MIT License