Single-queue thread pool parameterized by its idle-wait strategy. More...

#include <thread_pool_backend_base.hpp>

Classes
struct	statistics

Public Types
using	task_type = std::function< void()>

using	queued_task = detail::move_only_function< void()>

Public Member Functions
	thread_pool_backend_base (size_t num_threads=default_worker_count(), bool register_workers=false)

	thread_pool_backend_base (thread_pool_backend_base const &)=delete

auto	operator= (thread_pool_backend_base const &) -> thread_pool_backend_base &=delete

	~thread_pool_backend_base ()

Task submission
template<typename F , typename... Args>
auto	try_submit (F &&f, Args &&... args) -> expected< std::future< bind_result_t< F, Args... > >, std::error_code >
	Submit a task without throwing on shutdown.

template<typename F , typename... Args>
auto	submit (F &&f, Args &&... args) -> std::future< bind_result_t< F, Args... > >
	Submit a task, throwing on shutdown.

template<typename F , typename... Args>
void	post (F &&f, Args &&... args)
	Fire-and-forget task submission (throwing variant).

template<typename F , typename... Args>
auto	try_post (F &&f, Args &&... args) -> expected< void, std::error_code >
	Fire-and-forget task submission (non-throwing variant).

template<typename Iterator >
auto	try_submit_batch (Iterator begin, Iterator end) -> expected< std::vector< std::future< void > >, std::error_code >
	Submit a range of `void()` callables in one go (non-throwing).

template<typename Iterator >
auto	submit_batch (Iterator begin, Iterator end) -> std::vector< std::future< void > >
	Submit a batch of tasks (throwing).

template<typename Iterator , typename F >
void	parallel_for_each (Iterator begin, Iterator end, F &&func)
	Apply `func` to [begin, end) in parallel (chunked).

Observers
auto	size () const noexcept -> size_t
	Number of worker threads.

auto	pending_tasks () const -> size_t
	Number of tasks waiting in the queue.

auto	get_statistics () const -> statistics
	Collect approximate performance counters.

Thread configuration
auto	configure_threads (std::string const &name_prefix, native_scheduling_policy policy=native_scheduling_policy::other, native_thread_priority priority=native_thread_priority::normal()) -> expected< void, std::error_code >
	Name, schedule and prioritize all worker threads.

auto	configure_threads (native_thread_config const &config) -> expected< void, std::error_code >

auto	set_affinity (native_thread_affinity 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).

Synchronisation & lifecycle
void	wait_for_tasks ()
	Block until all pending and active tasks have completed.

auto	is_current_worker () const noexcept -> bool

void	shutdown (shutdown_policy_backend policy=shutdown_policy_backend::drain)
	Shut the pool down.

auto	shutdown_for (std::chrono::milliseconds timeout) -> bool
	Attempt a timed drain: finish as many tasks as possible within `timeout`, then discard queued work.

Tracing hooks
void	set_on_task_start (task_start_callback cb)
	Register a callback invoked just before each task executes.

template<typename Callback , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< Callback >, task_start_callback >, int > = 0>
void	set_on_task_start (Callback &&cb)

void	set_on_task_end (task_end_callback cb)
	Register a callback invoked just after each task completes.

template<typename Callback , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< Callback >, task_end_callback >, int > = 0>
void	set_on_task_end (Callback &&cb)

Detailed Description

template<typename WaitPolicy>
class threadschedule::detail::thread_pool_backend_base< WaitPolicy >

Single-queue thread pool parameterized by its idle-wait strategy.

All tasks share one std::queue protected by a single mutex. The WaitPolicy template parameter controls how workers wait for new work:

indefinite_wait - blocks on condition_variable::wait() (zero CPU while idle, instant wake). Instantiated as thread_pool_backend.
polling_wait - polls with condition_variable::wait_for(10 ms). Slightly higher idle CPU but lower worst-case latency under bursty loads. Instantiated as polling_pool_backend.

How task execution works: When you call submit(), the callable is wrapped in a std::packaged_task, pushed into the shared task queue under a mutex lock, and one sleeping worker is woken via condition_variable::notify_one(). The woken worker pops the front element and executes it.

Execution guarantees

Every successfully submitted task (submit() returned without throwing) is guaranteed to eventually execute.
submit() throws std::runtime_error if the pool is already shutting down. In that case the task is NOT enqueued.
Tasks are stored in a FIFO queue. Multiple workers pop concurrently, so submission order is roughly preserved but completion order is non-deterministic.
The returned std::future becomes ready once the task finishes. If the task threw an exception, future.get() rethrows it.
On shutdown(), workers finish their current task, then drain all remaining queued tasks before exiting.
wait_for_tasks() blocks until the queue is empty AND no worker is currently executing a task.

Thread safety: submit() and submit_batch() may be called from any thread concurrently. shutdown() is internally guarded and safe to call more than once.

Exception handling: Exceptions thrown by tasks are caught inside the worker loop. They are stored in the std::future returned by submit(). The worker thread continues processing.

Lifetime: The destructor calls shutdown() and joins all worker threads. Can block if tasks are still running.

Copyability / movability: Not copyable, not movable.

Template Parameters

WaitPolicy Strategy type with a static wait(cv, lock, predicate) -> bool method.

Definition at line 97 of file thread_pool_backend_base.hpp.

Member Typedef Documentation

◆ queued_task

template<typename WaitPolicy >

using threadschedule::detail::thread_pool_backend_base< WaitPolicy >::queued_task = detail::move_only_function<void()>

Definition at line 101 of file thread_pool_backend_base.hpp.

◆ task_type

template<typename WaitPolicy >

using threadschedule::detail::thread_pool_backend_base< WaitPolicy >::task_type = std::function<void()>

Definition at line 100 of file thread_pool_backend_base.hpp.

Constructor & Destructor Documentation

◆ thread_pool_backend_base() [1/2]

template<typename WaitPolicy >

threadschedule::detail::thread_pool_backend_base< WaitPolicy >::thread_pool_backend_base	(	size_t	num_threads = `default_worker_count()`,
		bool	register_workers = `false`
	)

inlineexplicit

Definition at line 113 of file thread_pool_backend_base.hpp.

References threadschedule::detail::worker_startup_latch::wait().

◆ thread_pool_backend_base() [2/2]

template<typename WaitPolicy >

threadschedule::detail::thread_pool_backend_base< WaitPolicy >::thread_pool_backend_base ( thread_pool_backend_base< WaitPolicy > const & )

delete

◆ ~thread_pool_backend_base()

template<typename WaitPolicy >

threadschedule::detail::thread_pool_backend_base< WaitPolicy >::~thread_pool_backend_base ( )

inline

Definition at line 139 of file thread_pool_backend_base.hpp.

References threadschedule::detail::drain, and threadschedule::detail::thread_pool_backend_base< WaitPolicy >::shutdown().

Member Function Documentation

◆ configure_threads() [1/2]

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::configure_threads ( native_thread_config const & config ) -> expected<void, std::error_code>

inline

Definition at line 333 of file thread_pool_backend_base.hpp.

References threadschedule::detail::configure_worker_threads(), and threadschedule::detail::runtime_registry().

◆ configure_threads() [2/2]

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::configure_threads	(	std::string const &	name_prefix,
		native_scheduling_policy	policy = `native_scheduling_policy::other`,
		native_thread_priority	priority = `native_thread_priority::normal()`
	)		-> expected<void, std::error_code>

inline

Name, schedule and prioritize all worker threads.

See also: work_stealing_pool_backend::configure_threads

Definition at line 324 of file thread_pool_backend_base.hpp.

References threadschedule::detail::configure_worker_threads(), and threadschedule::detail::runtime_registry().

◆ distribute_across_cpus()

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::distribute_across_cpus ( ) -> expected<void, std::error_code>

inline

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

Definition at line 347 of file thread_pool_backend_base.hpp.

References threadschedule::detail::distribute_workers_across_cpus().

◆ get_statistics()

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::get_statistics ( ) const -> statistics

inline

Collect approximate performance counters.

Definition at line 475 of file thread_pool_backend_base.hpp.

References threadschedule::detail::thread_pool_backend_base< WaitPolicy >::statistics::active_threads, threadschedule::detail::thread_pool_backend_base< WaitPolicy >::statistics::avg_task_time, threadschedule::detail::thread_pool_backend_base< WaitPolicy >::statistics::completed_tasks, threadschedule::detail::thread_pool_backend_base< WaitPolicy >::statistics::pending_tasks, threadschedule::detail::thread_pool_backend_base< WaitPolicy >::statistics::tasks_per_second, and threadschedule::detail::thread_pool_backend_base< WaitPolicy >::statistics::total_threads.

◆ is_current_worker()

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::is_current_worker ( ) const -> bool

inlinenoexcept

Definition at line 369 of file thread_pool_backend_base.hpp.

Referenced by threadschedule::detail::thread_pool_backend_base< WaitPolicy >::parallel_for_each(), threadschedule::detail::thread_pool_backend_base< WaitPolicy >::shutdown(), threadschedule::detail::thread_pool_backend_base< WaitPolicy >::shutdown_for(), and threadschedule::detail::thread_pool_backend_base< WaitPolicy >::wait_for_tasks().

◆ operator=()

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::operator= ( thread_pool_backend_base< WaitPolicy > const & ) -> thread_pool_backend_base &=delete

delete

◆ parallel_for_each()

template<typename WaitPolicy >

template<typename Iterator , typename F >

void threadschedule::detail::thread_pool_backend_base< WaitPolicy >::parallel_for_each	(	Iterator	begin,
		Iterator	end,
		F &&	func
	)

inline

Apply func to [begin, end) in parallel (chunked).

Template Parameters

Iterator Forward iterator; task chunks retain iterator pairs.

Definition at line 287 of file thread_pool_backend_base.hpp.

References threadschedule::detail::thread_pool_backend_base< WaitPolicy >::is_current_worker(), threadschedule::detail::parallel_for_each_chunked(), and threadschedule::detail::throw_worker_deadlock().

◆ pending_tasks()

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::pending_tasks ( ) const -> size_t

inline

Number of tasks waiting in the queue.

Definition at line 308 of file thread_pool_backend_base.hpp.

◆ post()

template<typename WaitPolicy >

template<typename F , typename... Args>

void threadschedule::detail::thread_pool_backend_base< WaitPolicy >::post	(	F &&	f,
		Args &&...	args
	)

inline

Fire-and-forget task submission (throwing variant).

Bypasses std::packaged_task / std::future for lower overhead.

Exceptions

std::runtime_error If the pool is shutting down.

See also: try_post()

Definition at line 198 of file thread_pool_backend_base.hpp.

References threadschedule::detail::thread_pool_backend_base< WaitPolicy >::try_post().

◆ set_affinity()

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::set_affinity ( native_thread_affinity const & affinity ) -> expected<void, std::error_code>

inline

Pin all workers to the same CPU set.

Definition at line 340 of file thread_pool_backend_base.hpp.

References threadschedule::detail::set_worker_affinity().

◆ set_on_task_end() [1/2]

template<typename WaitPolicy >

template<typename Callback , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< Callback >, task_end_callback >, int > = 0>

void threadschedule::detail::thread_pool_backend_base< WaitPolicy >::set_on_task_end ( Callback && cb )

inline

Definition at line 552 of file thread_pool_backend_base.hpp.

References threadschedule::detail::make_copyable_function().

◆ set_on_task_end() [2/2]

template<typename WaitPolicy >

void threadschedule::detail::thread_pool_backend_base< WaitPolicy >::set_on_task_end ( task_end_callback cb )

inline

Register a callback invoked just after each task completes.

Parameters

cb	Receives the end time, the worker's `std::thread::id`, and the wall-clock duration of the task.

Definition at line 543 of file thread_pool_backend_base.hpp.

◆ set_on_task_start() [1/2]

template<typename WaitPolicy >

template<typename Callback , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< Callback >, task_start_callback >, int > = 0>

void threadschedule::detail::thread_pool_backend_base< WaitPolicy >::set_on_task_start ( Callback && cb )

inline

Definition at line 528 of file thread_pool_backend_base.hpp.

◆ set_on_task_start() [2/2]

template<typename WaitPolicy >

void threadschedule::detail::thread_pool_backend_base< WaitPolicy >::set_on_task_start ( task_start_callback cb )

inline

Register a callback invoked just before each task executes.

Parameters

cb	Receives the start time and the worker's `std::thread::id`.

Definition at line 519 of file thread_pool_backend_base.hpp.

◆ shutdown()

template<typename WaitPolicy >

void threadschedule::detail::thread_pool_backend_base< WaitPolicy >::shutdown ( shutdown_policy_backend policy = shutdown_policy_backend::drain )

inline

Shut the pool down.

Parameters

policy drain (default) finishes all queued tasks; drop_pending discards queued tasks.

Definition at line 380 of file thread_pool_backend_base.hpp.

References threadschedule::detail::drop_pending, threadschedule::detail::thread_pool_backend_base< WaitPolicy >::is_current_worker(), and threadschedule::detail::throw_worker_deadlock().

Referenced by threadschedule::detail::thread_pool_backend_base< WaitPolicy >::~thread_pool_backend_base().

◆ shutdown_for()

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::shutdown_for ( std::chrono::milliseconds timeout ) -> bool

inline

Attempt a timed drain: finish as many tasks as possible within timeout, then discard queued work.

New submissions are rejected before the timed wait begins. Running C++ callables cannot be stopped safely, so this function can return after the timeout while an already-running task finishes.

Returns: true if all tasks completed within the deadline, false if the timeout expired first.

Definition at line 425 of file thread_pool_backend_base.hpp.

References threadschedule::detail::thread_pool_backend_base< WaitPolicy >::is_current_worker(), threadschedule::detail::shutdown_deadline_after(), and threadschedule::detail::throw_worker_deadlock().

◆ size()

template<typename WaitPolicy >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::size ( ) const -> size_t

inlinenoexcept

Number of worker threads.

Definition at line 301 of file thread_pool_backend_base.hpp.

◆ submit()

template<typename WaitPolicy >

template<typename F , typename... Args>

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::submit	(	F &&	f,
		Args &&...	args
	)		-> std::future<bind_result_t<F, Args...>>

inline

Submit a task, throwing on shutdown.

Exceptions

std::runtime_error If the pool is shutting down.

Definition at line 180 of file thread_pool_backend_base.hpp.

References threadschedule::expected< T, E >::has_value(), threadschedule::detail::thread_pool_backend_base< WaitPolicy >::try_submit(), and threadschedule::expected< T, E >::value().

◆ submit_batch()

template<typename WaitPolicy >

template<typename Iterator >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::submit_batch	(	Iterator	begin,
		Iterator	end
	)		-> std::vector<std::future<void>>

inline

Submit a batch of tasks (throwing).

See also: try_submit_batch()

Definition at line 275 of file thread_pool_backend_base.hpp.

References threadschedule::expected< T, E >::has_value(), threadschedule::detail::thread_pool_backend_base< WaitPolicy >::try_submit_batch(), and threadschedule::expected< T, E >::value().

◆ try_post()

template<typename WaitPolicy >

template<typename F , typename... Args>

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

inline

Fire-and-forget task submission (non-throwing variant).

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

Definition at line 212 of file thread_pool_backend_base.hpp.

References threadschedule::detail::bind_args().

Referenced by threadschedule::detail::thread_pool_backend_base< WaitPolicy >::post().

◆ try_submit()

template<typename WaitPolicy >

template<typename F , typename... Args>

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::try_submit	(	F &&	f,
		Args &&...	args
	)		-> expected<std::future<bind_result_t<F, Args...>>, std::error_code>

inline

Submit a task without throwing on shutdown.

Returns: expected<std::future<R>, std::error_code>.

See also: submit() for the throwing variant.

Definition at line 154 of file thread_pool_backend_base.hpp.

References threadschedule::detail::bind_args().

Referenced by threadschedule::detail::thread_pool_backend_base< WaitPolicy >::submit().

◆ try_submit_batch()

template<typename WaitPolicy >

template<typename Iterator >

auto threadschedule::detail::thread_pool_backend_base< WaitPolicy >::try_submit_batch	(	Iterator	begin,
		Iterator	end
	)		-> expected<std::vector<std::future<void>>, std::error_code>

inline

Submit a range of void() callables in one go (non-throwing).

All tasks are enqueued under a single lock acquisition.

Template Parameters

Iterator Input iterator whose value is callable as void().

Definition at line 233 of file thread_pool_backend_base.hpp.

References threadschedule::detail::multipass_range_size().

Referenced by threadschedule::detail::thread_pool_backend_base< WaitPolicy >::submit_batch().

◆ wait_for_tasks()

template<typename WaitPolicy >

void threadschedule::detail::thread_pool_backend_base< WaitPolicy >::wait_for_tasks ( )

inline

Block until all pending and active tasks have completed.

Definition at line 359 of file thread_pool_backend_base.hpp.

References threadschedule::detail::thread_pool_backend_base< WaitPolicy >::is_current_worker(), and threadschedule::detail::throw_worker_deadlock().

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

thread_pool_backend_base.hpp

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ queued_task

◆ task_type

Constructor & Destructor Documentation

◆ thread_pool_backend_base() [1/2]

◆ thread_pool_backend_base() [2/2]

◆ ~thread_pool_backend_base()

Member Function Documentation

◆ configure_threads() [1/2]

◆ configure_threads() [2/2]

◆ distribute_across_cpus()

◆ get_statistics()

◆ is_current_worker()

◆ operator=()

◆ parallel_for_each()

◆ pending_tasks()

◆ post()

◆ set_affinity()

◆ set_on_task_end() [1/2]

◆ set_on_task_end() [2/2]

◆ set_on_task_start() [1/2]

◆ set_on_task_start() [2/2]

◆ shutdown()

◆ shutdown_for()

◆ size()

◆ submit()

◆ submit_batch()

◆ try_post()

◆ try_submit()

◆ try_submit_batch()

◆ wait_for_tasks()