timer.c File Reference

Various types of event timer list. More...

#include <freeradius-devel/util/debug.h>
#include <freeradius-devel/util/time.h>
#include <freeradius-devel/util/dlist.h>
#include <freeradius-devel/util/event.h>
#include <freeradius-devel/util/strerror.h>
#include <freeradius-devel/util/timer.h>
#include <freeradius-devel/util/value.h>
#include <freeradius-devel/util/lst.h>
#include <freeradius-devel/util/rb.h>
#include <stdbool.h>
#include <talloc.h>

Include dependency graph for timer.c:

Go to the source code of this file.

Data Structures
struct	fr_timer_list_s
	An event timer list. More...
union	fr_timer_list_s.__unnamed154__
struct	fr_timer_s
	A timer event. More...
union	fr_timer_s.__unnamed156__
struct	timer_list_funcs_t

Macros
#define	_TIMER_PRIVATE   1
#define	CHECK_PARENT(_ev)
#define	EVENT_ARMED(_ev)   ((_ev)->tl != NULL)

Typedefs
typedef struct fr_timer_list_s	fr_timer_list_t
typedef int(*	timer_disarm_t) (fr_timer_t *ev)
	Specialisation function to delete a timer.
typedef int(*	timer_insert_t) (fr_timer_list_t *tl, fr_timer_t *ev)
	Specialisation function to insert a timer.
typedef int(*	timer_list_deferred_t) (fr_timer_list_t *tl)
	Process any deferred timer events.
typedef fr_timer_t *(*	timer_list_head_t) (fr_timer_list_t *tl)
	Return the soonest timer event.
typedef uint64_t(*	timer_list_num_elements_t) (fr_timer_list_t *tl)
	Return the number of elements in the list.
typedef int(*	timer_list_run_t) (fr_timer_list_t *tl, fr_time_t *when)
	Specialisation function to execute any pending timers.

Enumerations
enum	timer_list_type_t {   TIMER_LIST_TYPE_LST = 1 ,   TIMER_LIST_TYPE_ORDERED = 2 }
	What type of event list the timer is inserted into. More...

Functions
int	_fr_timer_at (NDEBUG_LOCATION_ARGS TALLOC_CTX *ctx, fr_timer_list_t *tl, fr_timer_t **ev_p, fr_time_t when, bool free_on_fire, fr_timer_cb_t callback, void const *uctx)
	Insert a timer event into an event list.
int	_fr_timer_in (NDEBUG_LOCATION_ARGS TALLOC_CTX *ctx, fr_timer_list_t *tl, fr_timer_t **ev_p, fr_time_delta_t delta, bool free_on_fire, fr_timer_cb_t callback, void const *uctx)
	Insert a timer event into an event list.
static void	_parent_timer_cb (UNUSED fr_timer_list_t *parent_tl, fr_time_t when, void *uctx)
	This callback fires in the parent to execute events in this sublist.
static int	_timer_free (fr_timer_t *ev)
	Remove an event from the event loop.
static int	_timer_list_free (fr_timer_list_t *tl)
	Cleanup all timers currently in the list.
bool	fr_timer_armed (fr_timer_t *ev)
	Check if a timer event is armed.
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.
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.
static int8_t	timer_cmp (void const *a, void const *b)
	Compare two timer events to see which one should occur first.
static fr_timer_list_t *	timer_list_alloc (TALLOC_CTX *ctx, fr_timer_list_t *parent)
static int	timer_list_lst_deferred (fr_timer_list_t *tl)
	Insert a timer event into a the lst.
static fr_timer_t *	timer_list_lst_head (fr_timer_list_t *tl)
	Return the head of the event list.
static uint64_t	timer_list_lst_num_events (fr_timer_list_t *tl)
static int	timer_list_lst_run (fr_timer_list_t *tl, fr_time_t *when)
	Run all scheduled timer events in a lst.
static int	timer_list_ordered_deferred (fr_timer_list_t *tl)
	Move all deferred events into the ordered event list.
static fr_timer_t *	timer_list_ordered_head (fr_timer_list_t *tl)
	Return the head of the ordered list.
static uint64_t	timer_list_ordered_num_events (fr_timer_list_t *tl)
static int	timer_list_ordered_run (fr_timer_list_t *tl, fr_time_t *when)
	Run all scheduled events in an ordered list.
static int	timer_list_parent_update (fr_timer_list_t *tl)
	Utility function to update parent timers.
static int	timer_lst_disarm (fr_timer_t *ev)
static int	timer_lst_insert_at (fr_timer_list_t *tl, fr_timer_t *ev)
	Insert a timer event into a single event timer list.
static int	timer_ordered_disarm (fr_timer_t *ev)
	Remove a timer from a timer list, but don't free it.
static int	timer_ordered_insert_at (fr_timer_list_t *tl, fr_timer_t *ev)
	Insert an event into an ordered timer list.

Variables
static timer_list_funcs_t const	timer_funcs []
	Functions for performing operations on various types of timer list.

Detailed Description

Various types of event timer list.

Copyright

2025 Arran Cudbard-Bell (a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg)

Definition in file timer.c.

---

Data Structure Documentation

fr_timer_list_s

struct fr_timer_list_s

An event timer list.

Definition at line 53 of file timer.c.

Collaboration diagram for fr_timer_list_s:

Data Fields
union fr_timer_list_s.__unnamed154__	__unnamed__
timer_head_t	deferred	A list of timer events to be inserted, after the current batch has been processed. This prevents "busy" timer loops, where other events may starve, or we may never exit.
bool	in_handler	Whether we're currently in a callback.
fr_timer_list_t *	parent	Parent list to insert event into (if any).
fr_timer_t *	parent_ev	Event in the parent's event loop.
struct fr_timer_list_pub_s	pub	Public interface to the event timer list.
timer_list_type_t	type

fr_timer_list_s.__unnamed154__

union fr_timer_list_s.__unnamed154__

Definition at line 56 of file timer.c.

Data Fields
fr_lst_t *	lst	of timer events to be executed.
timer_head_t	ordered	A list of timer events to be executed.

fr_timer_s

struct fr_timer_s

A timer event.

Definition at line 79 of file timer.c.

Collaboration diagram for fr_timer_s:

Data Fields
union fr_timer_s.__unnamed156__	__unnamed__
fr_timer_cb_t	callback	Callback to execute when the timer fires.
fr_timer_entry_t	entry	Entry in a list of timer events.
char const *	file	Source file this event was last updated in.
bool	free_on_fire	Whether to free the event when it fires.
int	line	Line this event was last updated on.
TALLOC_CTX *	linked_ctx	talloc ctx this event was bound to.
fr_timer_t **	parent	A pointer to the parent structure containing the timer event.
fr_timer_list_t *	tl	The event list this timer is part of. This is set to NULL when an event is disarmed, but all other fields are left intact.
void const *	uctx	Context pointer to pass to the callback.
fr_time_t	when	When this timer should fire.

fr_timer_s.__unnamed156__

union fr_timer_s.__unnamed156__

Definition at line 91 of file timer.c.

Data Fields
fr_lst_index_t	lst_idx	Where to store opaque lst data, not used for ordered lists.
fr_dlist_t	ordered_entry	Entry in an ordered list of timer events.

timer_list_funcs_t

struct timer_list_funcs_t

Definition at line 168 of file timer.c.

Collaboration diagram for timer_list_funcs_t:

Data Fields
timer_list_deferred_t	deferred	Function to process deferred events.
timer_disarm_t	disarm	Function to delete a timer event.
timer_list_head_t	head	Function to get the head of the list.
timer_insert_t	insert	Function to insert a timer event.
timer_list_num_elements_t	num_events	Function to get the number of elements in the list.
timer_list_run_t	run	Function to run a timer event.

Macro Definition Documentation

_TIMER_PRIVATE

#define _TIMER_PRIVATE   1

Definition at line 24 of file timer.c.

CHECK_PARENT

#define CHECK_PARENT

(

_ev

)

Value:

        fr_assert_msg(!(_ev)->parent || (*(_ev)->parent == ev), \
                      "Event %p, allocd %s[%d], parent field points to %p", (_ev), (_ev)->file, (_ev)->line, *(_ev)->parent);

Definition at line 109 of file timer.c.

EVENT_ARMED

#define EVENT_ARMED

(

_ev

)

((_ev)->tl != NULL)

Definition at line 178 of file timer.c.

Typedef Documentation

fr_timer_list_t

typedef struct fr_timer_list_s fr_timer_list_t

Definition at line 25 of file timer.c.

timer_disarm_t

typedef int(* timer_disarm_t) (fr_timer_t *ev)

Specialisation function to delete a timer.

Parameters

[in]

ev

Timer event to delete.

Returns

• 0 on success.
• -1 on failure.

Definition at line 130 of file timer.c.

timer_insert_t

typedef int(* timer_insert_t) (fr_timer_list_t *tl, fr_timer_t *ev)

Specialisation function to insert a timer.

Parameters

[in]	tl	Timer list to insert into.
[in]	ev	Timer event to insert.

Returns

• 0 on success.
• -1 on failure.

Definition at line 121 of file timer.c.

timer_list_deferred_t

typedef int(* timer_list_deferred_t) (fr_timer_list_t *tl)

Process any deferred timer events.

Parameters

[in]

tl

to process deferred events for.

Returns

• The head of the list.
• NULL if the list is empty.

Definition at line 158 of file timer.c.

timer_list_head_t

typedef fr_timer_t *(* timer_list_head_t) (fr_timer_list_t *tl)

Return the soonest timer event.

Parameters

[in]

tl

to get the head of.

Returns

• The head of the list.
• NULL if the list is empty.

Definition at line 149 of file timer.c.

timer_list_num_elements_t

typedef uint64_t(* timer_list_num_elements_t) (fr_timer_list_t *tl)

Return the number of elements in the list.

Parameters

[in]

tl

to get the number of elements from.

Returns

• The number of elements in the list.

Definition at line 166 of file timer.c.

timer_list_run_t

typedef int(* timer_list_run_t) (fr_timer_list_t *tl, fr_time_t *when)

Specialisation function to execute any pending timers.

Parameters

[in]	tl	Timer list to execute.
[in,out]	when	Our current time, updated to the next event time (i.e. the next time we'll need to run something)

Returns

• 0 no timer events fired.
• 1 a timer event fired.

Definition at line 140 of file timer.c.

Enumeration Type Documentation

timer_list_type_t

enum timer_list_type_t

What type of event list the timer is inserted into.

Enumerator
TIMER_LIST_TYPE_LST	Self-sorting timer list based on a left leaning skeleton tree.
TIMER_LIST_TYPE_ORDERED	Strictly ordered list of events in a dlist.

Definition at line 45 of file timer.c.

Function Documentation

_fr_timer_at()

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

Insert a timer event into an event list.

Note

The talloc parent of the memory returned in ev_p must not be changed. If the lifetime of the event needs to be bound to another context this function should be called with the existing event pointed to by ev_p.

Parameters

[in]	ctx	to bind lifetime of the event to.
[in]	tl	to insert event into.
[in,out]	ev_p	If not NULL modify this event instead of creating a new one. This is a parent in a temporal sense, not in a memory structure or dependency sense.
[in]	when	we should run the event.
[in]	free_on_fire	Whether event memory should be freed if the event fires.
[in]	callback	function to execute if the event fires.
[in]	uctx	user data to pass to the event.

Returns

• 0 on success.
• -1 on failure.

Definition at line 375 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

_fr_timer_in()

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

Insert a timer event into an event list.

Note

The talloc parent of the memory returned in ev_p must not be changed. If the lifetime of the event needs to be bound to another context this function should be called with the existing event pointed to by ev_p.

Parameters

[in]	ctx	to bind lifetime of the event to.
[in]	tl	to insert event into.
[in,out]	ev_p	If not NULL modify this event instead of creating a new one. This is a parent in a temporal sense, not in a memory structure or dependency sense.
[in]	delta	In how many nanoseconds to wait before should we execute the event.
[in]	callback	function to execute if the event fires.
[in]	uctx	user data to pass to the event.

Returns

• 0 on success.
• -1 on failure.

Definition at line 534 of file timer.c.

Here is the call graph for this function:

_parent_timer_cb()

static void _parent_timer_cb ( UNUSED fr_timer_list_t *  parent_tl, fr_time_t  when, void *  uctx  )

static

This callback fires in the parent to execute events in this sublist.

Parameters

[in]	parent_tl	Parent event timer list.
[in]	when	When the parent timer fired.
[in]	uctx	Sublist to execute.

Definition at line 244 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

_timer_free()

static int _timer_free ( fr_timer_t *  ev )

static

Remove an event from the event loop.

Parameters

[in]

ev

to free.

Returns

• 0 on success.
• -1 on failure.

Definition at line 341 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

_timer_list_free()

static int _timer_list_free ( fr_timer_list_t *  tl )

static

Cleanup all timers currently in the list.

Parameters

[in]

tl

to cleanup.

Returns

• 0 on success.
• -1 on failure.

Definition at line 1005 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

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

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 643 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 606 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 946 of file timer.c.

Here is the call 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 1050 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 965 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 1076 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 updated the parent list.
• 0 no timer events fired.
• >0 number of timer event fired.

Definition at line 815 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 993 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 979 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 670 of file timer.c.

Here is the caller graph for this function:

timer_cmp()

static int8_t timer_cmp ( void const *  a, void const *  b  )

static

Compare two timer events to see which one should occur first.

Parameters

[in]	a	the first timer event.
[in]	b	the second timer event.

Returns

• +1 if a should occur later than b.
• -1 if a should occur earlier than b.
• 0 if both events occur at the same time.

Definition at line 231 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

timer_list_alloc()

static fr_timer_list_t * timer_list_alloc ( TALLOC_CTX *  ctx, fr_timer_list_t *  parent  )

static

Definition at line 1023 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

timer_list_lst_deferred()

static int timer_list_lst_deferred ( fr_timer_list_t *  tl )

static

Insert a timer event into a the lst.

Parameters

[in]

tl

to move events in.

Returns

• 0 on success.
• -1 on failure.

Definition at line 879 of file timer.c.

Here is the call graph for this function:

timer_list_lst_head()

static fr_timer_t * timer_list_lst_head ( fr_timer_list_t *  tl )

static

Return the head of the event list.

Parameters

[in]

tl

to get the head of.

Returns

• The head of the trie.
• NULL, if there's no head.

Definition at line 855 of file timer.c.

Here is the call graph for this function:

timer_list_lst_num_events()

static uint64_t timer_list_lst_num_events ( fr_timer_list_t *  tl )

static

Definition at line 933 of file timer.c.

Here is the call graph for this function:

timer_list_lst_run()

static int timer_list_lst_run ( fr_timer_list_t *  tl, fr_time_t *  when  )

static

Run all scheduled timer events in a lst.

Parameters

[in]	tl	containing the timer events.
[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 no timer events fired.
• 1 a timer event fired.

Definition at line 698 of file timer.c.

Here is the call graph for this function:

timer_list_ordered_deferred()

static int timer_list_ordered_deferred ( fr_timer_list_t *  tl )

static

Move all deferred events into the ordered event list.

This operation is O(1).

Parameters

[in]

tl

to move events in.

Returns

• 0 on success.
• -1 on failure.

Definition at line 902 of file timer.c.

timer_list_ordered_head()

static fr_timer_t * timer_list_ordered_head ( fr_timer_list_t *  tl )

static

Return the head of the ordered list.

Parameters

[in]

tl

to get the head of.

Returns

• The head of the trie.
• NULL, if there's no head.

Definition at line 867 of file timer.c.

Here is the caller graph for this function:

timer_list_ordered_num_events()

static uint64_t timer_list_ordered_num_events ( fr_timer_list_t *  tl )

static

Definition at line 938 of file timer.c.

timer_list_ordered_run()

static int timer_list_ordered_run ( fr_timer_list_t *  tl, fr_time_t *  when  )

static

Run all scheduled events in an ordered list.

Parameters

[in]	tl	containing the timer events.
[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 updated the parent list.
• 0 no timer events fired.
• >0 number of timer event fired.

Definition at line 757 of file timer.c.

Here is the call graph for this function:

timer_list_parent_update()

static int timer_list_parent_update ( fr_timer_list_t *  tl )

inlinestatic

Utility function to update parent timers.

Parameters

[in]

tl

to update parent timers for.

Returns

• 0 on success.
• -1 on failure.

Definition at line 260 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

timer_lst_disarm()

static int timer_lst_disarm ( fr_timer_t *  ev )

static

Definition at line 544 of file timer.c.

Here is the call graph for this function:

timer_lst_insert_at()

static int timer_lst_insert_at ( fr_timer_list_t *  tl, fr_timer_t *  ev  )

static

Insert a timer event into a single event timer list.

Parameters

[in]	tl	to insert the event into.
[in]	ev	to insert.

Returns

• 0 on success.
• -1 on failure.

Definition at line 296 of file timer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

timer_ordered_disarm()

static int timer_ordered_disarm ( fr_timer_t *  ev )

static

Remove a timer from a timer list, but don't free it.

Parameters

[in]

ev

to remove.

Definition at line 580 of file timer.c.

timer_ordered_insert_at()

static int timer_ordered_insert_at ( fr_timer_list_t *  tl, fr_timer_t *  ev  )

static

Insert an event into an ordered timer list.

Timer must be in order, i.e. either before first event, or after last event

Parameters

[in]	tl	to insert the event into.
[in]	ev	to insert.

Returns

• 0 on success.
• -1 on failure.

Definition at line 316 of file timer.c.

Variable Documentation

timer_funcs

timer_list_funcs_t const timer_funcs[]

static

Initial value:

= {
        [TIMER_LIST_TYPE_LST] = {
                .insert = timer_lst_insert_at,
                .disarm = timer_lst_disarm,
 
                .run = timer_list_lst_run,
                .head = timer_list_lst_head,
                .deferred = timer_list_lst_deferred,
                .num_events = timer_list_lst_num_events
        },
        [TIMER_LIST_TYPE_ORDERED] = {
                .insert = timer_ordered_insert_at,
                .disarm = timer_ordered_disarm,
 
                .run = timer_list_ordered_run,
                .head = timer_list_ordered_head,
                .deferred = timer_list_ordered_deferred,
                .num_events = timer_list_ordered_num_events
        }
}

Functions for performing operations on various types of timer list.

Definition at line 201 of file timer.c.