BS::thread_pool: a fast, lightweight, modern, and easy-to-use C++17 / C++20 / C++23 thread pool library

By Barak Shoshany
Email: baraksh@gmail.com
Website: https://baraksh.com/
GitHub: https://github.com/bshoshany

This is the complete documentation for v5.1.0 of the library, released on 2026-01-03.

• Introduction
  • Motivation
  • Overview of features
• Getting started
  • Installing the library
  • Compiling and compatibility
  • Constructors
  • Getting and resetting the number of threads in the pool
• Submitting tasks to the queue
  • Submitting tasks with no arguments and receiving a future
  • Submitting tasks with arguments and receiving a future
  • Detaching and waiting for tasks
  • Waiting for submitted or detached tasks with a timeout
  • Class member functions as tasks
• Parallelizing loops
  • Automatic parallelization of loops
  • Optimizing the number of blocks
  • Common index types
  • Parallelizing loops without futures
  • Parallelizing individual indices vs. blocks
  • Loops with return values
  • Parallelizing sequences

Introduction

Motivation

Multithreading is essential for modern high-performance computing. Since C++11, the C++ standard library has included built-in low-level multithreading support using constructs such as std::thread. However, std::thread creates a new thread each time it is called, which can have a significant performance overhead. Furthermore, it is possible to create more threads than the hardware can handle simultaneously, potentially resulting in a substantial slowdown.

The library presented here contains a C++ thread pool class, BS::thread_pool, which avoids these issues by creating a fixed pool of threads once and for all, and then continuously reusing the same threads to perform different tasks throughout the lifetime of the program. By default, the number of threads in the pool is equal to the maximum number of threads that the hardware can run in parallel.

The user submits tasks to be executed into a queue. Whenever a thread becomes available, it retrieves the next task from the queue and executes it. The pool optionally produces an std::future for each task, which allows the user to wait for the task to finish executing and/or obtain its eventual return value, if applicable. Threads and tasks are autonomously managed by the pool in the background, without requiring any input from the user aside from submitting the desired tasks.

The design of this library is guided by four important principles. First, compactness: the entire library consists of just one self-contained header file, with no other components or dependencies. Second, portability: the library only utilizes the C++ standard library, without relying on any compiler extensions or 3rd-party libraries, and is therefore compatible with any modern standards-conforming C++ compiler on any platform, as long as it supports C++17 or later. Third, ease of use: the library is extensively documented, and programmers of any level should be able to use it right out of the box.

The fourth and final guiding principle is performance: each and every line of code in this library was carefully designed with maximum performance in mind, and performance was tested and verified on a variety of compilers and platforms. Indeed, the library was originally designed for use in the author's own computationally-intensive scientific computing projects, running both on high-end desktop/laptop computers and high-performance computing nodes.

Among the available C++ thread pool libraries, BS::thread_pool occupies the crucial middle ground between small bare-bones thread pool classes that offer rudimentary functionality and are only suitable for simple programs, and very large libraries that offer many advanced features but consist of multiple components and dependencies and involve complex APIs that require a substantial time investment to learn. BS::thread_pool was designed for users who want a simple and lightweight header-only library that is easy to learn and use, and can be readily incorporated into existing or new projects, but do not want to compromise on performance or functionality.

Obtaining the library is quick and easy; it can be downloaded manually from [the GitHub repository](https://github.com/bshoshany/