timer.h File Reference

#include <freeradius-devel/util/time.h>
#include <freeradius-devel/util/misc.h>
#include <freeradius-devel/util/talloc.h>

Include dependency graph for timer.h:

Go to the source code of this file.

Data Structures
struct	fr_timer_list_pub_s
	Public event timer list structure. More...

Macros
#define	_CONST   const
#define	fr_timer_at(...)   _fr_timer_at(NDEBUG_LOCATION_EXP __VA_ARGS__)
#define	FR_TIMER_DELETE(_ev_p)
#define	FR_TIMER_DELETE_RETURN(_ev_p)    if ((likely((*(_ev_p)) != NULL) && unlikely(!fr_cond_assert_msg(fr_timer_delete(_ev_p) == 0, "Failed to delete timer %p", *(_ev_p))))) return -1;
#define	FR_TIMER_DISARM(_ev)
#define	FR_TIMER_DISARM_RETURN(_ev)    if ((likely(((_ev)) != NULL) && unlikely(!fr_cond_assert_msg(fr_timer_disarm(_ev) == 0, "Failed to disarm timer %p", (_ev))))) return -1;
#define	fr_timer_in(...)   _fr_timer_in(NDEBUG_LOCATION_EXP __VA_ARGS__)

Typedefs
typedef fr_time_t(*	fr_event_time_source_t) (void)
	Alternative time source, useful for testing.
typedef void(*	fr_timer_cb_t) (fr_timer_list_t *tl, fr_time_t now, void *uctx)
	Called when a timer event fires.
typedef struct fr_timer_list_pub_s	fr_timer_list_t
typedef struct fr_timer_s	fr_timer_t
	An opaque timer handle.

Functions
bool	_fr_timer_armed (fr_timer_t *ev)
	Check if a timer event is armed.
int	_fr_timer_at (NDEBUG_LOCATION_ARGS TALLOC_CTX *ctx, fr_timer_list_t *tl, fr_timer_t **ev, fr_time_t when, bool free_on_fire, fr_timer_cb_t callback, void const *uctx)
int	_fr_timer_in (NDEBUG_LOCATION_ARGS TALLOC_CTX *ctx, fr_timer_list_t *tl, fr_timer_t **ev, fr_time_delta_t delta, bool free_on_fire, fr_timer_cb_t callback, void const *uctx)
static bool	fr_timer_armed (fr_timer_t *ev)
int	fr_timer_delete (fr_timer_t **ev_p)
	Delete a timer event and free its memory.
int	fr_timer_disarm (fr_timer_t *ev)
	Remove an event from the event list, but don't free the memory.
int	fr_timer_list_arm (fr_timer_list_t *tl)
	Arm (or re-arm) a timer list.
int	fr_timer_list_disarm (fr_timer_list_t *tl)
	Disarm a timer list.
int	fr_timer_list_force_run (fr_timer_list_t *tl)
	Forcibly run all events in an event loop.
fr_timer_list_t *	fr_timer_list_lst_alloc (TALLOC_CTX *ctx, fr_timer_list_t *parent)
	Allocate a new lst based timer list.
uint64_t	fr_timer_list_num_events (fr_timer_list_t *tl)
	Return number of pending events.
fr_timer_list_t *	fr_timer_list_ordered_alloc (TALLOC_CTX *ctx, fr_timer_list_t *parent)
	Allocate a new sorted event timer list.
int	fr_timer_list_run (fr_timer_list_t *tl, fr_time_t *when)
	Execute any pending events in the event loop.
void	fr_timer_list_set_time_func (fr_timer_list_t *tl, fr_event_time_source_t func)
	Override event list time source.
fr_timer_list_t *	fr_timer_list_shared_alloc (TALLOC_CTX *ctx, fr_timer_list_t *parent, fr_cmp_t cmp, fr_timer_cb_t callback, size_t node_offset, size_t time_offset)
	Allocate a new shared event timer list.
fr_time_t	fr_timer_list_when (fr_timer_list_t *tl)
	Return the time of the next event.
fr_time_delta_t	fr_timer_remaining (fr_timer_t *ev)
	Return time delta between now and when the timer should fire.
int	fr_timer_uctx_insert (fr_timer_list_t *tl, void *uctx)
	Insert a uctx into a shared timer, and update the timer.
void *	fr_timer_uctx_peek (fr_timer_list_t *tl)
int	fr_timer_uctx_remove (fr_timer_list_t *tl, void *uctx)
	Remove a uctx from a shared timer.
fr_time_t	fr_timer_when (fr_timer_t *ev)
	Internal timestamp representing when the timer should fire.
int	NDEBUG_LOCATION_NONNULL (3)
int	NDEBUG_LOCATION_NONNULL (6)))

---

Data Structure Documentation

fr_timer_list_pub_s

struct fr_timer_list_pub_s

Public event timer list structure.

Make the current list time, and time source available, but nothing else.

This allows us to access these values without the cost of a function call.

Definition at line 60 of file timer.h.

Data Fields
fr_event_time_source_t _CONST	time	Time source this list uses to get the current time when calculating deltas (fr_timer_in).

Macro Definition Documentation

_CONST

#define _CONST   const

Definition at line 43 of file timer.h.

fr_timer_at

#define fr_timer_at

(

...

)

_fr_timer_at(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 81 of file timer.h.

FR_TIMER_DELETE

#define FR_TIMER_DELETE

(

_ev_p

)

Value:

                        do { \
                                if ((likely((*(_ev_p)) != NULL) && unlikely(fr_timer_delete(_ev_p) < 0))) { \
                                        fr_assert_msg(0, "Failed to delete timer %p", *(_ev_p)); \
                                } \
                        } while (0)

Definition at line 103 of file timer.h.

FR_TIMER_DELETE_RETURN

#define FR_TIMER_DELETE_RETURN

(

_ev_p

)

if ((likely((*(_ev_p)) != NULL) && unlikely(!fr_cond_assert_msg(fr_timer_delete(_ev_p) == 0, "Failed to delete timer %p", *(_ev_p))))) return -1;

Definition at line 110 of file timer.h.

FR_TIMER_DISARM

#define FR_TIMER_DISARM

(

_ev

)

Value:

                        do { \
                                if (likely((_ev) != NULL) && unlikely(fr_timer_disarm(_ev) < 0)) { \
                                        fr_assert_msg(0, "Failed to disarm timer %p", (_ev)); \
                                } \
                        } while (0)

Definition at line 91 of file timer.h.

FR_TIMER_DISARM_RETURN

#define FR_TIMER_DISARM_RETURN

(

_ev

)

if ((likely(((_ev)) != NULL) && unlikely(!fr_cond_assert_msg(fr_timer_disarm(_ev) == 0, "Failed to disarm timer %p", (_ev))))) return -1;

Definition at line 98 of file timer.h.

fr_timer_in

#define fr_timer_in

(

...

)

_fr_timer_in(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 87 of file timer.h.

Typedef Documentation

fr_event_time_source_t

typedef fr_time_t(* fr_event_time_source_t) (void)

Alternative time source, useful for testing.

Returns

the current time in nanoseconds past the epoch.

Definition at line 52 of file timer.h.

fr_timer_cb_t

typedef void(* fr_timer_cb_t) (fr_timer_list_t *tl, fr_time_t now, void *uctx)

Called when a timer event fires.

Parameters

[in]	tl	timer list event was inserted into.
[in]	now	The current time.
[in]	uctx	User ctx passed to fr_timer_in or fr_timer_at.

Definition at line 75 of file timer.h.

fr_timer_list_t

typedef struct fr_timer_list_pub_s fr_timer_list_t

Definition at line 42 of file timer.h.

fr_timer_t

typedef struct fr_timer_s fr_timer_t

An opaque timer handle.

Definition at line 67 of file timer.h.

Function Documentation

_fr_timer_armed()

bool _fr_timer_armed

(

fr_timer_t *

ev

)

Check if a timer event is armed.

Parameters

[in]

ev

to check.

Returns

• true if the event is armed.
• false if the event is not armed.

Definition at line 742 of file timer.c.

Here is the caller graph for this function:

_fr_timer_at()

int _fr_timer_at	(	NDEBUG_LOCATION_ARGS TALLOC_CTX *	ctx,
		fr_timer_list_t *	tl,
		fr_timer_t **	ev,
		fr_time_t	when,
		bool	free_on_fire,
		fr_timer_cb_t	callback,
		void const *	uctx
	)

_fr_timer_in()

int _fr_timer_in	(	NDEBUG_LOCATION_ARGS TALLOC_CTX *	ctx,
		fr_timer_list_t *	tl,
		fr_timer_t **	ev,
		fr_time_delta_t	delta,
		bool	free_on_fire,
		fr_timer_cb_t	callback,
		void const *	uctx
	)

fr_timer_armed()

static bool fr_timer_armed ( fr_timer_t *  ev )

inlinestatic

Definition at line 120 of file timer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_delete()

int fr_timer_delete

(

fr_timer_t **

ev_p

)

Delete a timer event and free its memory.

Parameters

[in]

ev_p

of the event being deleted.

Returns

• 0 on success.
• -1 on failure.

Definition at line 692 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_disarm()

int fr_timer_disarm

(

fr_timer_t *

ev

)

Remove an event from the event list, but don't free the memory.

Parameters

[in]

ev

to remove from the event list.

Definition at line 655 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_list_arm()

int fr_timer_list_arm

(

fr_timer_list_t *

tl

)

Arm (or re-arm) a timer list.

Parameters

[in]

tl

Timer list to (re)-arm

Returns

• 0 on success.
• -1 on failure.

Definition at line 1122 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_list_disarm()

int fr_timer_list_disarm

(

fr_timer_list_t *

tl

)

Disarm a timer list.

Parameters

[in]

tl

Timer list to disarm

Returns

• 0 on success.
• -1 on failure.

Definition at line 1101 of file timer.c.

Here is the caller graph for this function:

fr_timer_list_force_run()

int fr_timer_list_force_run

(

fr_timer_list_t *

tl

)

Forcibly run all events in an event loop.

This is used to forcefully run every event in the event loop.

We pass in the real time, which may theoretically cause issues if timer callbacks are checking... But the uses of this function are very limited.

Returns

• < 0 if we failed to update the parent list.
• 0 no timer events fired.
• > 0 number of timer event fired.

Definition at line 920 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_list_lst_alloc()

fr_timer_list_t * fr_timer_list_lst_alloc	(	TALLOC_CTX *	ctx,
		fr_timer_list_t *	parent
	)

Allocate a new lst based timer list.

Parameters

[in]	ctx	to insert head timer event into.
[in]	parent	to insert the head timer event into.

Definition at line 1261 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_list_num_events()

uint64_t fr_timer_list_num_events

(

fr_timer_list_t *

tl

)

Return number of pending events.

Note

This includes deferred events, i.e. those yet to be inserted into the main list

Parameters

[in]

tl

to get the number of events from.

Returns

• The number of events in the list.

Definition at line 1149 of file timer.c.

Here is the caller graph for this function:

fr_timer_list_ordered_alloc()

fr_timer_list_t * fr_timer_list_ordered_alloc	(	TALLOC_CTX *	ctx,
		fr_timer_list_t *	parent
	)

Allocate a new sorted event timer list.

Parameters

[in]	ctx	to allocate the event timer list from.
[in]	parent	to insert the head timer event into.

Definition at line 1287 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_list_run()

int fr_timer_list_run	(	fr_timer_list_t *	tl,
		fr_time_t *	when
	)

Execute any pending events in the event loop.

Parameters

[in]	tl	to execute events in.
[in]	when	Process events scheduled to run before or at this time. Set to 0 if no more events. Set to the next event time if there are more events.

Returns

• < 0 if we failed to update the parent list.
• 0 no timer events fired.
• >0 number of timer event fired.

Definition at line 938 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_list_set_time_func()

void fr_timer_list_set_time_func	(	fr_timer_list_t *	tl,
		fr_event_time_source_t	func
	)

Override event list time source.

Parameters

[in]	tl	to set new time function for.
[in]	func	to set.

Definition at line 1200 of file timer.c.

Here is the caller graph for this function:

fr_timer_list_shared_alloc()

fr_timer_list_t * fr_timer_list_shared_alloc	(	TALLOC_CTX *	ctx,
		fr_timer_list_t *	parent,
		fr_cmp_t	cmp,
		fr_timer_cb_t	callback,
		size_t	node_offset,
		size_t	time_offset
	)

Allocate a new shared event timer list.

Parameters

[in]	ctx	to allocate the event timer list from.
[in]	parent	to insert the head timer event into.
[in]	cmp	comparison routine (smaller times are earlier)
[in]	callback	to run on timer event
[in]	node_offset	offset from uctx to the fr_rb_node_t it contains
[in]	time_offset	offset from uctx to the fr_time_t it contains

Definition at line 1308 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_list_when()

fr_time_t fr_timer_list_when

(

fr_timer_list_t *

tl

)

Return the time of the next event.

Parameters

[in]

tl

to get the next event time from.

Returns

• >0 the time of the next event.
• 0 if there are no more events.

Definition at line 1186 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_remaining()

fr_time_delta_t fr_timer_remaining

(

fr_timer_t *

ev

)

Return time delta between now and when the timer should fire.

Parameters

[in]

ev

to get the time delta for.

Definition at line 729 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_uctx_insert()

int fr_timer_uctx_insert	(	fr_timer_list_t *	tl,
		void *	uctx
	)

Insert a uctx into a shared timer, and update the timer.

Parameters

[in]	tl	Timer list to insert into.
[in]	uctx	to insert

Returns

• 0 on success.
• -1 on failure.

Definition at line 1344 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_uctx_peek()

void * fr_timer_uctx_peek

(

fr_timer_list_t *

tl

)

Definition at line 1377 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_uctx_remove()

int fr_timer_uctx_remove	(	fr_timer_list_t *	tl,
		void *	uctx
	)

Remove a uctx from a shared timer.

Parameters

[in]	tl	Timer list to insert into.
[in]	uctx	to remove

Returns

• 0 uctx was successfully removed.
• -1 uctx was removed, but the parent timer was not updated

Definition at line 1367 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_timer_when()

fr_time_t fr_timer_when

(

fr_timer_t *

ev

)

Internal timestamp representing when the timer should fire.

Returns

When the timestamp should fire.

Definition at line 719 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

NDEBUG_LOCATION_NONNULL() [1/2]

int NDEBUG_LOCATION_NONNULL

(

3

)

NDEBUG_LOCATION_NONNULL() [2/2]

int NDEBUG_LOCATION_NONNULL

(

6

)