thread_pool.H File Reference

A modern, efficient thread pool for parallel task execution. More...

#include <future>
#include <queue>
#include <functional>
#include <algorithm>
#include <condition_variable>
#include <atomic>
#include <vector>
#include <thread>
#include <mutex>
#include <stdexcept>
#include <type_traits>
#include <tuple>
#include <memory>
#include <limits>
#include <optional>
#include <chrono>
#include <numeric>
#include <iterator>
#include <string>

Include dependency graph for thread_pool.H:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	Aleph::operation_canceled
	Exception thrown when cooperative cancellation is observed. More...
struct	Aleph::CancellationState
	Shared state for cooperative cancellation. More...
class	Aleph::CancellationToken
	Read-only cooperative cancellation token. More...
class	Aleph::CancellationToken::ConditionVariableRegistration
	RAII guard for condition variable cancellation registration. More...
class	Aleph::CancellationSource
	Cooperative cancellation source paired with CancellationToken. More...
struct	Aleph::ParallelOptions
	Common configuration object for parallel algorithms. More...
class	Aleph::queue_overflow_error
	Exception thrown when the task queue exceeds its hard limit. More...
struct	Aleph::ThreadPoolStats
	Statistics collected by ThreadPool. More...
class	Aleph::ThreadPool
	A reusable thread pool for efficient parallel task execution. More...
struct	Aleph::ThreadPool::TaskBase
	Type-erased task wrapper. More...
struct	Aleph::ThreadPool::Task< F >
	Concrete task implementation with type preservation. More...
class	Aleph::TaskGroup
	Minimal structured-concurrency helper over ThreadPool futures. More...

Namespaces
namespace	Aleph
	Main namespace for Aleph-w library functions.
namespace	Aleph::parallel_detail

Typedefs
using	Aleph::ExceptionCallback = std::function< void(std::exception_ptr)>
	Type for exception callback in detached tasks.

Functions
ThreadPool &	Aleph::default_pool ()
	Return the default shared thread pool instance.
ThreadPool &	Aleph::parallel_detail::select_pool (const ParallelOptions &options)
size_t	Aleph::parallel_detail::resolve_chunk_size (const size_t total, const size_t num_threads, const ParallelOptions &options, const size_t min_chunk=1)
bool	Aleph::parallel_detail::use_sequential_path (const size_t total, const ThreadPool &pool, const ParallelOptions &options) noexcept
void	Aleph::parallel_detail::throw_if_canceled (const CancellationToken &token)
template<typename InputIt1 , typename InputIt2 , typename OutputIt , typename Compare >
void	Aleph::parallel_detail::merge_sequential (InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2, OutputIt d_first, Compare comp, const CancellationToken &token)
template<typename Iterator , typename F >
void	Aleph::parallel_for (ThreadPool &pool, Iterator begin, Iterator end, F &&f, size_t chunk_size=0)
	Execute a function in parallel over a range.
template<typename Iterator , typename F >
void	Aleph::parallel_for (Iterator begin, Iterator end, F &&f, const ParallelOptions &options={})
	Execute a function in parallel over a range with explicit options.
template<typename InputIt , typename OutputIt , typename F >
OutputIt	Aleph::parallel_transform (ThreadPool &pool, InputIt first, InputIt last, OutputIt d_first, F &&f, size_t chunk_size=0)
	Transform elements in parallel and store results.
template<typename InputIt , typename OutputIt , typename F >
OutputIt	Aleph::parallel_transform (InputIt first, InputIt last, OutputIt d_first, F &&f, const ParallelOptions &options={})
	Parallel transform with explicit options.
template<typename Iterator , typename T , typename BinaryOp >
T	Aleph::parallel_reduce (ThreadPool &pool, Iterator first, Iterator last, T init, BinaryOp op, size_t chunk_size=0)
	Reduce elements in parallel.
template<typename Iterator , typename T , typename BinaryOp >
T	Aleph::parallel_reduce (Iterator first, Iterator last, T init, BinaryOp op, const ParallelOptions &options={})
	Parallel reduce with explicit options.
template<typename F >
void	Aleph::parallel_for_index (ThreadPool &pool, size_t start, size_t end, F &&f, size_t chunk_size=0)
	Apply a function to each element in parallel (index-based).
template<typename F >
void	Aleph::parallel_for_index (size_t start, size_t end, F &&f, const ParallelOptions &options={})
	Parallel index loop with explicit options.
template<typename... Fs>
void	Aleph::parallel_invoke (ThreadPool &pool, Fs &&... fs)
	Invoke a small set of related callables in parallel.
template<typename... Fs>
void	Aleph::parallel_invoke (const ParallelOptions &options, Fs &&... fs)
	parallel_invoke with explicit options.
template<typename InputIt , typename OutputIt , typename BinaryOp >
OutputIt	Aleph::pscan (ThreadPool &pool, InputIt first, InputIt last, OutputIt d_first, BinaryOp op, size_t chunk_size=0)
	Inclusive prefix scan over a range.
template<typename InputIt , typename OutputIt , typename BinaryOp >
OutputIt	Aleph::pscan (InputIt first, InputIt last, OutputIt d_first, BinaryOp op, const ParallelOptions &options={})
	Inclusive prefix scan with explicit options.
template<typename InputIt , typename OutputIt , typename T , typename BinaryOp >
OutputIt	Aleph::pexclusive_scan (ThreadPool &pool, InputIt first, InputIt last, OutputIt d_first, T init, BinaryOp op, size_t chunk_size=0)
	Exclusive prefix scan over a range.
template<typename InputIt , typename OutputIt , typename T , typename BinaryOp >
OutputIt	Aleph::pexclusive_scan (InputIt first, InputIt last, OutputIt d_first, T init, BinaryOp op, const ParallelOptions &options={})
	Exclusive prefix scan with explicit options.
template<typename InputIt1 , typename InputIt2 , typename OutputIt , typename Compare = std::less<>>
OutputIt	Aleph::pmerge (ThreadPool &pool, InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2, OutputIt d_first, Compare comp=Compare{}, size_t chunk_size=0)
	Merge two sorted ranges in parallel.
template<typename InputIt1 , typename InputIt2 , typename OutputIt , typename Compare = std::less<>>
OutputIt	Aleph::pmerge (InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2, OutputIt d_first, Compare comp=Compare{}, const ParallelOptions &options={})
	Parallel merge with explicit options.

Detailed Description

A modern, efficient thread pool for parallel task execution.

This file provides a reusable thread pool that maintains a fixed number of worker threads, avoiding the overhead of creating new threads for each task (as happens with std::async).

Features

• Zero thread creation overhead: Workers are pre-created and reused
• Type-safe: Full template support with automatic return type deduction
• Future-based: Returns std::future<T> for result retrieval
• Exception-safe: Exceptions propagate through futures
• Resizable: Can dynamically adjust the number of workers
• Move-only support: Accepts move-only callables and arguments
• Member functions: Direct support via std::invoke

Performance Comparison

Method	Overhead per task
std::async	10-100 μs (thread creation)
ThreadPool	~50-100 ns (queue + notify)

Supported Callable Types

• Lambdas (including move-only captures)
• Free functions
• Function pointers
• Functors (function objects)
• std::function
• Member function pointers (with object)
• std::bind expressions

Usage Examples

#include <thread_pool.H>
 
Aleph::ThreadPool pool(4);
 
// Lambda with arguments
auto f1 = pool.enqueue([](int x, int y) { return x + y; }, 10, 20);
 
// Free function
auto f2 = pool.enqueue(std::sqrt, 16.0);
 
// Member function
struct Calculator {
  int multiply(int a, int b) { return a * b; }
};
Calculator calc;
auto f3 = pool.enqueue(&Calculator::multiply, &calc, 6, 7);
 
// Move-only lambda
auto ptr = std::make_unique<int>(42);
auto f4 = pool.enqueue([p = std::move(ptr)]() { return *p; });
 
// Fire-and-forget (no future overhead)
pool.enqueue_detached([] { std::cout << "Background task\n"; });
 
std::cout << f1.get() << " " << f2.get() << " " << f3.get() << " " << f4.get();
// Output: 30 4 42 42

Thread Safety

• enqueue() and enqueue_detached() are thread-safe
• resize() and shutdown() should not be called concurrently with each other

See also

worker_pool.H Alternative with different API

future_utils.H Utilities for working with futures

Author

Leandro Rabindranath León

Definition in file thread_pool.H.