modern-cpp-thread-pool

A lightweight, modern C++17 thread pool implementation with a focus on clarity, correctness, and practical performance evaluation. This project is designed both as a reusable library and as a learning-oriented reference for modern C++ concurrency, testing, and benchmarking practices.

---

Features

• C++17 Core Library – Fully compatible with C++17; no additional dependencies required for the core thread pool.
• Header-only Implementation – Simple to include in any project without separate compilation.
• Configurable Thread Pool Size – Specify the number of threads explicitly, or use the default: std::thread::hardware_concurrency() * 2.
• Task Submission with std::future – Submit tasks and retrieve results asynchronously.
• Lifecycle Management with RAII and Manual Shutdown – Threads can be shut down manually with ShutDownMode::GRACEFUL(default) or ShutDownMode::IMMEDIATE; if not explicitly shut down, the pool performs a graceful shutdown automatically.
• Thread-safe Task Queue – Internal task queue supports concurrent submission from multiple threads.
• Unit Tests with GoogleTest – Comes with a complete test suite for correctness validation.
• Optional C++20 Demo – Demonstrates usage with std::osyncstream for synchronized console output.
• Performance Benchmarks – Built-in benchmark using Google Benchmark to measure throughput and latency.

---

Project Structure

.
├── include/ # contains the header-only library
├── src/ # provides example usage demonstrating the API
├── bench/ # includes performance benchmarks
├── tests/ # contains unit tests to validate correctness
└── CMakeLists.txt

---

Quick Start

#include"thread_pool.hpp"
#include<iostream>intmain() {
ThreadPool pool{4};
auto future = pool.submit([] { return42; });
std::cout << "Result: " << future.get() << std::endl;
return0;
}

API Overview

Function	Description
ThreadPool(size_t num_threads = default_thread_pool_size())	Construct a thread pool with the given number of threads.
template<typename F, typename... Args> auto submit(F&& f, Args&&... args)	Submit a task to the pool and get a std::future for the result.
void shutdown(ShutDownMode mode = ShutDownMode::GRACEFUL)	Shut down all threads gracefully or immediately.
size_t size() const	Get the number of threads in the pool.

---

Requirements

• C++17 compatible compiler (for the thread pool itself)
• C++20 compatible compiler only required for running the demo (src/main.cpp) using std::osyncstream)
  (GCC ≥ 11, Clang ≥ 14 recommended for demo)
• CMake ≥ 3.14
• pthread (Linux / macOS)

Optional dependencies (automatically fetched by CMake if needed):

• GoogleTest (for unit tests)
• Google Benchmark (for benchmark tests; optional)
  • Benchmark tests in bench/bench.cpp compare with Boost.
  • Boost is NOT required for the core thread pool; it is only needed if you want to run the benchmark comparisons with Boost.
    • On Ubuntu 24.04, Boost 1.83 can be installed via apt.
    • If the installed Boost version differs, adjust the path in bench/CMakeLists.txt line 19.

---

Build Instructions

Clone the repository

git clone git@github.com:TTSS0529/modern-cpp-thread-pool.git
cd modern-cpp-thread-pool

Build example & tests

mkdir build &&cd build
cmake ..
cmake --build .
./demo # Run the demo program to show basic thread pool usage
ctest -v # Run unit tests with verbose output
ctest -T memcheck # Perform memory checks to detect leaks or errors

Benchmark(run in /build/)

# Configure the project to build the benchmark in Release mode
cmake -DTHREADPOOL_BUILD_BENCHMARK=ON -DCMAKE_BUILD_TYPE=Release ..
cmake --build .# Run the benchmark with a neutral CPU personality to avoid architecture-specific optimizations
setarch $(uname -m) -R ./bench/pool_bench

This benchmark compares this ThreadPool with Boost.Asio’s thread pool. It submits a large number of CPU-bound tasks (dummy_task) in chunks, measures execution time, and evaluates performance across different thread counts, task sizes, and chunk sizes. Use it to check throughput, scalability, and optimal configuration of this thread pool.

Benchmark Results (Time in ms)

Performance Difference Formula:
[ \text{Diff (%)} = \frac{\text{MyThreadPool} - \text{BoostThreadPool}}{\text{BoostThreadPool}} \times 100 ]

Positive value → MyThreadPool is slower
Negative value → MyThreadPool is faster

Threads	Tasks	Task Size	MyThreadPool (ms)	BoostThreadPool (ms)	Diff (%)
1	100k	1k	842.33	839.12	0.38
1	100k	10k	836.84	842.69	-0.70
1	1M	1k	8464.96	8382.84	0.98
1	1M	10k	8436.11	8453.47	-0.20
2	100k	1k	422.26	422.52	-0.06
2	100k	10k	415.06	417.70	-0.63
2	1M	1k	4209.31	4216.39	-0.17
2	1M	10k	4222.16	4216.77	0.13
4	100k	1k	264.42	269.07	-1.73
4	100k	10k	300.37	299.79	0.20
4	1M	1k	2640.90	2647.72	-0.26
4	1M	10k	2662.15	2742.34	-2.90
8	100k	1k	221.21	224.00	-1.26
8	100k	10k	256.35	258.22	-0.73
8	1M	1k	2233.51	2247.67	-0.63
8	1M	10k	2253.35	2286.54	-1.45
16	100k	1k	189.09	188.61	0.26
16	100k	10k	220.12	220.92	-0.36
16	1M	1k	1837.09	1842.14	-0.27
16	1M	10k	1884.03	1871.01	0.69
Summary:

• For small tasks (100k) or small task sizes (1k–10k), MyThreadPool and BoostThreadPool perform nearly identically, with differences mostly within ±1%.
• For large tasks (1M), differences remain small across all thread counts (1–16), typically within ±3%.
• No scenario shows a significant performance advantage for either pool; overall, MyThreadPool and BoostThreadPool are comparable.
• Slight variations (~3%) may occur due to scheduling and system load, but MyThreadPool is generally on par with BoostThreadPool.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.