Thread-safe priority queue for scheduling timed events. More...

#include <timeoutQueue.H>

Collaboration diagram for TimeoutQueue:

Classes
class	Event
	Base class for scheduled events. More...

Public Member Functions
	TimeoutQueue ()
	Default constructor - starts the background thread.

	~TimeoutQueue ()
	Destructor - shuts down the queue and joins the thread.

void	schedule_event (const Time &trigger_time, Event *)
	Schedule an event at a specific time.

void	schedule_event (Event *event)
	Schedule an event using its internal trigger time.

bool	cancel_event (Event *event)
	Cancel a scheduled event.

void	reschedule_event (const Time &trigger_time, Event *event)
	Reschedule an event to a new time.

void	cancel_delete_event (Event *&event)
	Cancel and delete an event.

void	shutdown ()
	Shut down the queue and stop the background thread.

std::thread::id	getThreadId () const
	Get the background thread ID.

size_t	size () const
	Get the number of pending events in the queue.

bool	is_empty () const
	Check if the queue has no pending events.

bool	is_running () const
	Check if the queue is running (not shut down)

void	schedule_after_ms (int ms_from_now, Event *event)
	Schedule an event relative to the current time.

Time	next_event_time () const
	Get the trigger time of the next (soonest) event.

size_t	clear_all ()
	Cancel all pending events in the queue.

size_t	executed_count () const
	Get count of events that have been executed.

size_t	canceled_count () const
	Get count of events that have been canceled.

void	reset_stats ()
	Reset statistics counters to zero.

void	pause ()
	Pause event execution (events remain scheduled but won't execute)

void	resume ()
	Resume event execution after pause.

bool	is_paused () const
	Check if the queue is paused.

bool	wait_until_empty (int timeout_ms=0)
	Block until all pending events have been executed or canceled.

Event *	find_by_id (const Event::EventId id) const
	Find a scheduled event by its ID.

bool	cancel_by_id (Event::EventId id)
	Cancel a scheduled event by its ID.

Private Member Functions
void	triggerEvent ()

void	shutdown_locked ()

Private Attributes
BinHeapVtl< Time >	prio_queue

DynMapTree< Event::EventId, Event * >	event_map

DynSetTree< Event * >	event_registry

std::mutex	mtx

std::condition_variable	cond

std::thread	workerThread

bool	isShutdown

bool	isPaused = false

size_t	executedCount = 0

size_t	canceledCount = 0

std::condition_variable	emptyCondition

Detailed Description

Thread-safe priority queue for scheduling timed events.

Manages a collection of events that should be triggered at specific absolute times. A background thread monitors the queue and executes events when their scheduled time arrives.

Thread Safety

All public methods are thread-safe and can be called from any thread. The background thread handles event execution. *

Definition at line 140 of file timeoutQueue.H.

Constructor & Destructor Documentation

◆ TimeoutQueue()

TimeoutQueue::TimeoutQueue ( )

Default constructor - starts the background thread.

Definition at line 48 of file timeoutQueue.C.

References triggerEvent(), and workerThread.

◆ ~TimeoutQueue()

TimeoutQueue::~TimeoutQueue ( )

Destructor - shuts down the queue and joins the thread.

Definition at line 53 of file timeoutQueue.C.

References ah_warning, isShutdown, Aleph::maps(), mtx, shutdown_locked(), and workerThread.

Member Function Documentation

◆ cancel_by_id()

bool TimeoutQueue::cancel_by_id ( Event::EventId id )

Cancel a scheduled event by its ID.

Parameters

id	The event ID to cancel

Returns: true if the event was found and canceled, false if not found or not in queue

Definition at line 501 of file timeoutQueue.C.

References TimeoutQueue::Event::Canceled, canceledCount, cond, emptyCondition, event_map, event_registry, TimeoutQueue::Event::In_Queue, TimeoutQueue::Event::InvalidId, Aleph::maps(), mtx, prio_queue, Aleph::GenBinHeap< NodeType, Key, Compare >::remove(), and Aleph::GenBinHeap< NodeType, Key, Compare >::size().

Referenced by TEST(), and TEST().

◆ cancel_delete_event()

void TimeoutQueue::cancel_delete_event ( Event *& event )

Cancel and delete an event.

If the event is currently executing, its status is set to To_Delete and the worker thread will delete it after EventFct() returns. Otherwise, the event is deleted immediately before invoking the completion callback.

The completion callback receives nullptr as the event pointer and Deleted as the status, since the event has already been destroyed.

Parameters

event Pointer to event (set to nullptr after deletion). No exception is thrown for the nullptr argument (early return).

Complexity: Average: O(1) when the event is executing or not in queue. Worst: O(log n) when the event is in the priority queue (heap removal). Space: O(1) additional.

Exception safety: Strong guarantee: if an exception is thrown, the event reference is unchanged.

Definition at line 145 of file timeoutQueue.C.

References ah_invalid_argument_unless, canceledCount, cond, TimeoutQueue::Event::Deleted, emptyCondition, event_map, event_registry, TimeoutQueue::Event::Executing, TimeoutQueue::Event::In_Queue, Aleph::maps(), mtx, prio_queue, Aleph::DynList< T >::remove(), Aleph::GenBinHeap< NodeType, Key, Compare >::remove(), Aleph::GenBinHeap< NodeType, Key, Compare >::size(), and TimeoutQueue::Event::To_Delete.

Referenced by demo_cancel_delete(), TEST(), TEST(), TEST(), TEST(), TEST(), and TEST().

◆ cancel_event()

bool TimeoutQueue::cancel_event ( TimeoutQueue::Event * event )

Cancel a scheduled event.

Parameters

event Event to cancel

Returns: true if the event was in queue and canceled. Returns false if the event is currently executing or not in the queue.

Definition at line 106 of file timeoutQueue.C.

References ah_invalid_argument_if, ah_invalid_argument_unless, TimeoutQueue::Event::Canceled, canceledCount, cond, emptyCondition, event_map, event_registry, TimeoutQueue::Event::In_Queue, Aleph::maps(), mtx, prio_queue, Aleph::GenBinHeap< NodeType, Key, Compare >::remove(), and Aleph::GenBinHeap< NodeType, Key, Compare >::size().

Referenced by demo_cancellation(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), and TEST().

◆ canceled_count()

size_t TimeoutQueue::canceled_count ( ) const

Get count of events that have been canceled.

Definition at line 438 of file timeoutQueue.C.

References canceledCount, and mtx.

Referenced by TEST(), TEST(), and TEST().

◆ clear_all()

size_t TimeoutQueue::clear_all ( )

Cancel all pending events in the queue.

Returns: Number of events that were canceled

Definition at line 406 of file timeoutQueue.C.

References TimeoutQueue::Event::Canceled, canceledCount, cond, Aleph::count(), emptyCondition, event_map, event_registry, Aleph::GenBinHeap< NodeType, Key, Compare >::getMin(), Aleph::maps(), mtx, TimeoutQueue::Event::on_completed, prio_queue, and Aleph::GenBinHeap< NodeType, Key, Compare >::size().

Referenced by TEST(), TEST(), and TEST().

◆ executed_count()

size_t TimeoutQueue::executed_count ( ) const

Get count of events that have been executed.

Definition at line 432 of file timeoutQueue.C.

References executedCount, and mtx.

Referenced by TEST(), TEST(), and TEST().

◆ find_by_id()

TimeoutQueue::Event * TimeoutQueue::find_by_id ( const Event::EventId id ) const

Find a scheduled event by its ID.

Parameters

id	The event ID to search for

Returns: Pointer to the event if found and still in the queue, nullptr otherwise

Definition at line 487 of file timeoutQueue.C.

References event_map, TimeoutQueue::Event::In_Queue, TimeoutQueue::Event::InvalidId, Aleph::maps(), and mtx.

Referenced by TEST().

◆ getThreadId()

std::thread::id TimeoutQueue::getThreadId ( ) const

inline

Get the background thread ID.

Definition at line 371 of file timeoutQueue.H.

References workerThread.

◆ is_empty()

bool TimeoutQueue::is_empty ( ) const

Check if the queue has no pending events.

Definition at line 380 of file timeoutQueue.C.

References mtx, prio_queue, and Aleph::GenBinHeap< NodeType, Key, Compare >::size().

Referenced by TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), and TEST().

◆ is_paused()

bool TimeoutQueue::is_paused ( ) const

Check if the queue is paused.

Definition at line 464 of file timeoutQueue.C.

References isPaused, and mtx.

Referenced by TEST().

◆ is_running()

bool TimeoutQueue::is_running ( ) const

Check if the queue is running (not shut down)

Definition at line 386 of file timeoutQueue.C.

References isShutdown, Aleph::maps(), and mtx.

Referenced by TEST(), and TEST().

◆ next_event_time()

Time TimeoutQueue::next_event_time ( ) const

Get the trigger time of the next (soonest) event.

Returns: Time of the next event, or {0,0} if the queue is empty

Definition at line 398 of file timeoutQueue.C.

References mtx, prio_queue, Aleph::GenBinHeap< NodeType, Key, Compare >::size(), and Aleph::GenBinHeap< NodeType, Key, Compare >::top().

Referenced by TEST().

◆ pause()

void TimeoutQueue::pause ( )

Pause event execution (events remain scheduled but won't execute)

Definition at line 451 of file timeoutQueue.C.

References isPaused, and mtx.

Referenced by TEST().

◆ reschedule_event()

void TimeoutQueue::reschedule_event	(	const Time &	trigger_time,
		TimeoutQueue::Event *	event
	)

Reschedule an event to a new time.

Parameters

trigger_time	New absolute trigger time
event	Event to reschedule *

Definition at line 207 of file timeoutQueue.C.

References ah_invalid_argument_if, ah_invalid_argument_unless, cond, event_map, event_registry, TimeoutQueue::Event::In_Queue, Aleph::GenBinHeap< NodeType, Key, Compare >::insert(), isShutdown, Aleph::maps(), mtx, prio_queue, and Aleph::GenBinHeap< NodeType, Key, Compare >::remove().

Referenced by demo_rescheduling(), PeriodicEvent::EventFct(), ReschedulingEvent::EventFct(), TEST(), TEST(), TEST(), and TEST().

◆ reset_stats()

void TimeoutQueue::reset_stats ( )

Reset statistics counters to zero.

Definition at line 444 of file timeoutQueue.C.

References canceledCount, executedCount, and mtx.

Referenced by TEST(), TEST(), TEST(), and TEST().

◆ resume()

void TimeoutQueue::resume ( )

Resume event execution after pause.

Definition at line 457 of file timeoutQueue.C.

References cond, isPaused, and mtx.

Referenced by TEST().

◆ schedule_after_ms()

void TimeoutQueue::schedule_after_ms	(	int	ms_from_now,
		Event *	event
	)

Schedule an event relative to the current time.

Parameters

ms_from_now	Milliseconds from now to trigger
event	Event to schedule

Definition at line 392 of file timeoutQueue.C.

References Aleph::maps(), read_current_time(), schedule_event(), and time_plus_msec().

Referenced by TEST().

◆ schedule_event() [1/2]

void TimeoutQueue::schedule_event	(	const Time &	trigger_time,
		TimeoutQueue::Event *	event
	)

Schedule an event at a specific time.

Parameters

trigger_time	Absolute trigger time
event	Event to schedule *

Definition at line 71 of file timeoutQueue.C.

References ah_invalid_argument_if, Aleph::maps(), and schedule_event().

◆ schedule_event() [2/2]

void TimeoutQueue::schedule_event ( TimeoutQueue::Event * event )

Schedule an event using its internal trigger time.

Parameters

event Event to schedule (uses event's getAbsoluteTime()) *

Definition at line 81 of file timeoutQueue.C.

References ah_domain_error_if, ah_invalid_argument_if, cond, event_map, event_registry, TimeoutQueue::Event::In_Queue, Aleph::GenBinHeap< NodeType, Key, Compare >::insert(), isShutdown, Aleph::maps(), mtx, NSEC, and prio_queue.

◆ shutdown()

void TimeoutQueue::shutdown ( )

Shut down the queue and stop the background thread.

Definition at line 368 of file timeoutQueue.C.

References mtx, and shutdown_locked().

Referenced by main(), TimeoutQueueEnvironment::TearDown(), and TEST().

◆ shutdown_locked()

void TimeoutQueue::shutdown_locked ( )

inlineprivate

Definition at line 296 of file timeoutQueue.H.

References cond, and isShutdown.

Referenced by ~TimeoutQueue(), and shutdown().

◆ size()

size_t TimeoutQueue::size ( ) const

Get the number of pending events in the queue.

Definition at line 374 of file timeoutQueue.C.

References mtx, prio_queue, and Aleph::GenBinHeap< NodeType, Key, Compare >::size().

Referenced by TEST(), TEST(), and TEST().

◆ triggerEvent()

void TimeoutQueue::triggerEvent ( )

private

◆ wait_until_empty()

bool TimeoutQueue::wait_until_empty ( int timeout_ms = 0 )

Block until all pending events have been executed or canceled.

Parameters

timeout_ms Maximum time to wait in milliseconds (0 = wait forever)

Returns: true if queue became empty, false if timeout

Definition at line 470 of file timeoutQueue.C.

References emptyCondition, isShutdown, Aleph::maps(), mtx, prio_queue, and Aleph::GenBinHeap< NodeType, Key, Compare >::size().

Referenced by TEST(), TEST(), TEST(), and TEST().

Member Data Documentation

◆ canceledCount

size_t TimeoutQueue::canceledCount = 0

private

Definition at line 289 of file timeoutQueue.H.

Referenced by cancel_by_id(), cancel_delete_event(), cancel_event(), canceled_count(), clear_all(), reset_stats(), and triggerEvent().

◆ cond

std::condition_variable TimeoutQueue::cond

private

Definition at line 282 of file timeoutQueue.H.

Referenced by cancel_by_id(), cancel_delete_event(), cancel_event(), clear_all(), reschedule_event(), resume(), schedule_event(), shutdown_locked(), and triggerEvent().

◆ emptyCondition

std::condition_variable TimeoutQueue::emptyCondition

private

Definition at line 291 of file timeoutQueue.H.

Referenced by cancel_by_id(), cancel_delete_event(), cancel_event(), clear_all(), triggerEvent(), and wait_until_empty().

◆ event_map

DynMapTree<Event::EventId, Event *> TimeoutQueue::event_map

private

Definition at line 278 of file timeoutQueue.H.

Referenced by cancel_by_id(), cancel_delete_event(), cancel_event(), clear_all(), find_by_id(), reschedule_event(), schedule_event(), and triggerEvent().

◆ event_registry

DynSetTree<Event *> TimeoutQueue::event_registry

private

Definition at line 279 of file timeoutQueue.H.

Referenced by cancel_by_id(), cancel_delete_event(), cancel_event(), clear_all(), reschedule_event(), schedule_event(), and triggerEvent().

◆ executedCount

size_t TimeoutQueue::executedCount = 0

private

Definition at line 288 of file timeoutQueue.H.

Referenced by executed_count(), reset_stats(), and triggerEvent().

◆ isPaused

bool TimeoutQueue::isPaused = false

private

Definition at line 286 of file timeoutQueue.H.

Referenced by is_paused(), pause(), resume(), and triggerEvent().

◆ isShutdown

bool TimeoutQueue::isShutdown

private

Definition at line 285 of file timeoutQueue.H.

Referenced by ~TimeoutQueue(), is_running(), reschedule_event(), schedule_event(), shutdown_locked(), triggerEvent(), and wait_until_empty().

◆ mtx

std::mutex TimeoutQueue::mtx

mutableprivate

Definition at line 281 of file timeoutQueue.H.

Referenced by ~TimeoutQueue(), cancel_by_id(), cancel_delete_event(), cancel_event(), canceled_count(), clear_all(), executed_count(), find_by_id(), is_empty(), is_paused(), is_running(), next_event_time(), pause(), reschedule_event(), reset_stats(), resume(), schedule_event(), shutdown(), size(), triggerEvent(), and wait_until_empty().

◆ prio_queue

BinHeapVtl<Time> TimeoutQueue::prio_queue

private

Definition at line 277 of file timeoutQueue.H.

Referenced by cancel_by_id(), cancel_delete_event(), cancel_event(), clear_all(), is_empty(), next_event_time(), reschedule_event(), schedule_event(), size(), triggerEvent(), and wait_until_empty().

◆ workerThread

std::thread TimeoutQueue::workerThread

private

Definition at line 283 of file timeoutQueue.H.

Referenced by TimeoutQueue(), ~TimeoutQueue(), and getThreadId().

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

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Thread Safety

Constructor & Destructor Documentation

◆ TimeoutQueue()

◆ ~TimeoutQueue()

Member Function Documentation

◆ cancel_by_id()

◆ cancel_delete_event()

◆ cancel_event()

◆ canceled_count()

◆ clear_all()

◆ executed_count()

◆ find_by_id()

◆ getThreadId()

◆ is_empty()

◆ is_paused()

◆ is_running()

◆ next_event_time()

◆ pause()

◆ reschedule_event()

◆ reset_stats()

◆ resume()

◆ schedule_after_ms()

◆ schedule_event() [1/2]

◆ schedule_event() [2/2]

◆ shutdown()

◆ shutdown_locked()

◆ size()

◆ triggerEvent()

◆ wait_until_empty()

Member Data Documentation

◆ canceledCount

◆ cond

◆ emptyCondition

◆ event_map

◆ event_registry

◆ executedCount

◆ isPaused

◆ isShutdown

◆ mtx

◆ prio_queue

◆ workerThread