The FreeRADIUS server $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Loading...
Searching...
No Matches
timer.h
Go to the documentation of this file.
1#pragma once
2
3/*
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
17 */
18
19/** Timer lists with event callbacks
20 *
21 * @file src/lib/util/event.h
22 *
23 * @copyright 2025 Arran Cudbard-Bell (a.cudbardb@freeradius.org)
24 */
25RCSIDH(timer_h, "$Id: 824b23f32520f30d206882bed0340070041120ec $")
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31#include <freeradius-devel/util/time.h>
32#include <freeradius-devel/util/talloc.h>
33
34/*
35 * Allow public and private versions of the same structures
36 */
37#ifdef _CONST
38# error _CONST can only be defined in the local header
39#endif
40#ifndef _TIMER_PRIVATE
42# define _CONST const
43#else
44# define _CONST
45#endif
46
47/** Alternative time source, useful for testing
48 *
49 * @return the current time in nanoseconds past the epoch.
50 */
52
53/** Public event timer list structure
54 *
55 * Make the current list time, and time source available, but nothing else.
56 *
57 * This allows us to access these values without the cost of a function call.
58 */
60 fr_event_time_source_t _CONST time; //!< Time source this list uses to get the current time
61 ///< when calculating deltas (fr_timer_in).
62};
63
64/** An opaque timer handle
65 */
66typedef struct fr_timer_s fr_timer_t;
67
68/** Called when a timer event fires
69 *
70 * @param[in] tl timer list event was inserted into.
71 * @param[in] now The current time.
72 * @param[in] uctx User ctx passed to #fr_timer_in or #fr_timer_at.
73 */
74typedef void (*fr_timer_cb_t)(fr_timer_list_t *tl, fr_time_t now, void *uctx);
75
77 TALLOC_CTX *ctx, fr_timer_list_t *tl, fr_timer_t **ev,
80#define fr_timer_at(...) _fr_timer_at(NDEBUG_LOCATION_EXP __VA_ARGS__)
81
83 TALLOC_CTX *ctx, fr_timer_list_t *tl, fr_timer_t **ev,
84 fr_time_delta_t delta, bool free_on_fire, fr_timer_cb_t callback, void const *uctx)
86#define fr_timer_in(...) _fr_timer_in(NDEBUG_LOCATION_EXP __VA_ARGS__)
87
88int fr_timer_disarm(fr_timer_t *ev); /* disarms but does not free */
89
90int fr_timer_delete(fr_timer_t **ev_p) CC_HINT(nonnull); /* disarms AND frees */
91
93
95
97
99
101
103
105
107
109
110#ifdef WITH_EVENT_DEBUG
111void fr_timer_report(fr_timer_list_t *tl, fr_time_t now, void *uctx);
112void fr_timer_dump(fr_timer_list_t *tl);
113#endif
114
115#undef _CONST
116
117#ifdef __cplusplus
118}
119#endif
#define RCSIDH(h, id)
Definition build.h:486
#define NDEBUG_LOCATION_ARGS
Pass caller information to the function.
Definition build.h:263
#define NDEBUG_LOCATION_NONNULL(_num)
Definition build.h:267
struct fr_time_s fr_time_t
"server local" time.
A time delta, a difference in time measured in nanoseconds.
Definition time.h:80
"server local" time.
Definition time.h:69
void const * uctx
Context pointer to pass to the callback.
Definition timer.c:83
fr_timer_cb_t callback
Callback to execute when the timer fires.
Definition timer.c:82
fr_time_t when
When this timer should fire.
Definition timer.c:80
bool free_on_fire
Whether to free the event when it fires.
Definition timer.c:95
fr_timer_list_t * tl
The event list this timer is part of.
Definition timer.c:97
An event timer list.
Definition timer.c:53
A timer event.
Definition timer.c:79
int fr_timer_list_run(fr_timer_list_t *tl, fr_time_t *when)
Execute any pending events in the event loop.
Definition timer.c:815
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_list_disarm(fr_timer_list_t *tl)
Disable all timers in a list.
Definition timer.c:946
fr_time_t fr_timer_when(fr_timer_t *ev)
Internal timestamp representing when the timer should fire.
Definition timer.c:670
uint64_t fr_timer_list_num_events(fr_timer_list_t *tl)
Return number of pending events.
Definition timer.c:965
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_time_t fr_timer_list_when(fr_timer_list_t *tl)
Return the time of the next event.
Definition timer.c:979
fr_timer_list_t * fr_timer_list_ordered_alloc(TALLOC_CTX *ctx, fr_timer_list_t *parent)
Allocate a new sorted event timer list.
Definition timer.c:1076
fr_timer_list_t * fr_timer_list_lst_alloc(TALLOC_CTX *ctx, fr_timer_list_t *parent)
Allocate a new lst based timer list.
Definition timer.c:1050
int fr_timer_disarm(fr_timer_t *ev)
Remove an event from the event list, but don't free the memory.
Definition timer.c:606
#define _CONST
Definition timer.h:42
void fr_timer_list_set_time_func(fr_timer_list_t *tl, fr_event_time_source_t func)
Override event list time source.
Definition timer.c:993
fr_time_t(* fr_event_time_source_t)(void)
Alternative time source, useful for testing.
Definition timer.h:51
void(* fr_timer_cb_t)(fr_timer_list_t *tl, fr_time_t now, void *uctx)
Called when a timer event fires.
Definition timer.h:74
int fr_timer_delete(fr_timer_t **ev_p)
Delete a timer event and free its memory.
Definition timer.c:643
bool fr_timer_armed(fr_timer_t *ev)
Check if a timer event is armed.
Definition timer.c:682
fr_event_time_source_t _CONST time
Time source this list uses to get the current time when calculating deltas (fr_timer_in).
Definition timer.h:60
Public event timer list structure.
Definition timer.h:59
static fr_slen_t parent
Definition pair.h:845
int nonnull(2, 5))