# DynamicThreadPool

**Repository Path**: zhongtangtech/dynamic-thread-pool

## Basic Information

- **Project Name**: DynamicThreadPool
- **Description**: 本项目是一个基于 C++11 及以上标准 的高性能、高可配置性的动态线程池实现，适用于 CPU 密集型、I/O 密集型 及 混合型 任务场景。
线程池具备 动态扩缩容、优先级调度、延时任务执行、对象池复用 等高级特性，适用于 高并发、低延迟 的任务调度场景。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-27
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dynamic Thread Pool

## 📌 Introduction

This project is a **high-performance, highly configurable dynamic thread pool** implemented in **C++11 and above**, designed for **CPU-intensive**, **I/O-intensive**, and **hybrid workloads**.
The thread pool supports **dynamic scaling, priority scheduling, delayed task execution, and object pooling**, making it suitable for **high-concurrency, low-latency** scenarios.

---

## 🚀 Key Features

### 🧠 Intelligent Dynamic Thread Adjustment

* Dynamically **adjusts the number of threads** according to workload, avoiding wasted resources or task backlog.
* Provides four pool types: `STATIC`, `CPU`, `IO`, `MIXED`, each calculating the optimal thread count automatically.
* Uses **Exponential Moving Average (EMA)** for task execution time statistics, smoothing workload prediction and improving scaling precision.

### ⏰ Delayed Task & Priority Scheduling

* Built-in **dual queue mechanism**: priority queue (real-time tasks) and timer queue (delayed tasks).
* Tasks support **5-level priority** and **delayed execution (second-level precision)**.
* A dedicated scheduler thread monitors delayed tasks to ensure **on-time execution**.

### ♻️ Efficient Memory Management

* Uses an **Object Pool** to manage task objects, reducing frequent heap allocations.
* Combined with `thread_local` caching to further lower lock contention and allocation overhead.

### 🔧 Task Lifecycle Management

* Each task is assigned a unique **ID**, supporting **status queries and cancellation** by ID.
* Clear task state machine (waiting, running, completed), making it easy to monitor and debug.

### 🧩 Highly Configurable

* Customizable **core threads, max threads, queue length, scheduling interval**, etc.
* Provides **smoothing factors and scaling step size** for fine-tuning across different workloads.

### 🧪 Thread Safety & Graceful Shutdown

* Designed with **lock-free or fine-grained locking**, minimizing contention.
* Supports **graceful shutdown**, ensuring all tasks are either executed or safely canceled before destruction.

### ⚡ Performance Advantages

* **Low latency**: Object pool + thread-local caching reduce allocation overhead.
* **High throughput**: Dynamic scaling ensures fast responsiveness under heavy load.
* **Resource-friendly**: Idle threads automatically suspend to save CPU cycles.
* **Observability**: Built-in logging outputs key thread pool metrics for monitoring and tuning.

---

## 📂 Project Structure

* `base.h` – Defines basic types and macros.
* `object.h` – Timer class definitions.
* `task.h` – Task-related classes and structures.
* `threadPool.h` – Core logic of the thread pool (thread scheduling, task distribution, etc.).
* `test1.cpp` – Entry point for testing the thread pool.

---

## ⚙️ Usage

### 1️⃣ Compile

Make sure you have a C++ compiler (e.g., g++). Compile with:

```bash
g++ -std=c++11 -pthread test1.cpp -o thread_pool_test
```

### 2️⃣ Run

```bash
./thread_pool_test
```

### 3️⃣ Test

The `main()` function in `test1.cpp` initializes the pool and submits tasks.
Check the output to verify functionality.

---

## 📘 Basic API

### 🔹 Construct a Thread Pool

```cpp
// Static type thread pool
threadPool(c_int coreThreadNumber, c_int maxThreadNumber, c_double checkTime, const_ll maxTask, c_int logChoice = 3);

// Other pool types
threadPool(c_uint8_t type, c_double checkTime, const_ll maxTask, c_int logChoice = 3);
```

* **Static thread pool**: requires explicit parameters (core size, max size, check interval, max tasks, logging).
* **Dynamic thread pool**: requires only type, interval, max tasks, and logging. The pool auto-adjusts parameters.

Supported pool types:

```cpp
CPU,    // CPU-intensive (heavy computation, little I/O)
IO,     // I/O-intensive (e.g., HTTP, file I/O)
MIXED,  // Mixed workload
STATIC  // Static (no scaling)
```

---

### 🔹 Submit Tasks

```cpp
std::pair<c_uint64_t, typename std::enable_if<!std::is_void<T>::value, std::future<T>>::type>
submit(c_int ex_time, c_uint8_t priority, Fun&& fun, Args&&... args);
```

Parameters:

* `ex_time` – expected execution time
* `priority` – task priority (0–4)
* `fun` – function/lambda task body
* `args...` – task arguments

Returns:

* `std::pair<c_uint64_t, std::future<T>>`
* Use **Task ID** to query or cancel tasks, or **future** to retrieve results.

---

### 🔹 Cancel Tasks

```cpp
bool erase(c_uint64_t& id);
```

Cancel a pending task by **Task ID**.

---

## 📊 Roadmap

* Monitoring module: real-time visualization of thread pool metrics via web/GUI, with runtime reconfiguration support.

---

## 👨‍💻 Author

* **zlzelu**
* Project: [Gitee](https://gitee.com/zlzelu/dynamic-thread-pool)

---

## 📄 License

This project is released under the **MIT License**. See [LICENSE](LICENSE) for details.