timer.h File Reference

#include <freeradius-devel/util/time.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_armed(_ev)   ((_ev) && _fr_timer_armed(_ev)) /* returns true if the timer is armed */
#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)
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_disarm (fr_timer_list_t *tl)
	Disable all timers in a list.
int	fr_timer_list_force_run (fr_timer_list_t *tl)
	Get the head of the timer list, the event may not be ready to fire.
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_time_t	fr_timer_list_when (fr_timer_list_t *tl)
	Return the time of the next event.
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 59 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 42 of file timer.h.

fr_timer_armed

#define fr_timer_armed

(

_ev

)

((_ev) && _fr_timer_armed(_ev)) /* returns true if the timer is armed */

Definition at line 117 of file timer.h.

fr_timer_at

#define fr_timer_at

(

...

)

_fr_timer_at(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 80 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 102 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 109 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 90 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 97 of file timer.h.

fr_timer_in

#define fr_timer_in

(

...

)

_fr_timer_in(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 86 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 51 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 74 of file timer.h.

fr_timer_list_t

typedef struct fr_timer_list_pub_s fr_timer_list_t

Definition at line 41 of file timer.h.

fr_timer_t

typedef struct fr_timer_s fr_timer_t

An opaque timer handle.

Definition at line 66 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 678 of file timer.c.

_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_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 639 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 602 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

)

Disable all timers in a list.

Definition at line 961 of file timer.c.

Here is the call graph for this function:

fr_timer_list_force_run()

int fr_timer_list_force_run

(

fr_timer_list_t *

tl

)

Get the head of the timer list, the event may not be ready to fire.

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 812 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 1065 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 980 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 1091 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 830 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 1008 of file timer.c.

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 994 of file timer.c.

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 666 of file timer.c.

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

)