Thread pool augmented with delayed and periodic task scheduling. More...

#include <scheduled_pool_backend_base.hpp>

Classes
struct	periodic_task_state

struct	scheduled_dispatch_state

class	scheduled_task_info

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

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

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

using	time_point = std::chrono::steady_clock::time_point

using	duration = std::chrono::steady_clock::duration

Public Member Functions
	scheduled_pool_backend_base (size_t worker_threads=default_worker_count())
	Create a scheduled thread pool.

template<typename T = PoolType, std::enable_if_t< std::is_constructible_v< T, size_t, bool >, int > = 0>
	scheduled_pool_backend_base (size_t worker_threads, bool register_workers)

	scheduled_pool_backend_base (scheduled_pool_backend_base const &)=delete

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

	~scheduled_pool_backend_base ()

auto	schedule_after (duration delay, task_type task) -> scheduled_task_backend
	Schedule a task to run after a delay.

template<typename F , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< F >, task_type >, int > = 0>
auto	schedule_after (duration delay, F &&task) -> scheduled_task_backend

auto	schedule_at (time_point time_point, task_type task) -> scheduled_task_backend
	Schedule a task to run at a specific time point.

template<typename F , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< F >, task_type >, int > = 0>
auto	schedule_at (time_point time_point, F &&task) -> scheduled_task_backend

auto	schedule_periodic (duration interval, task_type task) -> scheduled_task_backend
	Schedule a task to run periodically at fixed intervals.

template<typename F , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< F >, task_type >, int > = 0>
auto	schedule_periodic (duration interval, F &&task) -> scheduled_task_backend

auto	schedule_periodic_after (duration initial_delay, duration interval, task_type task) -> scheduled_task_backend
	Schedule a task to run periodically after an initial delay.

template<typename F , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< F >, task_type >, int > = 0>
auto	schedule_periodic_after (duration initial_delay, duration interval, F &&task) -> scheduled_task_backend

auto	scheduled_count () const -> size_t
	Get number of scheduled tasks (including periodic)

auto	is_current_context () const noexcept -> bool

auto	thread_pool () -> PoolType &
	Get the underlying thread pool for direct task submission.

void	shutdown (shutdown_policy_backend policy=shutdown_policy_backend::drain)
	Shutdown the scheduler and wait for completion.

auto	configure_threads (std::string const &name_prefix, native_scheduling_policy policy=native_scheduling_policy::other, native_thread_priority priority=native_thread_priority::normal())
	Configure worker threads.

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

auto	scheduler_thread_info () const -> std::optional< thread_info >

auto	configure_scheduler_thread (std::string const &name, native_scheduling_policy policy=native_scheduling_policy::other, native_thread_priority priority=native_thread_priority::normal()) -> expected< void, std::error_code >

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

Static Public Member Functions
static void	cancel (scheduled_task_backend &handle)
	Cancel a scheduled task by handle.

Detailed Description

template<typename PoolType = thread_pool_backend>
class threadschedule::detail::scheduled_pool_backend_base< PoolType >

Thread pool augmented with delayed and periodic task scheduling.

Non-copyable, non-movable. Combines a dedicated scheduler thread with an underlying PoolType (default: thread_pool_backend) that does the actual work.

How task execution works

The pool owns a single scheduler thread that runs an internal loop (scheduler_loop). Scheduled tasks are stored in a std::multimap sorted by their next_run time point. The scheduler thread sleeps (via condition_variable::wait / wait_until) until the earliest task is due. When a task becomes due, the scheduler thread:

Removes it from the multimap.
Checks if the task has been cancelled (via the atomic flag). If cancelled, the task is discarded.
Posts the task to the underlying PoolType via pool_.post(). From this point on, the task follows the execution rules of the underlying pool (see thread_pool_backend, polling_pool_backend, work_stealing_pool_backend, or lightweight_pool_backend documentation).
For periodic tasks, the scheduler re-inserts the next fixed-rate deadline. A task never overlaps with itself; deadlines missed while an occurrence is running are skipped rather than queued as backlog.

Execution guarantees

Every successfully scheduled task (schedule_after/schedule_at/ schedule_periodic returned a handle) is guaranteed to eventually execute, unless it is cancelled or shutdown() is called before it becomes due.
Tasks are stored in a std::multimap keyed by time point. When multiple tasks share the same due time, they are dispatched in insertion order (guaranteed by std::multimap since C++11).
Tasks that are already due and submitted to the underlying pool before shutdown() will still execute (the pool drains its queue).
Tasks that are not yet due at the time of shutdown() will NOT execute. The scheduler thread exits immediately on shutdown, so future-scheduled tasks are lost.
Cancellation is cooperative: calling handle.cancel() sets an atomic flag. The scheduler checks this flag before posting the task to the pool. Additionally, the pool-side wrapper checks the flag again right before calling the task. However, a task that is already running will NOT be interrupted by cancel().
Periodic tasks use fixed-rate deadlines. If an occurrence takes longer than its interval, missed occurrences are skipped. The same periodic callable is never invoked concurrently, and independent pool work does not wait behind a backlog of overdue occurrences.
There is no returned std::future for scheduled tasks. If you need to observe the result, use the underlying pool directly via thread_pool().post() or thread_pool().submit().

Thread safety: All schedule_* methods are thread-safe (protected by an internal mutex). cancel() on a scheduled_task_backend is also thread-safe (atomic). shutdown() is internally guarded and safe to call more than once.

Lifetime: The destructor calls shutdown(), which joins the scheduler thread and then shuts down the underlying pool. Can block if the pool still has running tasks.

Copyability / movability: Not copyable, not movable.

Template Parameters

PoolType Thread pool used for task execution (default: thread_pool_backend).

See also: scheduled_pool_backend, scheduled_work_stealing_pool_backend, scheduled_polling_pool_backend, scheduled_lightweight_pool_backend (convenience aliases)

Definition at line 104 of file scheduled_pool_backend_base.hpp.

Member Typedef Documentation

◆ duration

template<typename PoolType = thread_pool_backend>

using threadschedule::detail::scheduled_pool_backend_base< PoolType >::duration = std::chrono::steady_clock::duration

Definition at line 111 of file scheduled_pool_backend_base.hpp.

◆ one_shot_task_type

template<typename PoolType = thread_pool_backend>

using threadschedule::detail::scheduled_pool_backend_base< PoolType >::one_shot_task_type = detail::move_only_function<void()>

Definition at line 108 of file scheduled_pool_backend_base.hpp.

◆ periodic_task_type

template<typename PoolType = thread_pool_backend>

using threadschedule::detail::scheduled_pool_backend_base< PoolType >::periodic_task_type = detail::move_only_function<void()>

Definition at line 109 of file scheduled_pool_backend_base.hpp.

◆ task_type

template<typename PoolType = thread_pool_backend>

using threadschedule::detail::scheduled_pool_backend_base< PoolType >::task_type = std::function<void()>

Definition at line 107 of file scheduled_pool_backend_base.hpp.

◆ time_point

template<typename PoolType = thread_pool_backend>

using threadschedule::detail::scheduled_pool_backend_base< PoolType >::time_point = std::chrono::steady_clock::time_point

Definition at line 110 of file scheduled_pool_backend_base.hpp.

Constructor & Destructor Documentation

◆ scheduled_pool_backend_base() [1/3]

template<typename PoolType = thread_pool_backend>

threadschedule::detail::scheduled_pool_backend_base< PoolType >::scheduled_pool_backend_base ( size_t worker_threads = default_worker_count() )

inlineexplicit

Create a scheduled thread pool.

Parameters

worker_threads Number of worker threads for executing tasks (default: hardware concurrency)

Definition at line 250 of file scheduled_pool_backend_base.hpp.

◆ scheduled_pool_backend_base() [2/3]

template<typename PoolType = thread_pool_backend>

template<typename T = PoolType, std::enable_if_t< std::is_constructible_v< T, size_t, bool >, int > = 0>

threadschedule::detail::scheduled_pool_backend_base< PoolType >::scheduled_pool_backend_base	(	size_t	worker_threads,
		bool	register_workers
	)

inline

Definition at line 257 of file scheduled_pool_backend_base.hpp.

◆ scheduled_pool_backend_base() [3/3]

template<typename PoolType = thread_pool_backend>

threadschedule::detail::scheduled_pool_backend_base< PoolType >::scheduled_pool_backend_base ( scheduled_pool_backend_base< PoolType > const & )

delete

◆ ~scheduled_pool_backend_base()

template<typename PoolType = thread_pool_backend>

threadschedule::detail::scheduled_pool_backend_base< PoolType >::~scheduled_pool_backend_base ( )

inline

Definition at line 266 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::scheduled_pool_backend_base< PoolType >::shutdown().

Member Function Documentation

◆ cancel()

template<typename PoolType = thread_pool_backend>

static void threadschedule::detail::scheduled_pool_backend_base< PoolType >::cancel ( scheduled_task_backend & handle )

inlinestatic

Cancel a scheduled task by handle.

Parameters

handle Handle returned from schedule_* functions

Note: Can also call handle.cancel() directly

Definition at line 381 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::scheduled_task_backend::cancel().

◆ configure_scheduler_thread() [1/2]

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::configure_scheduler_thread ( native_thread_config const & config ) -> expected<void, std::error_code>

inline

Definition at line 488 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::scheduled_pool_backend_base< PoolType >::scheduler_thread_info().

◆ configure_scheduler_thread() [2/2]

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::configure_scheduler_thread	(	std::string const &	name,
		native_scheduling_policy	policy = `native_scheduling_policy::other`,
		native_thread_priority	priority = `native_thread_priority::normal()`
	)		-> expected<void, std::error_code>

inline

Definition at line 477 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::configure_thread(), and threadschedule::detail::scheduled_pool_backend_base< PoolType >::scheduler_thread_info().

◆ configure_threads() [1/2]

template<typename PoolType = thread_pool_backend>

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

inline

Definition at line 460 of file scheduled_pool_backend_base.hpp.

◆ configure_threads() [2/2]

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::configure_threads	(	std::string const &	name_prefix,
		native_scheduling_policy	policy = `native_scheduling_policy::other`,
		native_thread_priority	priority = `native_thread_priority::normal()`
	)

inline

Configure worker threads.

Returns expected<void, std::error_code> from the underlying pool.

Definition at line 453 of file scheduled_pool_backend_base.hpp.

◆ is_current_context()

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::is_current_context ( ) const -> bool

inlinenoexcept

Definition at line 397 of file scheduled_pool_backend_base.hpp.

Referenced by threadschedule::detail::scheduled_pool_backend_base< PoolType >::shutdown().

◆ operator=()

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::operator= ( scheduled_pool_backend_base< PoolType > const & ) -> scheduled_pool_backend_base &=delete

delete

◆ schedule_after() [1/2]

template<typename PoolType = thread_pool_backend>

template<typename F , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< F >, task_type >, int > = 0>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_after	(	duration	delay,
		F &&	task
	)		-> scheduled_task_backend

inline

Definition at line 288 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::checked_deadline_after(), and threadschedule::detail::make_move_only_function().

◆ schedule_after() [2/2]

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_after	(	duration	delay,
		task_type	task
	)		-> scheduled_task_backend

inline

Schedule a task to run after a delay.

Parameters

delay	duration to wait before executing the task
task	Function to execute

Returns: Handle to cancel the task

Definition at line 278 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::checked_deadline_after(), and threadschedule::detail::make_move_only_function().

◆ schedule_at() [1/2]

template<typename PoolType = thread_pool_backend>

template<typename F , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< F >, task_type >, int > = 0>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_at	(	time_point	time_point,
		F &&	task
	)		-> scheduled_task_backend

inline

Definition at line 310 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::make_move_only_function().

◆ schedule_at() [2/2]

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_at	(	time_point	time_point,
		task_type	task
	)		-> scheduled_task_backend

inline

Schedule a task to run at a specific time point.

Parameters

time_point	When to execute the task
task	Function to execute

Returns: Handle to cancel the task

Definition at line 303 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::make_move_only_function().

◆ schedule_periodic() [1/2]

template<typename PoolType = thread_pool_backend>

template<typename F , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< F >, task_type >, int > = 0>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_periodic	(	duration	interval,
		F &&	task
	)		-> scheduled_task_backend

inline

Definition at line 332 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_periodic_after().

◆ schedule_periodic() [2/2]

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_periodic	(	duration	interval,
		task_type	task
	)		-> scheduled_task_backend

inline

Schedule a task to run periodically at fixed intervals.

Parameters

interval	duration between executions
task	Function to execute repeatedly

Returns: Handle to cancel the periodic task

The task runs immediately and then repeats every interval. Use schedule_periodic_after() if you want to delay the first execution.

Definition at line 325 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_periodic_after().

◆ schedule_periodic_after() [1/2]

template<typename PoolType = thread_pool_backend>

template<typename F , std::enable_if_t<!std::is_same_v< detail::remove_cvref_t< F >, task_type >, int > = 0>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_periodic_after	(	duration	initial_delay,
		duration	interval,
		F &&	task
	)		-> scheduled_task_backend

inline

Definition at line 360 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::checked_deadline_after(), and threadschedule::detail::make_move_only_function().

◆ schedule_periodic_after() [2/2]

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_periodic_after	(	duration	initial_delay,
		duration	interval,
		task_type	task
	)		-> scheduled_task_backend

inline

Schedule a task to run periodically after an initial delay.

Parameters

initial_delay	duration to wait before first execution
interval	duration between subsequent executions
task	Function to execute repeatedly

Returns: Handle to cancel the periodic task

Definition at line 345 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::checked_deadline_after(), and threadschedule::detail::make_move_only_function().

Referenced by threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_periodic(), and threadschedule::detail::scheduled_pool_backend_base< PoolType >::schedule_periodic().

◆ scheduled_count()

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::scheduled_count ( ) const -> size_t

inline

Get number of scheduled tasks (including periodic)

Definition at line 390 of file scheduled_pool_backend_base.hpp.

◆ scheduler_thread_info()

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::scheduler_thread_info ( ) const -> std::optional<thread_info>

inline

Definition at line 466 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::thread_info::get_thread_id(), and threadschedule::detail::basic_thread_backend< ThreadType, OwnershipTag >::joinable().

Referenced by threadschedule::detail::scheduled_pool_backend_base< PoolType >::configure_scheduler_thread(), and threadschedule::detail::scheduled_pool_backend_base< PoolType >::configure_scheduler_thread().

◆ shutdown()

template<typename PoolType = thread_pool_backend>

void threadschedule::detail::scheduled_pool_backend_base< PoolType >::shutdown ( shutdown_policy_backend policy = shutdown_policy_backend::drain )

inline

Shutdown the scheduler and wait for completion.

Definition at line 415 of file scheduled_pool_backend_base.hpp.

References threadschedule::detail::scheduled_pool_backend_base< PoolType >::is_current_context(), threadschedule::detail::basic_thread_backend< ThreadType, OwnershipTag >::join(), threadschedule::detail::basic_thread_backend< ThreadType, OwnershipTag >::joinable(), and threadschedule::detail::throw_worker_deadlock().

Referenced by threadschedule::detail::scheduled_pool_backend_base< PoolType >::~scheduled_pool_backend_base().

◆ thread_pool()

template<typename PoolType = thread_pool_backend>

auto threadschedule::detail::scheduled_pool_backend_base< PoolType >::thread_pool ( ) -> PoolType&

inline

Get the underlying thread pool for direct task submission.

Definition at line 406 of file scheduled_pool_backend_base.hpp.

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

scheduled_pool_backend_base.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ duration

◆ one_shot_task_type

◆ periodic_task_type

◆ task_type

◆ time_point

Constructor & Destructor Documentation

◆ scheduled_pool_backend_base() [1/3]

◆ scheduled_pool_backend_base() [2/3]

◆ scheduled_pool_backend_base() [3/3]

◆ ~scheduled_pool_backend_base()

Member Function Documentation

◆ cancel()

◆ configure_scheduler_thread() [1/2]

◆ configure_scheduler_thread() [2/2]

◆ configure_threads() [1/2]

◆ configure_threads() [2/2]

◆ is_current_context()

◆ operator=()

◆ schedule_after() [1/2]

◆ schedule_after() [2/2]

◆ schedule_at() [1/2]

◆ schedule_at() [2/2]

◆ schedule_periodic() [1/2]

◆ schedule_periodic() [2/2]

◆ schedule_periodic_after() [1/2]

◆ schedule_periodic_after() [2/2]

◆ scheduled_count()

◆ scheduler_thread_info()

◆ shutdown()

◆ thread_pool()