timer.h File Reference

#include <keel/event_ctx.h>
#include <stdint.h>

Include dependency graph for timer.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	KlTimerEntry
	Timer heap entry (stored in KlEventCtx.timers array). More...

Typedefs
typedef void(*	KlTimerFn) (void *user_data)
	Timer callback function.

Functions
int64_t	kl_timer_add (KlEventCtx *ctx, uint64_t delay_ms, KlTimerFn cb, void *user_data)
	Schedule a one-shot timer.
int	kl_timer_cancel (KlEventCtx *ctx, int64_t timer_id)
	Cancel a pending timer.
int	kl_timer_next_timeout (KlEventCtx *ctx, int max_ms)
	Compute the timeout for the next kl_event_wait call.
int	kl_timer_fire (KlEventCtx *ctx)
	Fire all expired timers.

Typedef Documentation

KlTimerFn

typedef void(* KlTimerFn) (void *user_data)

Timer callback function.

Parameters

user_data

Opaque pointer passed to kl_timer_add.

Function Documentation

kl_timer_add()

int64_t kl_timer_add	(	KlEventCtx *	ctx,
		uint64_t	delay_ms,
		KlTimerFn	cb,
		void *	user_data
	)

Schedule a one-shot timer.

The callback fires after delay_ms milliseconds on the event loop thread. Timers are one-shot: the callback can re-add itself via kl_timer_add if repeating behavior is needed.

Safe to call from within a timer callback.

Parameters

ctx	Event context (owns the timer heap).
delay_ms	Delay in milliseconds (0 = fire on next kl_timer_fire).
cb	Callback invoked when the timer expires.
user_data	Opaque pointer passed to cb.

Returns

Timer ID >= 0 on success, -1 on error.

kl_timer_cancel()

int kl_timer_cancel	(	KlEventCtx *	ctx,
		int64_t	timer_id
	)

Cancel a pending timer.

Safe to call from within a timer callback. No-op if the timer has already fired (IDs are never reused).

Parameters

ctx	Event context.
timer_id	ID returned by kl_timer_add.

Returns

0 if cancelled, -1 if not found.

kl_timer_next_timeout()

int kl_timer_next_timeout	(	KlEventCtx *	ctx,
		int	max_ms
	)

Compute the timeout for the next kl_event_wait call.

Returns the smaller of max_ms and the time until the next timer fires. Returns 0 if a timer is already overdue. Returns max_ms if no timers are pending.

Parameters

ctx	Event context.
max_ms	Maximum timeout (e.g. KL_POLL_TIMEOUT_MS).

Returns

Clamped timeout in milliseconds.

kl_timer_fire()

int kl_timer_fire

(

KlEventCtx *

ctx

)

Fire all expired timers.

Pops and invokes all timers whose deadline <= kl_monotonic_ms(). Safe for callbacks to add or cancel timers.

Parameters

ctx	Event context.

Returns

Number of timers fired.