vlink::WheelTimer Class Reference

O(1) hash-wheel timer backed by a fixed-size circular slot array. More...

#include <wheel_timer.h>

Collaboration diagram for vlink::WheelTimer:

Public Types
using	Key = int64_t
	Opaque handle returned by add() and used to remove() a timer.
using	Callback = std::function<void(Key)>
	Callback invoked when a timer expires.

Public Member Functions
	WheelTimer (uint32_t slots, uint32_t interval_ms)
	Constructs the wheel timer.
	~WheelTimer ()
	Destructor. Calls stop() if the wheel is still running.
void	start ()
	Starts the internal background thread and begins advancing the wheel.
void	stop ()
	Stops the wheel and joins the background thread.
void	pause ()
	Temporarily suspends the wheel without terminating the background thread.
void	resume ()
	Resumes a paused wheel.
void	wakeup ()
	Wakes the internal worker thread if it is sleeping between ticks.
bool	is_running () const
	Returns true if the wheel is currently running (started and not stopped).
Key	add (uint32_t timeout_ms, Callback &&callback, uint32_t repeat_ms=0)
	Adds a new timer to the wheel.
bool	remove (Key key)
	Removes a timer before it fires.
uint32_t	get_remaining_time (Key key) const
	Returns the estimated remaining time for a timer.
void	set_catchup_limit (uint32_t max_slots_to_catch_up)
	Sets the maximum number of missed slots processed in a single tick.

Detailed Description

O(1) hash-wheel timer backed by a fixed-size circular slot array.

Runs its own internal background thread to advance the wheel on each interval_ms tick.

Member Typedef Documentation

Callback

using vlink::WheelTimer::Callback = std::function<void(Key)>

Callback invoked when a timer expires.

The Key parameter allows a single lambda to manage multiple timers.

Key

using vlink::WheelTimer::Key = int64_t

Opaque handle returned by add() and used to remove() a timer.

Constructor & Destructor Documentation

WheelTimer()

vlink::WheelTimer::WheelTimer ( uint32_t slots, uint32_t interval_ms )

explicit

Constructs the wheel timer.

Creates the internal slot array. Call start() to begin advancing the wheel.

Parameters

slots	Number of time buckets in the wheel. Higher values reduce the number of round counters needed for long timeouts.
interval_ms	Duration of one slot in milliseconds. Resolution of all timers.

Here is the caller graph for this function:

~WheelTimer()

vlink::WheelTimer::~WheelTimer

(

)

Destructor. Calls stop() if the wheel is still running.

Member Function Documentation

add()

Key vlink::WheelTimer::add	(	uint32_t	timeout_ms,
		Callback &&	callback,
		uint32_t	repeat_ms = 0 )

Adds a new timer to the wheel.

The callback will be invoked from the wheel's internal thread after timeout_ms milliseconds. If repeat_ms > 0, the timer is automatically re-added with the repeat_ms interval each time it fires.

Parameters

timeout_ms	Initial delay in milliseconds (rounded up to the nearest slot).
callback	Function to call on expiry. Receives the timer's Key as argument.
repeat_ms	Re-fire interval in milliseconds. 0 = one-shot. Default: 0.

Returns

A unique Key identifying this timer entry.

get_remaining_time()

uint32_t vlink::WheelTimer::get_remaining_time ( Key key ) const

nodiscard

Returns the estimated remaining time for a timer.

The returned value is approximate due to discretisation to slot boundaries.

Parameters

key	Key returned by add().

Returns

Estimated remaining time in milliseconds, or 0 if the key is not found.

is_running()

bool vlink::WheelTimer::is_running ( ) const

nodiscard

Returns true if the wheel is currently running (started and not stopped).

Returns

true if running.

pause()

void vlink::WheelTimer::pause

(

)

Temporarily suspends the wheel without terminating the background thread.

Timers will not fire while paused. The background thread remains alive. Call resume() to continue normal operation.

remove()

bool vlink::WheelTimer::remove

(

Key

key

)

Removes a timer before it fires.

Parameters

key	Key returned by add().

Returns

true if the timer was found and removed; false if already expired or invalid.

resume()

void vlink::WheelTimer::resume

(

)

Resumes a paused wheel.

If the wheel is not paused, this is a no-op.

set_catchup_limit()

void vlink::WheelTimer::set_catchup_limit

(

uint32_t

max_slots_to_catch_up

)

Sets the maximum number of missed slots processed in a single tick.

If the wheel falls behind (e.g., due to system sleep), it may have many slots to catch up. This limit prevents a single tick from blocking for too long by capping the number of catch-up slots processed per iteration. Default is unlimited.

Parameters

max_slots_to_catch_up

Maximum slots to process per tick cycle.

Here is the call graph for this function:

start()

void vlink::WheelTimer::start

(

)

Starts the internal background thread and begins advancing the wheel.

stop()

void vlink::WheelTimer::stop

(

)

Stops the wheel and joins the background thread.

Pending timers are not fired after stop() returns.

wakeup()

void vlink::WheelTimer::wakeup

(

)

Wakes the internal worker thread if it is sleeping between ticks.

Useful for triggering an immediate tick after adding a very short timeout.

---

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

• include/vlink/base/wheel_timer.h