Ultra-lightweight fire-and-forget thread pool. More...

#include <thread_pool.hpp>

Public Member Functions
	LightweightPoolT (size_t num_threads=std::thread::hardware_concurrency())
	Construct a lightweight pool with `num_threads` workers.
	LightweightPoolT (LightweightPoolT const &)=delete
auto	operator= (LightweightPoolT const &) -> LightweightPoolT &=delete
	~LightweightPoolT ()
Task submission
template<typename F, typename... Args>
void	post (F &&f, Args &&... args)
	Post a fire-and-forget task (throwing variant).
template<typename F, typename... Args>
auto	try_post (F &&f, Args &&... args) -> expected< void, std::error_code >
	Post a fire-and-forget task (non-throwing variant).
template<typename Iterator>
void	post_batch (Iterator begin, Iterator end)
	Post a range of callables under a single lock acquisition.
template<typename Iterator>
auto	try_post_batch (Iterator begin, Iterator end) -> expected< void, std::error_code >
	Batch post (non-throwing).
Lifecycle
void	shutdown (ShutdownPolicy policy=ShutdownPolicy::drain)
	Shut the pool down.
auto	shutdown_for (std::chrono::milliseconds timeout) -> bool
	Attempt a timed drain.
Observers
auto	size () const noexcept -> size_t
	Number of worker threads.
Thread configuration
auto	configure_threads (std::string const &name_prefix, SchedulingPolicy policy=SchedulingPolicy::OTHER, ThreadPriority priority=ThreadPriority::normal()) -> expected< void, std::error_code >
	Name, schedule and prioritize all worker threads.
auto	set_affinity (ThreadAffinity const &affinity) -> expected< void, std::error_code >
	Pin all workers to the same CPU set.
auto	distribute_across_cpus () -> expected< void, std::error_code >
	Pin each worker to a distinct CPU core (round-robin).

Detailed Description

template<size_t TaskSize = 64>
class threadschedule::LightweightPoolT< TaskSize >

Ultra-lightweight fire-and-forget thread pool.

Designed for maximum throughput on tasks whose return value is not needed. Typical measured throughput is 3x higher than submit() on e.g. HighPerformancePool on the same hardware, because LightweightPoolT avoids the overhead of std::packaged_task, std::future, and std::shared_ptr entirely.

Internal architecture: Producer(s) Single Queue Worker Threads

+---------+ +------------------+ +----------------+

| post() | ---> | SboCallable<64> | ---> | ThreadWrapper |

| post() | ---> | SboCallable<64> | ---> | ThreadWrapper |

+---------+ +------------------+ +----------------+

mutex + cond_var

threadschedule::LightweightPoolT::post
void post(F &&f, Args &&... args)
Post a fire-and-forget task (throwing variant).
Definition thread_pool.hpp:1885

threadschedule::ThreadWrapper
Owning wrapper around std::thread with RAII join-on-destroy semantics.
Definition thread_wrapper.hpp:353

Queue: Single std::queue of detail::SboCallable objects protected by one mutex + condition_variable.
Workers: ThreadWrapper instances so that thread naming, CPU affinity, and scheduling policy can be configured after construction.
SBO: Callables up to TaskSize - 8 bytes are stored inline (no heap allocation). Larger callables fall back to the heap.

What is not included (by design)

No std::future / std::packaged_task (use submit() on other pools if you need return values).
No statistics counters (HighPerformancePool::get_statistics).
No tracing hooks (HighPerformancePool::set_on_task_start).
No work stealing (single shared queue).
No ThreadRegistry auto-registration.

Execution guarantees

Every successfully posted task is guaranteed to execute (unless shutdown(ShutdownPolicy::drop_pending) is called).
Tasks are dequeued in FIFO order. Because multiple workers pop concurrently, the completion order is non-deterministic.
Exceptions thrown by tasks are silently caught; the worker continues.

Thread safety: post(), try_post(), post_batch(), and try_post_batch() may be called from any number of threads concurrently. shutdown() is internally guarded and safe to call more than once.

Lifetime: The destructor calls shutdown(ShutdownPolicy::drain) and joins all workers. It blocks until every queued task has been executed.

Choosing TaskSize: The default of 64 bytes (one x86 cache line) works well for lambdas capturing up to ~7 pointers. If your tasks capture more state, increase TaskSize to avoid the heap fallback:
LightweightPoolT<128> pool(4); // 120 bytes of inline storage

threadschedule::LightweightPoolT::LightweightPoolT
LightweightPoolT(size_t num_threads=std::thread::hardware_concurrency())
Construct a lightweight pool with num_threads workers.
Definition thread_pool.hpp:1854

Copyability / movability: Not copyable, not movable.

Template Parameters

TaskSize Total size in bytes of each detail::SboCallable slot (default 64). Usable inline buffer = TaskSize - 8 bytes on 64-bit platforms.

See also: LightweightPool (alias for LightweightPoolT<64>), ScheduledLightweightPool (scheduled variant).

Definition at line 1846 of file thread_pool.hpp.

Constructor & Destructor Documentation

◆ LightweightPoolT() [1/2]

template<size_t TaskSize = 64>

threadschedule::LightweightPoolT< TaskSize >::LightweightPoolT ( size_t num_threads = std::thread::hardware_concurrency() )

inlineexplicit

Construct a lightweight pool with num_threads workers.

Parameters

num_threads Number of worker threads (clamped to at least 1). Defaults to std::thread::hardware_concurrency().

Definition at line 1854 of file thread_pool.hpp.

Referenced by LightweightPoolT(), and operator=().

◆ LightweightPoolT() [2/2]

template<size_t TaskSize = 64>

threadschedule::LightweightPoolT< TaskSize >::LightweightPoolT ( LightweightPoolT< TaskSize > const & )

delete

References LightweightPoolT().

◆ ~LightweightPoolT()

template<size_t TaskSize = 64>

threadschedule::LightweightPoolT< TaskSize >::~LightweightPoolT ( )

inline

Definition at line 1865 of file thread_pool.hpp.

References threadschedule::drain, and shutdown().

Member Function Documentation

◆ configure_threads()

template<size_t TaskSize = 64>

auto threadschedule::LightweightPoolT< TaskSize >::configure_threads	(	std::string const &	name_prefix,
		SchedulingPolicy	policy = SchedulingPolicy::OTHER,
		ThreadPriority	priority = ThreadPriority::normal() ) -> expected<void, std::error_code>

inline

Name, schedule and prioritize all worker threads.

Workers are named name_prefix + "_0", "_1", etc.

Definition at line 2046 of file thread_pool.hpp.

References threadschedule::detail::configure_worker_threads(), threadschedule::ThreadPriority::normal(), and threadschedule::OTHER.

◆ distribute_across_cpus()

template<size_t TaskSize = 64>

auto threadschedule::LightweightPoolT< TaskSize >::distribute_across_cpus ( ) -> expected<void, std::error_code>

inline

Pin each worker to a distinct CPU core (round-robin).

Definition at line 2059 of file thread_pool.hpp.

References threadschedule::detail::distribute_workers_across_cpus().

◆ operator=()

template<size_t TaskSize = 64>

auto threadschedule::LightweightPoolT< TaskSize >::operator= ( LightweightPoolT< TaskSize > const & ) -> LightweightPoolT &=delete

delete

References LightweightPoolT().

◆ post()

template<size_t TaskSize = 64>

template<typename F, typename... Args>

void threadschedule::LightweightPoolT< TaskSize >::post	(	F &&	f,
		Args &&...	args )

inline

Post a fire-and-forget task (throwing variant).

The callable and its arguments are bound into a detail::SboCallable and pushed into the shared queue.

Template Parameters

F	Callable type.
Args	Argument types forwarded to `F`.

Exceptions

std::runtime_error If the pool is shutting down.

See also: try_post() for the non-throwing variant.

Definition at line 1885 of file thread_pool.hpp.

References try_post().

◆ post_batch()

template<size_t TaskSize = 64>

template<typename Iterator>

void threadschedule::LightweightPoolT< TaskSize >::post_batch	(	Iterator	begin,
		Iterator	end )

inline

Post a range of callables under a single lock acquisition.

More efficient than calling post() in a loop because the mutex is acquired only once and all workers are woken via notify_all().

Template Parameters

Iterator Forward iterator whose value_type is callable as void().

Exceptions

std::runtime_error If the pool is shutting down.

Definition at line 1922 of file thread_pool.hpp.

References try_post_batch().

◆ set_affinity()

template<size_t TaskSize = 64>

auto threadschedule::LightweightPoolT< TaskSize >::set_affinity ( ThreadAffinity const & affinity ) -> expected<void, std::error_code>

inline

Pin all workers to the same CPU set.

Definition at line 2053 of file thread_pool.hpp.

References threadschedule::detail::set_worker_affinity().

◆ shutdown()

template<size_t TaskSize = 64>

void threadschedule::LightweightPoolT< TaskSize >::shutdown ( ShutdownPolicy policy = ShutdownPolicy::drain )

inline

Shut the pool down.

Parameters

policy drain (default) - workers finish all queued tasks before exiting. drop_pending - the queue is cleared and only the currently executing tasks are allowed to finish.

Safe to call more than once (subsequent calls are no-ops).

Definition at line 1978 of file thread_pool.hpp.

References threadschedule::drain, and threadschedule::drop_pending.

Referenced by shutdown_for(), and ~LightweightPoolT().

◆ shutdown_for()

template<size_t TaskSize = 64>

auto threadschedule::LightweightPoolT< TaskSize >::shutdown_for ( std::chrono::milliseconds timeout ) -> bool

inline

Attempt a timed drain.

Waits up to timeout for all tasks to complete, then performs a full shutdown(drain).

Returns: true if all tasks completed within the deadline, false if the timeout expired (pool is still shut down).

Definition at line 2009 of file thread_pool.hpp.

References threadschedule::drain, and shutdown().

◆ size()

template<size_t TaskSize = 64>

auto threadschedule::LightweightPoolT< TaskSize >::size ( ) const -> size_t

inlinenodiscardnoexcept

Number of worker threads.

Definition at line 2031 of file thread_pool.hpp.

◆ try_post()

template<size_t TaskSize = 64>

template<typename F, typename... Args>

auto threadschedule::LightweightPoolT< TaskSize >::try_post	(	F &&	f,
		Args &&...	args ) -> expected<void, std::error_code>

inline

Post a fire-and-forget task (non-throwing variant).

Returns: expected<void, std::error_code> – std::errc::operation_canceled on shutdown.

Definition at line 1899 of file thread_pool.hpp.

References threadschedule::detail::bind_args().

Referenced by post().

◆ try_post_batch()

template<size_t TaskSize = 64>

template<typename Iterator>

auto threadschedule::LightweightPoolT< TaskSize >::try_post_batch	(	Iterator	begin,
		Iterator	end ) -> expected<void, std::error_code>

inline

Batch post (non-throwing).

Returns: expected<void, std::error_code>.

Definition at line 1934 of file thread_pool.hpp.

Referenced by post_batch().

The documentation for this class was generated from the following file:

thread_pool.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ LightweightPoolT() [1/2]

◆ LightweightPoolT() [2/2]

◆ ~LightweightPoolT()

Member Function Documentation

◆ configure_threads()

◆ distribute_across_cpus()

◆ operator=()

◆ post()

◆ post_batch()

◆ set_affinity()

◆ shutdown()

◆ shutdown_for()

◆ size()

◆ try_post()

◆ try_post_batch()