vlink::Timer Class Reference

Event-loop-driven repeating or one-shot timer. More...

#include <timer.h>

Collaboration diagram for vlink::Timer:

Public Types
using	Callback = std::function<void()>
	Callback type invoked on each timer tick.

Public Member Functions
	Timer ()
	Constructs a detached timer with no message loop, interval or callback.
	Timer (class MessageLoop *message_loop)
	Constructs a timer attached to message_loop with no interval or callback yet.
	Timer (class MessageLoop *message_loop, uint32_t interval_ms, int32_t loop_count=kInfinite, Callback &&callback=nullptr)
	Constructs and fully configures a timer attached to a loop.
	Timer (uint32_t interval_ms, int32_t loop_count=kInfinite, Callback &&callback=nullptr)
	Constructs a timer without attaching it to a loop.
	~Timer ()
	Destructor. Stops the timer and detaches it from the loop.
bool	is_active () const
	Returns true if the timer is currently running (armed and has remaining ticks).
bool	is_strict () const
	Returns true if strict mode is enabled.
uint32_t	get_interval () const
	Returns the current tick interval in milliseconds.
int32_t	get_loop_count () const
	Returns the configured total loop count.
int32_t	get_remain_loop_count () const
	Returns the number of remaining ticks before the timer stops automatically.
uint64_t	get_invoke_count () const
	Returns the total number of times the callback has been invoked since start().
uint16_t	get_priority () const
	Returns the task dispatch priority.
class MessageLoop *	get_message_loop () const
	Returns the MessageLoop this timer is attached to.
bool	attach (class MessageLoop *message_loop)
	Attaches the timer to a MessageLoop.
bool	detach ()
	Detaches the timer from its MessageLoop without stopping it.
void	start (Callback &&callback=nullptr)
	Arms and starts the timer.
void	restart ()
	Resets the countdown to zero and continues firing.
void	stop ()
	Disarms the timer without destroying it.
void	set_strict (bool strict)
	Enables or disables strict (catch-up) firing mode.
void	set_interval (uint32_t interval_ms)
	Changes the tick interval.
void	set_loop_count (int32_t loop_count)
	Changes the total number of ticks.
void	set_callback (Callback &&callback)
	Replaces the callback invoked on each tick.
void	set_priority (uint16_t priority)
	Sets the dispatch priority for the timer task.

Static Public Member Functions
static bool	call_once (class MessageLoop *message_loop, uint32_t interval_ms, Callback &&callback, uint16_t priority=0)
	Posts a one-shot timer to a MessageLoop without creating a Timer object.

Static Public Attributes
static constexpr int	kInfinite {-1}
	Sentinel loop count meaning repeat indefinitely.

Friends
class	MessageLoop

Detailed Description

Event-loop-driven repeating or one-shot timer.

Callbacks are dispatched on the thread of the associated MessageLoop.

Member Typedef Documentation

Callback

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

Callback type invoked on each timer tick.

Constructor & Destructor Documentation

Timer() [1/4]

vlink::Timer::Timer ( )

explicit

Constructs a detached timer with no message loop, interval or callback.

Must be configured with attach(), set_interval() and set_callback() before start() can be called.

Timer() [2/4]

vlink::Timer::Timer ( class MessageLoop * message_loop )

explicit

Constructs a timer attached to message_loop with no interval or callback yet.

Parameters

message_loop

The MessageLoop to deliver callbacks on.

Here is the call graph for this function:

Timer() [3/4]

vlink::Timer::Timer ( class MessageLoop * message_loop, uint32_t interval_ms, int32_t loop_count = kInfinite, Callback && callback = nullptr )

explicit

Constructs and fully configures a timer attached to a loop.

Parameters

message_loop	The MessageLoop to deliver callbacks on.
interval_ms	Tick interval in milliseconds. When zero, falls back to kMinInterval (10000).
loop_count	Number of times to fire (kInfinite for indefinite repeat). Default: kInfinite.
callback	Callback to invoke on each tick. Default: nullptr.

Here is the call graph for this function:

Timer() [4/4]

vlink::Timer::Timer ( uint32_t interval_ms, int32_t loop_count = kInfinite, Callback && callback = nullptr )

explicit

Constructs a timer without attaching it to a loop.

Call attach() before start().

Parameters

interval_ms	Tick interval in milliseconds.
loop_count	Number of times to fire. Default: kInfinite.
callback	Callback to invoke on each tick. Default: nullptr.

~Timer()

vlink::Timer::~Timer

(

)

Destructor. Stops the timer and detaches it from the loop.

Member Function Documentation

attach()

bool vlink::Timer::attach

(

class MessageLoop *

message_loop

)

Attaches the timer to a MessageLoop.

Must be called before start() if the timer was constructed without a loop. If the timer is already attached to a different loop it is detached first.

Parameters

message_loop

Loop to attach to.

Returns

true on success.

Here is the call graph for this function:

call_once()

bool vlink::Timer::call_once ( class MessageLoop * message_loop, uint32_t interval_ms, Callback && callback, uint16_t priority = 0 )

static

Posts a one-shot timer to a MessageLoop without creating a Timer object.

The timer fires exactly once after interval_ms milliseconds and is then destroyed. Useful for simple delayed tasks where lifetime management of a Timer object is inconvenient.

Parameters

message_loop	The MessageLoop to deliver the callback on.
interval_ms	Delay in milliseconds.
callback	Callback to invoke once.
priority	Priority of the timer task (default: 0).

Returns

true if the timer was successfully posted.

Here is the call graph for this function:

Here is the caller graph for this function:

detach()

bool vlink::Timer::detach

(

)

Detaches the timer from its MessageLoop without stopping it.

After detaching the timer stops firing. It can be re-attached to a different loop.

Returns

true on success.

get_interval()

uint32_t vlink::Timer::get_interval ( ) const

nodiscard

Returns the current tick interval in milliseconds.

Returns

Interval in milliseconds.

get_invoke_count()

uint64_t vlink::Timer::get_invoke_count ( ) const

nodiscard

Returns the total number of times the callback has been invoked since start().

Returns

Cumulative invocation count.

get_loop_count()

int32_t vlink::Timer::get_loop_count ( ) const

nodiscard

Returns the configured total loop count.

Returns

Loop count, or kInfinite (-1) for indefinite repeat.

get_message_loop()

class MessageLoop * vlink::Timer::get_message_loop ( ) const

nodiscard

Returns the MessageLoop this timer is attached to.

Returns

Pointer to the associated loop, or nullptr if detached.

Here is the call graph for this function:

get_priority()

uint16_t vlink::Timer::get_priority ( ) const

nodiscard

Returns the task dispatch priority.

Relevant only when the timer is attached to a kPriorityType MessageLoop.

Returns

Priority value (higher = dispatched sooner).

get_remain_loop_count()

int32_t vlink::Timer::get_remain_loop_count ( ) const

nodiscard

Returns the number of remaining ticks before the timer stops automatically.

Returns

Remaining tick count, or kInfinite if repeating indefinitely.

is_active()

bool vlink::Timer::is_active ( ) const

nodiscard

Returns true if the timer is currently running (armed and has remaining ticks).

Returns

true if the timer is active.

is_strict()

bool vlink::Timer::is_strict ( ) const

nodiscard

Returns true if strict mode is enabled.

In strict mode, missed ticks (due to a busy loop) are fired immediately on the next loop iteration to compensate for schedule drift.

Returns

true if strict mode is on.

restart()

void vlink::Timer::restart

(

)

Resets the countdown to zero and continues firing.

Equivalent to stop() followed by start() but also resets get_invoke_count().

set_callback()

void vlink::Timer::set_callback

(

Callback &&

callback

)

Replaces the callback invoked on each tick.

Parameters

callback

New callback.

set_interval()

void vlink::Timer::set_interval

(

uint32_t

interval_ms

)

Changes the tick interval.

Takes effect on the next start() or restart() call. When set to zero, the interval falls back to kMinInterval (10000).

Parameters

interval_ms

New interval in milliseconds.

set_loop_count()

void vlink::Timer::set_loop_count

(

int32_t

loop_count

)

Changes the total number of ticks.

Parameters

loop_count

New loop count. Use kInfinite for indefinite repeat.

set_priority()

void vlink::Timer::set_priority

(

uint16_t

priority

)

Sets the dispatch priority for the timer task.

Only effective when the associated loop is of type kPriorityType.

Parameters

priority

Priority value (higher = earlier dispatch).

set_strict()

void vlink::Timer::set_strict

(

bool

strict

)

Enables or disables strict (catch-up) firing mode.

When true, if the loop was busy and one or more ticks were missed, they are fired immediately on the next loop iteration. Default is false.

Parameters

strict

true to enable catch-up firing.

start()

void vlink::Timer::start

(

Callback &&

callback = nullptr

)

Arms and starts the timer.

If callback is provided it replaces the previously set callback. The first tick fires after one full interval.

Parameters

callback

Optional replacement callback. Default: nullptr (keep existing).

stop()

void vlink::Timer::stop

(

)

Disarms the timer without destroying it.

After stop(), is_active() returns false. Call start() to re-arm.

Friends And Related Symbol Documentation

MessageLoop

friend class MessageLoop

friend

Member Data Documentation

kInfinite

int vlink::Timer::kInfinite {-1}

staticconstexpr

Sentinel loop count meaning repeat indefinitely.

---

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

• include/vlink/base/timer.h