# BJ_THREAD

**Repository Path**: BAIJIE4015/bj_-thread

## Basic Information

- **Project Name**: BJ_THREAD
- **Description**: 线程池 方便代码自主率查询时替代boost等高效的线程池。
- **Primary Language**: C++
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-13
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BJ_THREAD - 跨平台线程池库

## 项目简介

BJ_THREAD 是一个跨平台的 C++ 线程池库，支持 Windows 和 Linux 系统。该库提供了简单易用的线程池接口，实现了高效的任务调度。

## 主要特性

1. **跨平台支持**：支持 Windows 和 Linux 系统
2. **双队列设计**：同一个线程池内支持顺序执行和无序执行两种队列
3. **灵活的任务提交**：通过 Post 方法的参数决定任务执行模式
4. **工厂模式**：使用工厂模式创建线程池对象
5. **自动线程数**：根据系统 CPU 核心数自动分配默认线程池大小
6. **类型安全**：使用模板支持任意返回类型的任务
7. **异常安全**：支持任务异常传递

## 项目结构

```
BJ_THREAD/
├── include/           # 头文件
│   ├── ThreadPool.h          # 线程池核心类
│   └── ThreadPoolFactory.h   # 线程池工厂类
├── src/              # 源文件
│   ├── ThreadPool.cpp
│   └── ThreadPoolFactory.cpp
├── test/             # 测试文件
│   └── main.cpp
└── CMakeLists.txt    # CMake 构建配置
```

## 编译方法

### Windows

```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
```

### Linux

```bash
mkdir build
cd build
cmake ..
make
```

编译完成后，可执行文件位于 `build/bin/` 目录下。

## 使用方法

### 1. 包含头文件

```cpp
#include "ThreadPool.h"
#include "ThreadPoolFactory.h"
using namespace BJ_THREAD;
```

### 2. 创建线程池

#### 使用默认线程数（系统 CPU 核心数）

```cpp
auto pPool = CThreadPoolFactory::CreateThreadPool();
```

#### 指定线程数

```cpp
// 创建 4 个线程的线程池
auto pPool = CThreadPoolFactory::CreateThreadPool(4);
```

### 3. 提交任务

#### 提交顺序执行任务

```cpp
auto result = pPool->Post(enExecutionMode::SEQUENTIAL, [](int x, int y) {
    return x + y;
}, 10, 20);

int sum = result.get();  // 等待任务完成并获取结果
```

#### 提交无序执行任务

```cpp
auto result = pPool->Post(enExecutionMode::UNORDERED, [](int x, int y) {
    return x + y;
}, 10, 20);

int sum = result.get();  // 等待任务完成并获取结果
```

#### 提交无返回值的任务

```cpp
pPool->Post(enExecutionMode::UNORDERED, [] {
    std::cout << "Task executed" << std::endl;
});
```

### 4. 在同一个线程池中混合使用两种模式

```cpp
auto pPool = CThreadPoolFactory::CreateThreadPool();

// 提交顺序执行任务
for (int i = 0; i < 5; ++i) {
    pPool->Post(enExecutionMode::SEQUENTIAL, [i] {
        std::cout << "Sequential task " << i << std::endl;
    });
}

// 提交无序执行任务
for (int i = 0; i < 5; ++i) {
    pPool->Post(enExecutionMode::UNORDERED, [i] {
        std::cout << "Unordered task " << i << std::endl;
    });
}
```

### 5. 关闭线程池

```cpp
pPool->Shutdown();
```

### 6. 获取线程池信息

```cpp
size_t unThreadCount = pPool->GetThreadCount();  // 获取线程数
bool bRunning = pPool->IsRunning();               // 检查是否运行中
```

## 执行模式说明

### 顺序执行模式 (SEQUENTIAL)

在顺序执行模式下，任务会按照提交的顺序依次执行，即使有多个工作线程，同一时间也只有一个顺序任务在执行。

```cpp
pPool->Post(enExecutionMode::SEQUENTIAL, [] {
    // 任务代码
});
```

适用场景：
- 需要保证任务执行顺序的场景
- 任务之间存在依赖关系
- 需要互斥访问共享资源的场景

### 无序执行模式 (UNORDERED)

在无序执行模式下，任务会被分配到空闲的工作线程上并行执行，执行顺序不确定。

```cpp
pPool->Post(enExecutionMode::UNORDERED, [] {
    // 任务代码
});
```

适用场景：
- 任务之间相互独立
- 需要充分利用多核性能
- 可以并行执行的任务

## API 参考

### CThreadPool 类

#### 构造函数

```cpp
CThreadPool(size_t unThreadCount);
```

#### 公共方法

```cpp
template<typename F, typename... Args>
auto Post(enExecutionMode enMode, F&& f, Args&&... args) -> std::future<typename std::result_of<F(Args...)>::type>;

void Shutdown();
size_t GetThreadCount() const;
bool IsRunning() const;
```

### CThreadPoolFactory 类

#### 静态方法

```cpp
static std::unique_ptr<CThreadPool> CreateThreadPool();
static std::unique_ptr<CThreadPool> CreateThreadPool(size_t unThreadCount);
static size_t GetSystemDefaultThreadCount();
```

## 示例代码

### 完整示例

```cpp
#include "ThreadPool.h"
#include "ThreadPoolFactory.h"
#include <iostream>

using namespace BJ_THREAD;

int main() {
    // 创建线程池（使用默认线程数）
    auto pPool = CThreadPoolFactory::CreateThreadPool();

    std::cout << "Thread pool created with " << pPool->GetThreadCount() << " threads" << std::endl;

    // 提交顺序执行任务
    std::vector<std::future<int>> aSequentialResults;
    for (int i = 0; i < 5; ++i) {
        aSequentialResults.emplace_back(pPool->Post(enExecutionMode::SEQUENTIAL, [i] {
            std::this_thread::sleep_for(std::chrono::milliseconds(100));
            std::cout << "Sequential task " << i << " executed" << std::endl;
            return i;
        }));
    }

    // 提交无序执行任务
    std::vector<std::future<int>> aUnorderedResults;
    for (int i = 0; i < 5; ++i) {
        aUnorderedResults.emplace_back(pPool->Post(enExecutionMode::UNORDERED, [i] {
            std::this_thread::sleep_for(std::chrono::milliseconds(100));
            std::cout << "Unordered task " << i << " executed" << std::endl;
            return i + 100;
        }));
    }

    // 获取结果
    for (auto& result : aSequentialResults) {
        result.get();
    }

    for (auto& result : aUnorderedResults) {
        result.get();
    }

    // 关闭线程池
    pPool->Shutdown();

    return 0;
}
```

## 设计说明

### 双队列设计

本线程池采用双队列设计，在同一个线程池内维护两个任务队列：
- **顺序任务队列**（`m_aSequentialTasks`）：存储需要顺序执行的任务
- **无序任务队列**（`m_aUnorderedTasks`）：存储可以无序执行的任务

工作线程在获取任务时，优先从顺序任务队列中获取任务，如果顺序队列为空，则从无序任务队列中获取任务。顺序任务在执行时会使用互斥锁保证串行执行，而无序任务可以并行执行。

### 执行模式选择

通过 `Post` 方法的第一个参数 `enExecutionMode` 来指定任务的执行模式：
- `enExecutionMode::SEQUENTIAL`：顺序执行
- `enExecutionMode::UNORDERED`：无序执行

这种设计使得用户可以在同一个线程池中灵活地选择任务的执行模式，而不需要创建多个线程池。

## 注意事项

1. 线程池对象销毁时会自动调用 `Shutdown()`，无需手动调用
2. 在线程池关闭后提交任务会抛出异常
3. 顺序执行模式下，虽然有多个工作线程，但顺序任务仍然是串行执行的
4. 确保在任务中捕获异常，否则异常会通过 `future` 传递
5. 顺序任务和无序任务在同一个线程池中会共享工作线程资源

## 版本历史

- v1.0.0 (2026-02-13)
  - 初始版本
  - 支持跨平台（Windows/Linux）
  - 同一线程池内支持顺序和无序执行模式
  - 通过 Post 参数决定执行模式
  - 工厂模式创建线程池
  - 自动分配默认线程数

## 许可证

AGPL-3.0