Clocks

Refcounted monotonic-clock object with one-shot timeout callbacks. More...

Macros
#define	r_clock_ref   r_ref_ref
	Take a reference (alias for r_ref_ref).
#define	r_clock_unref   r_ref_unref
	Drop a reference (alias for r_ref_unref).
#define	r_clock_entry_ref   r_ref_ref
	Take a reference on a clock entry (alias for r_ref_ref).
#define	r_clock_entry_unref   r_ref_unref
	Drop a reference on a clock entry (alias for r_ref_unref).
#define	r_clock_wait_relative(clock, delay)    r_clock_wait (clock, r_clock_get_time (clock) + (delay))
	Convenience: wait until "now + @p delay".

Typedefs
typedef struct RClock	RClock
	Opaque, refcounted clock handle.
typedef struct RClockEntry	RClockEntry
	Opaque, refcounted clock-timeout-entry handle.

Functions
RClock *	r_system_clock_get (void)
	Return the process-wide system monotonic clock.
RClock *	r_test_clock_new (rboolean update_on_wait)
	Create a synthetic clock for tests.
RClockTime	r_clock_get_time (const RClock *clock)
	Read the clock's current monotonic timestamp.
RClockTime	r_clock_wait (RClock *clock, RClockTime ts)
	Block until the clock reaches ts (or update synthetic clocks accordingly).
RClockEntry *	r_clock_add_timeout_callback (RClock *clock, RClockTime ts, RFunc cb, rpointer data, RDestroyNotify datanotify, rpointer user, RDestroyNotify usernotify)
	Register a one-shot callback to fire when the clock passes ts.
rboolean	r_clock_cancel_entry (RClock *clock, RClockEntry *entry)
	Remove a pending entry before it fires.
rsize	r_clock_timeout_count (const RClock *clock)
	Number of pending timeout entries on clock.
rboolean	r_clock_is_synthetic (const RClock *clock)
	TRUE if clock is a synthetic (test) clock.
RClockTime	r_clock_first_timeout (RClock *clock)
	Timestamp of the earliest pending timeout, or R_CLOCK_TIME_NONE if none.
ruint	r_clock_process_entries (RClock *clock, RClockTime *out)
	Run every entry whose timestamp has already passed.
rboolean	r_test_clock_update_time (RClock *clock, RClockTime ts)
	Advance a synthetic clock to ts (cannot move backwards).

Detailed Description

Refcounted monotonic-clock object with one-shot timeout callbacks.

Two implementations:

• System clock: singleton fetched via r_system_clock_get, backed by r_time_get_ts_monotonic.
• Test clock: created via r_test_clock_new for use in tests where time must be advanced manually with r_test_clock_update_time. Time cannot move backwards.

Timeout callbacks registered via r_clock_add_timeout_callback fire when r_clock_process_entries is called and the clock's current time has passed the entry's timestamp; this lets event loops integrate clock-driven work into their main poll.

Function Documentation

r_clock_add_timeout_callback()

RClockEntry * r_clock_add_timeout_callback	(	RClock *	clock,
		RClockTime	ts,
		RFunc	cb,
		rpointer	data,
		RDestroyNotify	datanotify,
		rpointer	user,
		RDestroyNotify	usernotify
	)

Register a one-shot callback to fire when the clock passes ts.

Parameters

clock	Clock to register against.
ts	Absolute timestamp when cb should fire.
cb	Callback function.
data	First argument passed to cb.
datanotify	Destructor for data; may be NULL.
user	Second argument passed to cb.
usernotify	Destructor for user; may be NULL.

Returns

Refcounted entry handle (also keeps a reference inside the clock until processed or cancelled).

r_clock_cancel_entry()

rboolean r_clock_cancel_entry	(	RClock *	clock,
		RClockEntry *	entry
	)

Remove a pending entry before it fires.

Returns

TRUE if it was still pending; FALSE if it had already fired or been cancelled.

r_clock_process_entries()

ruint r_clock_process_entries	(	RClock *	clock,
		RClockTime *	out
	)

Run every entry whose timestamp has already passed.

Parameters

clock	Clock to drain.
out	Optional out-pointer: receives the timestamp of the next still-pending entry, or R_CLOCK_TIME_NONE.

Returns

Number of entries that fired.

r_clock_wait()

RClockTime r_clock_wait	(	RClock *	clock,
		RClockTime	ts
	)

Block until the clock reaches ts (or update synthetic clocks accordingly).

Returns

The clock time at the end of the wait.

r_test_clock_new()

RClock * r_test_clock_new

(

rboolean

update_on_wait

)

Create a synthetic clock for tests.

Parameters

update_on_wait

If TRUE, r_clock_wait advances the clock to the requested timestamp instead of blocking on it.

r_test_clock_update_time()

rboolean r_test_clock_update_time	(	RClock *	clock,
		RClockTime	ts
	)

Advance a synthetic clock to ts (cannot move backwards).

Returns

TRUE on success, FALSE if clock is not a test clock or ts is in the past.