task-thread-pool is a fast and lightweight thread pool for C++11 and newer.

Easily add parallelism to your project without introducing heavy dependencies.

• Focus on correctness, ease of use, simplicity, performance.
• Small single header file and permissive licensing means easy integration.
• Tested on all major platforms and compilers:
  • Linux, macOS, Windows
  • GCC, LLVM/Clang, MSVC, MinGW, Emscripten
    • CI tests on GCC 7+ and LLVM 7+, should work on older
  • C++11, C++14, C++17, C++20, C++23
• Comprehensive test suite, including stress tests.
• Benchmarks help confirm good performance.

Usage

#include <task_thread_pool.hpp>

task_thread_pool::task_thread_pool pool; // num_threads = number of physical cores
// or
task_thread_pool::task_thread_pool pool{4}; // num_threads = 4

Submit a function, a lambda, std::packaged_task, std::function, or any Callable, and its arguments:

pool.submit_detach( [](int arg) { std::cout << arg; }, 123456 );

To track task return values (and thrown exceptions), use submit() which returns an std::future:

std::future<int> future = pool.submit([] { return 1; });

int result = future.get(); // returns 1

std::future::get() waits for the task to complete.

To wait for all tasks to complete:

pool.wait_for_tasks();

Parallel Loops and More

Use poolSTL to parallelize loops, transforms, sorts, and other standard library algorithms using this thread pool. This approach is easy to start with and also keeps your code future-proof by employing standard C++ mechanisms. It is easy to later change parallelism libraries (or start using the compiler-provided ones, once they're available to you).

For example, use std::for_each to parallelize for and for-each loops:

std::vector<int> v = {0, 1, 2, 3, 4, 5};
task_thread_pool::task_thread_pool pool;

// parallel for
using poolstl::iota_iter;

std::for_each(poolstl::par.on(pool), iota_iter<int>(0), iota_iter<int>(v.size()), [](int i) {
    std::cout << v[i];  // loop body
});

// parallel for-each
std::for_each(poolstl::par.on(pool), v.cbegin(), v.cend(), [](auto value) {
    std::cout << value;  // loop body
});

Example

#include <iostream>
// Use #include "task_thread_pool.hpp" for relative path,
// and #include <task_thread_pool.hpp> if installed in include path
#include "task_thread_pool.hpp"

int sum(int a, int b) { return a + b; }

int main() {
    // Create a thread pool. The number of threads is equal to the number of cores in the system,
    // as given by std::thread::hardware_concurrency().
    // You can also specify the number of threads, like so: pool(4),
    // or resize the thread pool later using pool.set_num_threads(4).
    task_thread_pool::task_thread_pool pool;

    //---------------------------------------------
    // Submit a task that returns a value.
    std::future<int> one_future = pool.submit([] { return 1; });
    // Use std::future::get() to wait for the task to complete and return the value.
    std::cout << "Task returned: " << one_future.get() << std::endl;

    //---------------------------------------------
    // Tasks may have arguments:
    std::future<int> sum_future = pool.submit(&sum, 1, 2);
    std::cout << "Sum = " << sum_future.get() << std::endl;

    //---------------------------------------------
    // Submit a task that we don't need to track the execution of:
    pool.submit_detach([](int arg) {
        std::cout << "The argument is: " << arg << std::endl;
    }, 42);

    //---------------------------------------------
    // Wait for all tasks to complete:
    pool.wait_for_tasks();

    //---------------------------------------------
    // The pool can be paused:
    pool.pause();

    // Submit a task that won't be started until the pool is unpaused.
    std::future<void> paused_future = pool.submit([] {
        std::cout << "Paused task executes" << std::endl;
    });

    // prints 1
    std::cout << "Number of tasks in the pool: " << pool.get_num_tasks() << std::endl;
    
    // Resume executing queued tasks.
    pool.unpause();

    // Wait for the task to finish.
    paused_future.get();

    // prints 0
    std::cout << "Number of tasks in the pool: " << pool.get_num_tasks() << std::endl;

    //---------------------------------------------
    // All queued tasks are executed before the pool is destroyed:
    pool.submit_detach([]{
        std::cout << "One last task" << std::endl;
    });

    return 0;
}

Installation

Copy

task-thread-pool is a single header file.

You may simply copy task_thread_pool.hpp into your project or your system include/.

CMake

You may use CMake to fetch directly from GitHub:

include(FetchContent)
FetchContent_Declare(
        task-thread-pool
        GIT_REPOSITORY https://github.com/alugowski/task-thread-pool
        GIT_TAG main
        GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(task-thread-pool)

target_link_libraries(YOUR_TARGET task-thread-pool::task-thread-pool)

Use GIT_TAG main to use the latest version, or replace main with a version number to pin a fixed version.

vcpkg

vcpkg install task-thread-pool

Note for Clang and GCC <9 users

Some compilers, including non-Apple Clang and GCC 8 and older, require the -lpthread linker flag to use C++11 threads. The above CMake instructions will do that automatically.

How it works

Simplicity is a major goal so this thread pool does what you'd expect. Submitted tasks are added to a queue and worker threads pull from this queue.

Care is taken that this process is efficient. The submit methods are optimized to only do what they need. Worker threads only lock the queue once per task. Excess synchronization is avoided.

That said, this simple design is best used in low contention scenarios. If you have many tiny tasks or many (10+) physical CPU cores then this single queue becomes a hotspot. In that case avoid lightweight pools like this one and use something like Threading Building Blocks. They include work-stealing executors that avoid this hotspot at the cost of extra complexity and project dependencies.

Benchmarking

We include some Google Benchmarks for some pool operations in benchmark/.

If there is an operation you care about feel free to open an issue or submit your own benchmark code.

-------------------------------------------------------------------------------
Benchmark                                     Time             CPU   Iterations
-------------------------------------------------------------------------------
pool_create_destroy                       46318 ns        26004 ns        26489
submit_detach_packaged_task/paused:1        254 ns          244 ns      2875157
submit_detach_packaged_task/paused:0        362 ns          304 ns      2296008
submit_detach_void_lambda/paused:1          263 ns          260 ns      3072412
submit_detach_void_lambda/paused:0          418 ns          374 ns      2020779
submit_void_lambda/paused:1                 399 ns          385 ns      1942879
submit_void_lambda/paused:0                 667 ns          543 ns      1257161
submit_void_lambda_future/paused:1          391 ns          376 ns      1897255
submit_void_lambda_future/paused:0          649 ns          524 ns      1238653
submit_int_lambda_future/paused:1           395 ns          376 ns      1902789
submit_int_lambda_future/paused:0           643 ns          518 ns      1146038
run_1k_packaged_tasks                    462965 ns       362080 ns         1939
run_1k_void_lambdas                      492022 ns       411069 ns         1712
run_1k_int_lambdas                       679579 ns       533813 ns         1368