Timeout callback list

Ordered list of callbacks keyed on absolute deadlines; the building block under rlib's event-loop timers. More...

Files
file	rtimeoutcblist.h
	Ordered list of callbacks indexed by absolute deadline.

Data Structures
struct	RTimeoutCBList
	Ordered list of RToCB entries keyed by deadline. More...

Macros
#define	r_to_cb_ref   r_ref_ref
	Increment the entry's refcount.
#define	r_to_cb_unref   r_ref_unref
	Decrement the entry's refcount; frees when it reaches zero.
#define	R_TIMEOUT_CBLIST_INIT   { NULL, NULL, 0 }
	Static initialiser for an empty RTimeoutCBList.
#define	r_timeout_cblist_init(lst)   r_memset (lst, 0, sizeof (RTimeoutCBList))
	Initialise a stack-allocated RTimeoutCBList to empty.
#define	r_timeout_cblist_len(lst)   (lst)->size
	Number of pending callbacks.

Typedefs
typedef struct RToCB	RToCB
	Opaque, refcounted timeout-callback entry.

Functions
void	r_timeout_cblist_clear (RTimeoutCBList *lst)
	Cancel every pending entry and drop the list to empty.
rboolean	r_timeout_cblist_insert (RTimeoutCBList *lst, RToCB **tocb, RClockTime ts, RFunc cb, rpointer data, RDestroyNotify datanotify, rpointer user, RDestroyNotify usernotify)
	Schedule cb to fire at ts.
rboolean	r_timeout_cblist_cancel (RTimeoutCBList *lst, RToCB *cb)
	Cancel the entry identified by cb.
RClockTime	r_timeout_cblist_first_timeout (RTimeoutCBList *lst)
	Return the deadline of the head entry, or R_CLOCK_TIME_NONE if the list is empty.
rsize	r_timeout_cblist_update (RTimeoutCBList *lst, RClockTime ts)
	Fire and remove every entry whose deadline is at or before ts; returns the number called.

Detailed Description

Ordered list of callbacks keyed on absolute deadlines; the building block under rlib's event-loop timers.

Callers insert (deadline, callback) entries via r_timeout_cblist_insert and call r_timeout_cblist_update on each loop tick. The list is kept sorted by deadline so r_timeout_cblist_first_timeout is O(1) and the update walk only inspects entries whose deadline has actually passed.

Function Documentation

r_timeout_cblist_cancel()

rboolean r_timeout_cblist_cancel	(	RTimeoutCBList *	lst,
		RToCB *	cb
	)

Cancel the entry identified by cb.

The entry's destroy notifiers run before it's removed.

Returns

FALSE if cb is no longer in the list (already fired, already cancelled).

r_timeout_cblist_clear()

void r_timeout_cblist_clear

(

RTimeoutCBList *

lst

)

Cancel every pending entry and drop the list to empty.

Each entry's destroy notifiers run before its memory is freed.

r_timeout_cblist_first_timeout()

RClockTime r_timeout_cblist_first_timeout

(

RTimeoutCBList *

lst

)

Return the deadline of the head entry, or R_CLOCK_TIME_NONE if the list is empty.

Use to compute the next loop wake-up.

r_timeout_cblist_insert()

rboolean r_timeout_cblist_insert	(	RTimeoutCBList *	lst,
		RToCB **	tocb,
		RClockTime	ts,
		RFunc	cb,
		rpointer	data,
		RDestroyNotify	datanotify,
		rpointer	user,
		RDestroyNotify	usernotify
	)

Schedule cb to fire at ts.

The list keeps itself sorted by deadline; insertion is O(n) in the worst case but typically O(1) for monotonically increasing deadlines.

Parameters

lst	The list.
tocb	Out: handle suitable for r_timeout_cblist_cancel. Pass NULL to discard.
ts	Absolute deadline (in RClockTime ticks).
cb	Callback function.
data	Callback's first argument.
datanotify	Destroy notifier for data, or NULL.
user	Callback's second argument.
usernotify	Destroy notifier for user, or NULL.

r_timeout_cblist_update()

rsize r_timeout_cblist_update	(	RTimeoutCBList *	lst,
		RClockTime	ts
	)

Fire and remove every entry whose deadline is at or before ts; returns the number called.

Typical pattern is to feed the current clock value and re-arm the loop's wake-up from r_timeout_cblist_first_timeout afterwards.