vlink::WheelTimer Class Reference

O(1) hashed-timing-wheel scheduler backed by an internal worker thread. More...

#include <wheel_timer.h>

Collaboration diagram for vlink::WheelTimer:

Public Types
using	Key = int64_t
	Opaque handle returned by add() and accepted by remove(). More...
using	Callback = Function< void(Key)>
	Callback signature invoked when a timer expires. More...

Public Member Functions
	WheelTimer (uint32_t slots, uint32_t interval_ms)
	Constructs the wheel with the given resolution and capacity. More...
	~WheelTimer ()
	Destructor. Calls stop() when the wheel is still running. More...
void	start ()
	Starts the worker thread and begins advancing the wheel cursor. More...
void	stop ()
	Stops the wheel and joins the worker thread. More...
void	pause ()
	Temporarily suspends timer dispatch without joining the worker thread. More...
void	resume ()
	Resumes a paused wheel; a no-op when not paused. More...
void	wakeup ()
	Wakes the worker thread early when it is sleeping between ticks. More...
bool	is_running () const
	Reports whether the wheel is currently running. More...
Key	add (uint32_t timeout_ms, Callback &&callback, uint32_t repeat_ms=0)
	Inserts a new timer into the wheel. More...
bool	remove (Key key)
	Removes a timer before its callback runs. More...
uint32_t	get_remaining_time (Key key) const
	Returns the approximate remaining time before a timer fires. More...
void	set_catchup_limit (uint32_t max_slots_to_catch_up)
	Caps the number of catch-up slots processed in a single tick iteration. More...

Detailed Description

O(1) hashed-timing-wheel scheduler backed by an internal worker thread.

Owns a fixed-size slot array and advances a cursor every interval_ms milliseconds.

Member Typedef Documentation

Callback

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

Callback signature invoked when a timer expires.

The Key argument lets a single lambda manage multiple timers.

Key

using vlink::WheelTimer::Key = int64_t

Opaque handle returned by add() and accepted by remove().

Constructor & Destructor Documentation

WheelTimer()

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

explicit

Constructs the wheel with the given resolution and capacity.

Both slots and interval_ms must be greater than zero; invalid values log a fatal error and throw. Call start() to begin advancing the wheel.

Parameters

slots	Number of buckets in the wheel. Larger values shorten the round counter for long timeouts.
interval_ms	Tick duration in milliseconds; sets the resolution of every timer.

~WheelTimer()

vlink::WheelTimer::~WheelTimer

(

)

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

Member Function Documentation

add()

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

Inserts a new timer into the wheel.

The callback runs on the worker thread after timeout_ms milliseconds. When repeat_ms is non-zero the timer is re-armed at every expiry with repeat_ms as the next timeout.

Parameters

timeout_ms	Initial delay in milliseconds (rounded up to a slot boundary).
callback	Function invoked on expiry.
repeat_ms	Re-arm interval in milliseconds; 0 selects one-shot. Default: 0.

Returns

Unique key identifying this timer entry, or -1 on invalid input or key allocation failure.

get_remaining_time()

uint32_t vlink::WheelTimer::get_remaining_time

(

Key

key

)

const

Returns the approximate remaining time before a timer fires.

The value is rounded to the wheel's tick resolution.

Parameters

key	Key returned by add().

Returns

Estimated remaining time in milliseconds, or 0 when key is unknown.

is_running()

bool vlink::WheelTimer::is_running

(

)

const

Reports whether the wheel is currently running.

Returns

true between start() and stop().

pause()

void vlink::WheelTimer::pause

(

)

Temporarily suspends timer dispatch without joining the worker thread.

The worker remains alive but the cursor stops advancing. Use resume() to continue.

remove()

bool vlink::WheelTimer::remove

(

Key

key

)

Removes a timer before its callback runs.

Parameters

key	Key returned by add().

Returns

true when the timer existed and was removed.

resume()

void vlink::WheelTimer::resume

(

)

Resumes a paused wheel; a no-op when not paused.

set_catchup_limit()

void vlink::WheelTimer::set_catchup_limit

(

uint32_t

max_slots_to_catch_up

)

Caps the number of catch-up slots processed in a single tick iteration.

Prevents a single tick from blocking the worker for an unbounded duration when the wheel falls behind (for example, after the system wakes from sleep).

Parameters

max_slots_to_catch_up

Maximum slots processed per tick cycle.

start()

void vlink::WheelTimer::start

(

)

Starts the worker thread and begins advancing the wheel cursor.

stop()

void vlink::WheelTimer::stop

(

)

Stops the wheel and joins the worker thread.

Pending timers do not fire after stop() returns.

wakeup()

void vlink::WheelTimer::wakeup

(

)

Wakes the worker thread early when it is sleeping between ticks.

Useful after inserting a very short timeout that should fire immediately.

---

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

• include/vlink/base/wheel_timer.h