vlink::WheelTimer类 参考

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

#include <wheel_timer.h>

vlink::WheelTimer 的协作图:

Public 类型
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 成员函数
	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.

详细描述

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.

成员类型定义说明

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.

构造及析构函数说明

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.

参数

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.

这是这个函数的调用关系图:

~WheelTimer()

vlink::WheelTimer::~WheelTimer

(

)

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

成员函数说明

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.

参数

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.

返回

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.

参数

key	Key returned by add().

返回

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).

返回

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.

参数

key	Key returned by add().

返回

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.

参数

max_slots_to_catch_up

Maximum slots to process per tick cycle.

函数调用图:

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.

---

该类的文档由以下文件生成:

• include/vlink/base/wheel_timer.h