Wrapper around libkqueue to make managing events easier. More...

#include <freeradius-devel/build.h>
#include <freeradius-devel/missing.h>
#include <freeradius-devel/util/time.h>
#include <freeradius-devel/util/talloc.h>
#include <stdbool.h>
#include <sys/event.h>

Include dependency graph for event.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
union	fr_event_funcs_t
	Union of all filter functions. More...

struct	fr_event_io_func_t
	Callbacks for the FR_EVENT_FILTER_IO filter. More...

struct	fr_event_update_t
	Structure describing a modification to a filter's state. More...

struct	fr_event_vnode_func_t
	Callbacks for the FR_EVENT_FILTER_VNODE filter. More...

Macros
#define	fr_event_fd_insert(...) _fr_event_fd_insert(NDEBUG_LOCATION_EXP __VA_ARGS__)

#define	fr_event_fd_mode(...) _fr_event_fd_move(NDEBUG_LOCATION_EXP __VA_ARGS__)

#define	fr_event_filter_insert(...) _fr_event_filter_insert(NDEBUG_LOCATION_EXP __VA_ARGS__)

#define	fr_event_filter_update(...) _fr_event_filter_update(NDEBUG_LOCATION_EXP __VA_ARGS__)

#define	fr_event_pid_reap(...) _fr_event_pid_reap(NDEBUG_LOCATION_EXP __VA_ARGS__)

#define	fr_event_pid_wait(...) _fr_event_pid_wait(NDEBUG_LOCATION_EXP __VA_ARGS__)

#define	FR_EVENT_RESUME(_s, _f) { .offset = offsetof(_s, _f), .op = FR_EVENT_OP_RESUME }
	Re-add the filter for a func from kevent. More...

#define	FR_EVENT_SUSPEND(_s, _f) { .offset = offsetof(_s, _f), .op = FR_EVENT_OP_SUSPEND }
	Temporarily remove the filter for a func from kevent. More...

#define	fr_event_timer_at(...) _fr_event_timer_at(NDEBUG_LOCATION_EXP __VA_ARGS__)

#define	fr_event_timer_in(...) _fr_event_timer_in(NDEBUG_LOCATION_EXP __VA_ARGS__)

#define	fr_event_user_insert(_ctx, _ev_p, _el, _trigger, _callback, _uctx) _fr_event_user_insert(NDEBUG_LOCATION_EXP _ctx, _ev_p, _el, _trigger, _callback, _uctx)

Typedefs
typedef void(*	fr_event_error_cb_t) (fr_event_list_t el, int fd, int flags, int fd_errno, void uctx)
	Called when an IO error event occurs on a file descriptor. More...

typedef void(*	fr_event_fd_cb_t) (fr_event_list_t el, int fd, int flags, void uctx)
	Called when an IO event occurs on a file descriptor. More...

typedef struct fr_event_fd	fr_event_fd_t
	An opaque file descriptor handle. More...

typedef struct fr_event_list	fr_event_list_t
	An opaque event list handle. More...

typedef void(*	fr_event_pid_cb_t) (fr_event_list_t el, pid_t pid, int status, void uctx)
	Called when a child process has exited. More...

typedef struct fr_event_pid	fr_event_pid_t
	An opaque PID status handle. More...

typedef int(*	fr_event_status_cb_t) (fr_time_t now, fr_time_delta_t wake, void *uctx)
	Called after each event loop cycle. More...

typedef fr_time_t(*	fr_event_time_source_t) (void)
	Alternative time source, useful for testing. More...

typedef void(*	fr_event_timer_cb_t) (fr_event_list_t el, fr_time_t now, void uctx)
	Called when a timer event fires. More...

typedef struct fr_event_timer	fr_event_timer_t
	An opaque timer handle. More...

typedef void(*	fr_event_user_cb_t) (fr_event_list_t el, void uctx)
	Called when a user kevent occurs. More...

typedef struct fr_event_user_s	fr_event_user_t
	An opaquer user event handle. More...

Enumerations
enum	fr_event_filter_t { FR_EVENT_FILTER_IO = 1 , FR_EVENT_FILTER_VNODE }
	The type of filter to install for an FD. More...

enum	fr_event_op_t { FR_EVENT_OP_SUSPEND = 1 , FR_EVENT_OP_RESUME }
	Operations to perform on filter. More...

Functions
int	_fr_event_fd_insert (NDEBUG_LOCATION_ARGS TALLOC_CTX ctx, fr_event_fd_t ef_out, fr_event_list_t el, int fd, fr_event_fd_cb_t read_fn, fr_event_fd_cb_t write_fn, fr_event_error_cb_t error, void *uctx)
	Associate I/O callbacks with a file descriptor. More...

int	_fr_event_fd_move (NDEBUG_LOCATION_ARGS fr_event_list_t dst, fr_event_list_t src, int fd, fr_event_filter_t filter)
	Move a file descriptor event from one event list to another. More...

int	_fr_event_filter_insert (NDEBUG_LOCATION_ARGS TALLOC_CTX ctx, fr_event_fd_t ef_out, fr_event_list_t el, int fd, fr_event_filter_t filter, void funcs, fr_event_error_cb_t error, void uctx)
	Insert a filter for the specified fd. More...

int	_fr_event_filter_update (NDEBUG_LOCATION_ARGS fr_event_list_t *el, int fd, fr_event_filter_t filter, fr_event_update_t const updates[])
	Suspend/resume a subset of filters. More...

int	_fr_event_pid_reap (NDEBUG_LOCATION_ARGS fr_event_list_t el, pid_t pid, fr_event_pid_cb_t wait_fn, void uctx)))
	Asynchronously wait for a PID to exit, then reap it. More...

int	_fr_event_pid_wait (NDEBUG_LOCATION_ARGS TALLOC_CTX ctx, fr_event_list_t el, fr_event_pid_t const *ev_p, pid_t pid, fr_event_pid_cb_t wait_fn, void uctx)))
	Insert a PID event into an event list. More...

int	_fr_event_timer_at (NDEBUG_LOCATION_ARGS TALLOC_CTX ctx, fr_event_list_t el, fr_event_timer_t const *ev, fr_time_t when, fr_event_timer_cb_t callback, void const uctx)
	Insert a timer event into an event list. More...

int	_fr_event_timer_in (NDEBUG_LOCATION_ARGS TALLOC_CTX ctx, fr_event_list_t el, fr_event_timer_t const *ev, fr_time_delta_t delta, fr_event_timer_cb_t callback, void const uctx)
	Insert a timer event into an event list. More...

int	_fr_event_user_insert (NDEBUG_LOCATION_ARGS TALLOC_CTX ctx, fr_event_list_t el, fr_event_user_t *ev_p, bool trigger, fr_event_user_cb_t callback, void uctx)
	Add a user callback to the event list. More...

int	fr_event_corral (fr_event_list_t *el, fr_time_t now, bool wait)
	Gather outstanding timer and file descriptor events. More...

int	fr_event_fd_armour (fr_event_list_t *el, int fd, fr_event_filter_t, uintptr_t armour)
	Armour an FD. More...

fr_event_fd_cb_t	fr_event_fd_cb (fr_event_fd_t *ef, int filter, int fflags)
	Returns the appropriate callback function for a given event. More...

int	fr_event_fd_delete (fr_event_list_t *el, int fd, fr_event_filter_t filter)
	Remove a file descriptor from the event loop. More...

fr_event_fd_t *	fr_event_fd_handle (fr_event_list_t *el, int fd, fr_event_filter_t filter)
	Get the opaque event handle from a file descriptor. More...

void *	fr_event_fd_uctx (fr_event_fd_t *ef)
	Returns the uctx associated with an fr_event_fd_t handle. More...

int	fr_event_fd_unarmour (fr_event_list_t *el, int fd, fr_event_filter_t filter, uintptr_t armour)
	Unarmour an FD. More...

fr_event_list_t *	fr_event_list_alloc (TALLOC_CTX ctx, fr_event_status_cb_t status, void status_ctx)
	Initialise a new event list. More...

bool	fr_event_list_empty (fr_event_list_t *el)
	Return whether the event loop has any active events. More...

int	fr_event_list_kq (fr_event_list_t *el)
	Return the kq associated with an event list. More...

uint64_t	fr_event_list_num_fds (fr_event_list_t *el)
	Return the number of file descriptors is_registered with this event loop. More...

uint64_t	fr_event_list_num_timers (fr_event_list_t *el)
	Return the number of timer events currently scheduled. More...

unsigned int	fr_event_list_reap_signal (fr_event_list_t *el, fr_time_delta_t timeout, int signal)
	Send a signal to all the processes we have in our reap list, and reap them. More...

void	fr_event_list_set_time_func (fr_event_list_t *el, fr_event_time_source_t func)
	Override event list time source. More...

fr_time_t	fr_event_list_time (fr_event_list_t *el)
	Get the current server time according to the event list. More...

int	fr_event_loop (fr_event_list_t *el)
	Run an event loop. More...

void	fr_event_loop_exit (fr_event_list_t *el, int code)
	Signal an event loop exit with the specified code. More...

bool	fr_event_loop_exiting (fr_event_list_t *el)
	Check to see whether the event loop is in the process of exiting. More...

int	fr_event_post_delete (fr_event_list_t el, fr_event_timer_cb_t callback, void uctx))
	Delete a post-event callback from the event list. More...

int	fr_event_post_insert (fr_event_list_t el, fr_event_timer_cb_t callback, void uctx))
	Add a post-event callback to the event list. More...

int	fr_event_pre_delete (fr_event_list_t el, fr_event_status_cb_t callback, void uctx))
	Delete a pre-event callback from the event list. More...

int	fr_event_pre_insert (fr_event_list_t el, fr_event_status_cb_t callback, void uctx))
	Add a pre-event callback to the event list. More...

void	fr_event_service (fr_event_list_t *el)
	Service any outstanding timer or file descriptor events. More...

int	fr_event_timer_delete (fr_event_timer_t const **ev)
	Delete a timer event from the event list. More...

int	fr_event_timer_run (fr_event_list_t el, fr_time_t when)
	Run a single scheduled timer event. More...

fr_time_t	fr_event_timer_when (fr_event_timer_t const *ev)
	Internal timestamp representing when the timer should fire. More...

int	fr_event_user_delete (fr_event_list_t el, fr_event_user_cb_t user, void uctx))

int	fr_event_user_trigger (fr_event_list_t el, fr_event_user_t ev)
	Trigger a user event. More...

Detailed Description

Wrapper around libkqueue to make managing events easier.

Copyright: 2007 The FreeRADIUS server project; 2007 Alan DeKok (aland.nosp@m.@dep.nosp@m.loyin.nosp@m.grad.nosp@m.ius.c.nosp@m.om)

Definition in file event.h.

Data Structure Documentation

◆ fr_event_funcs_t

union fr_event_funcs_t

Union of all filter functions.

Definition at line 198 of file event.h.

Collaboration diagram for fr_event_funcs_t:

Data Fields
fr_event_io_func_t	io	Read/write functions.
fr_event_vnode_func_t	vnode	vnode callback functions.

◆ fr_event_io_func_t

struct fr_event_io_func_t

Callbacks for the FR_EVENT_FILTER_IO filter.

Definition at line 173 of file event.h.

Collaboration diagram for fr_event_io_func_t:

Data Fields
fr_event_fd_cb_t	read	Callback for when data is available.
fr_event_fd_cb_t	write	Callback for when we can write data.

◆ fr_event_update_t

struct fr_event_update_t

Structure describing a modification to a filter's state.

Definition at line 75 of file event.h.

Data Fields
size_t	offset	Offset of function in func struct.
fr_event_op_t	op	Operation to perform on function/filter.

◆ fr_event_vnode_func_t

struct fr_event_vnode_func_t

Callbacks for the FR_EVENT_FILTER_VNODE filter.

Definition at line 180 of file event.h.

Collaboration diagram for fr_event_vnode_func_t:

Data Fields
fr_event_fd_cb_t	attrib	File attributes changed.
fr_event_fd_cb_t	delete	The file was deleted.
fr_event_fd_cb_t	extend	Additional files were added to a directory.
fr_event_fd_cb_t	link	The link count on the file changed.
fr_event_fd_cb_t	rename	The file was renamed.
fr_event_fd_cb_t	write	The file was written to.

Macro Definition Documentation

◆ fr_event_fd_insert

#define fr_event_fd_insert ( ... ) _fr_event_fd_insert(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 232 of file event.h.

◆ fr_event_fd_mode

#define fr_event_fd_mode ( ... ) _fr_event_fd_move(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 210 of file event.h.

◆ fr_event_filter_insert

#define fr_event_filter_insert ( ... ) _fr_event_filter_insert(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 219 of file event.h.

◆ fr_event_filter_update

#define fr_event_filter_update ( ... ) _fr_event_filter_update(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 224 of file event.h.

◆ fr_event_pid_reap

#define fr_event_pid_reap ( ... ) _fr_event_pid_reap(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 271 of file event.h.

◆ fr_event_pid_wait

#define fr_event_pid_wait ( ... ) _fr_event_pid_wait(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 265 of file event.h.

◆ FR_EVENT_RESUME

#define FR_EVENT_RESUME	(	_s,
		_f
	)	{ .offset = offsetof(_s, _f), .op = FR_EVENT_OP_RESUME }

Re-add the filter for a func from kevent.

Use to populate elements in an array of fr_event_update_t.

static fr_event_update_t resume_read[] = {
      FR_EVENT_RESUME(fr_event_io_func_t, read),
      { 0 }
}

Parameters

[in]	_s	the structure containing the func to suspend.
[in]	_f	the func to resume.

Definition at line 110 of file event.h.

◆ FR_EVENT_SUSPEND

#define FR_EVENT_SUSPEND	(	_s,
		_f
	)	{ .offset = offsetof(_s, _f), .op = FR_EVENT_OP_SUSPEND }

Temporarily remove the filter for a func from kevent.

Use to populate elements in an array of fr_event_update_t.

static fr_event_update_t pause_read[] = {
      FR_EVENT_SUSPEND(fr_event_io_func_t, read),
      { 0 }
}

Parameters

[in]	_s	the structure containing the func to suspend.
[in]	_f	the func to suspend.

Definition at line 94 of file event.h.

◆ fr_event_timer_at

#define fr_event_timer_at ( ... ) _fr_event_timer_at(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 250 of file event.h.

◆ fr_event_timer_in

#define fr_event_timer_in ( ... ) _fr_event_timer_in(NDEBUG_LOCATION_EXP __VA_ARGS__)

Definition at line 255 of file event.h.

◆ fr_event_user_insert

#define fr_event_user_insert	(	_ctx,
		_ev_p,
		_el,
		_trigger,
		_callback,
		_uctx
	)	_fr_event_user_insert(NDEBUG_LOCATION_EXP _ctx, _ev_p, _el, _trigger, _callback, _uctx)

Definition at line 280 of file event.h.

Typedef Documentation

◆ fr_event_error_cb_t

typedef void(* fr_event_error_cb_t) (fr_event_list_t *el, int fd, int flags, int fd_errno, void *uctx)

Called when an IO error event occurs on a file descriptor.

Parameters

[in]	el	Event list the file descriptor was inserted into.
[in]	fd	That experienced the IO event.
[in]	flags	field as returned by kevent.
[in]	fd_errno	File descriptor error.
[in]	uctx	User ctx passed to fr_event_fd_insert.

Definition at line 147 of file event.h.

◆ fr_event_fd_cb_t

typedef void(* fr_event_fd_cb_t) (fr_event_list_t *el, int fd, int flags, void *uctx)

Called when an IO event occurs on a file descriptor.

Parameters

[in]	el	Event list the file descriptor was inserted into.
[in]	fd	That experienced the IO event.
[in]	flags	field as returned by kevent.
[in]	uctx	User ctx passed to fr_event_fd_insert.

Definition at line 137 of file event.h.

◆ fr_event_fd_t

typedef struct fr_event_fd fr_event_fd_t

An opaque file descriptor handle.

Definition at line 1 of file event.h.

◆ fr_event_list_t

typedef struct fr_event_list fr_event_list_t

An opaque event list handle.

Definition at line 1 of file event.h.

◆ fr_event_pid_cb_t

typedef void(* fr_event_pid_cb_t) (fr_event_list_t *el, pid_t pid, int status, void *uctx)

Called when a child process has exited.

Parameters

[in]	el	Event list
[in]	pid	That exited
[in]	status	exit status
[in]	uctx	User ctx passed to fr_event_fd_insert.

Definition at line 156 of file event.h.

◆ fr_event_pid_t

typedef struct fr_event_pid fr_event_pid_t

An opaque PID status handle.

Definition at line 1 of file event.h.

◆ fr_event_status_cb_t

typedef int(* fr_event_status_cb_t) (fr_time_t now, fr_time_delta_t wake, void *uctx)

Called after each event loop cycle.

Called before calling kqueue to put the thread in a sleeping state.

Parameters

[in]	now	The current time.
[in]	wake	When we'll next need to wake up to service an event.
[in]	uctx	User ctx passed to fr_event_list_alloc.

Definition at line 128 of file event.h.

◆ 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 169 of file event.h.

◆ fr_event_timer_cb_t

typedef void(* fr_event_timer_cb_t) (fr_event_list_t *el, fr_time_t now, void *uctx)

Called when a timer event fires.

Parameters

[in]	now	The current time.
[in]	el	Event list the timer event was inserted into.
[in]	uctx	User ctx passed to fr_event_timer_in or fr_event_timer_at.

Definition at line 118 of file event.h.

◆ fr_event_timer_t

typedef struct fr_event_timer fr_event_timer_t

An opaque timer handle.

Definition at line 1 of file event.h.

◆ fr_event_user_cb_t

typedef void(* fr_event_user_cb_t) (fr_event_list_t *el, void *uctx)

Called when a user kevent occurs.

Parameters

[in]	el	Event list
[in]	uctx	User ctx passed to fr_event_user_insert.

Definition at line 163 of file event.h.

◆ fr_event_user_t

typedef struct fr_event_user_s fr_event_user_t

An opaquer user event handle.

Definition at line 1 of file event.h.

Enumeration Type Documentation

◆ fr_event_filter_t

enum fr_event_filter_t

The type of filter to install for an FD.

Enumerator
FR_EVENT_FILTER_IO	Combined filter for read/write functions/.
FR_EVENT_FILTER_VNODE	Filter for vnode subfilters.

Definition at line 61 of file event.h.

◆ fr_event_op_t

enum fr_event_op_t

Operations to perform on filter.

Enumerator
FR_EVENT_OP_SUSPEND	Temporarily remove the relevant filter from kevent.
FR_EVENT_OP_RESUME	Reinsert the filter into kevent.

Definition at line 68 of file event.h.

Function Documentation

◆ _fr_event_fd_insert()

int _fr_event_fd_insert	(	NDEBUG_LOCATION_ARGS TALLOC_CTX *	ctx,
		fr_event_fd_t **	ef_out,
		fr_event_list_t *	el,
		int	fd,
		fr_event_fd_cb_t	read_fn,
		fr_event_fd_cb_t	write_fn,
		fr_event_error_cb_t	error,
		void *	uctx
	)

Associate I/O callbacks with a file descriptor.

Parameters

[in]	ctx	to bind lifetime of the event to.
[out]	ef_out	Where to store the output event
[in]	el	to insert fd callback into.
[in]	fd	to install filters for.
[in]	read_fn	function to call when fd is readable.
[in]	write_fn	function to call when fd is writable.
[in]	error	function to call when an error occurs on the fd.
[in]	uctx	to pass to handler.

Returns

0 on success.
-1 on failure.

Definition at line 1226 of file event.c.

Here is the call graph for this function:

◆ _fr_event_fd_move()

int _fr_event_fd_move	(	NDEBUG_LOCATION_ARGS fr_event_list_t *	dst,
		fr_event_list_t *	src,
		int	fd,
		fr_event_filter_t	filter
	)

Move a file descriptor event from one event list to another.

FIXME - Move suspended events too.

Note: Any pending events will not be transferred.

Parameters

[in]	dst	Event list to move file descriptor event to.
[in]	src	Event list to move file descriptor from.
[in]	fd	of the event to move.
[in]	filter	of the event to move.

Returns

0 on success.
-1 on failure. The event will remain active in the src list.

Definition at line 942 of file event.c.

Here is the call graph for this function:

◆ _fr_event_filter_insert()

int _fr_event_filter_insert	(	NDEBUG_LOCATION_ARGS TALLOC_CTX *	ctx,
		fr_event_fd_t **	ef_out,
		fr_event_list_t *	el,
		int	fd,
		fr_event_filter_t	filter,
		void *	funcs,
		fr_event_error_cb_t	error,
		void *	uctx
	)

Insert a filter for the specified fd.

Parameters

[in]	ctx	to bind lifetime of the event to.
[out]	ef_out	Previously allocated ef, or NULL.
[in]	el	to insert fd callback into.
[in]	fd	to install filters for.
[in]	filter	one of the fr_event_filter_t values.
[in]	funcs	Structure containing callback functions. If a function pointer is set, the equivalent kevent filter will be installed.
[in]	error	function to call when an error occurs on the fd.
[in]	uctx	to pass to handler.

Definition at line 1070 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _fr_event_filter_update()

int _fr_event_filter_update	(	NDEBUG_LOCATION_ARGS fr_event_list_t *	el,
		int	fd,
		fr_event_filter_t	filter,
		fr_event_update_t const	updates[]
	)

Suspend/resume a subset of filters.

This function trades producing useful errors for speed.

An example of suspending the read filter for an FD would be:

static fr_event_update_t pause_read[] = {
      FR_EVENT_SUSPEND(fr_event_io_func_t, read),
      { 0 }
}
 
fr_event_filter_update(el, fd, FR_EVENT_FILTER_IO, pause_read);

Parameters

[in]	el	to update descriptor in.
[in]	fd	to update filters for.
[in]	filter	The type of filter to update.
[in]	updates	An array of updates to toggle filters on/off without removing the callback function.

Definition at line 993 of file event.c.

Here is the call graph for this function:

◆ _fr_event_pid_reap()

int _fr_event_pid_reap	(	NDEBUG_LOCATION_ARGS fr_event_list_t *	el,
		pid_t	pid,
		fr_event_pid_cb_t	callback,
		void *	uctx
	)

Asynchronously wait for a PID to exit, then reap it.

This is intended to be used when we no longer care about a process exiting, but we still want to clean up its state so we don't have zombie processes sticking around.

Parameters

[in]	el	to use to reap the process.
[in]	pid	to reap.
[in]	callback	to call when the process is reaped. May be NULL.
[in]	uctx	to pass to callback.

Returns

-1 if we couldn't find the process or it has already exited/been reaped.
0 on success (we setup a process handler).

Definition at line 1961 of file event.c.

Here is the call graph for this function:

◆ _fr_event_pid_wait()

int _fr_event_pid_wait	(	NDEBUG_LOCATION_ARGS TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		fr_event_pid_t const **	ev_p,
		pid_t	pid,
		fr_event_pid_cb_t	callback,
		void *	uctx
	)

Insert a PID 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]	el	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]	pid	child PID to wait for
[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 1734 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _fr_event_timer_at()

int _fr_event_timer_at	(	NDEBUG_LOCATION_ARGS TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		fr_event_timer_t const **	ev_p,
		fr_time_t	when,
		fr_event_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]	el	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]	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 1444 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _fr_event_timer_in()

int _fr_event_timer_in	(	NDEBUG_LOCATION_ARGS TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		fr_event_timer_t const **	ev_p,
		fr_time_delta_t	delta,
		fr_event_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]	el	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 1589 of file event.c.

Here is the call graph for this function:

◆ _fr_event_user_insert()

int _fr_event_user_insert	(	NDEBUG_LOCATION_ARGS TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		fr_event_user_t **	ev_p,
		bool	trigger,
		fr_event_user_cb_t	callback,
		void *	uctx
	)

Add a user callback to the event list.

Parameters

[in]	ctx	to allocate the event in.
[in]	el	Containing the timer events.
[out]	ev_p	Where to write a pointer.
[in]	trigger	Whether the user event is triggered initially.
[in]	callback	for EVFILT_USER.
[in]	uctx	for the callback.

Returns

0 on success.
-1 on error.

Definition at line 2180 of file event.c.

Here is the call graph for this function:

◆ fr_event_corral()

int fr_event_corral	(	fr_event_list_t *	el,
		fr_time_t	now,
		bool	wait
	)

Gather outstanding timer and file descriptor events.

Parameters

[in]	el	to process events for.
[in]	now	The current time.
[in]	wait	if true, block on the kevent() call until a timer or file descriptor event occurs.

Returns

<0 error, or the event loop is exiting
the number of outstanding I/O events, +1 if at least one timer will fire.

Definition at line 2407 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_fd_armour()

int fr_event_fd_armour	(	fr_event_list_t *	el,
		int	fd,
		fr_event_filter_t	filter,
		uintptr_t	armour
	)

Armour an FD.

Parameters

[in]	el	to remove file descriptor from.
[in]	fd	to remove.
[in]	filter	The type of filter to remove.
[in]	armour	The armour to add.

Returns

0 if file descriptor was armoured
<0 on error.

Definition at line 1335 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_fd_cb()

fr_event_fd_cb_t fr_event_fd_cb	(	fr_event_fd_t *	ef,
		int	kq_filter,
		int	kq_fflags
	)

Returns the appropriate callback function for a given event.

Parameters

[in]	ef	the event filter fd handle.
[in]	kq_filter	If the callbacks are indexed by filter.
[in]	kq_fflags	If the callbacks are indexed by NOTES (fflags).

Returns

NULL if no event it associated with the given ef/kq_filter or kq_fflags combo.
The callback that would be called if an event with this filter/fflag combo was received.

Definition at line 1311 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_fd_delete()

int fr_event_fd_delete	(	fr_event_list_t *	el,
		int	fd,
		fr_event_filter_t	filter
	)

Remove a file descriptor from the event loop.

Parameters

[in]	el	to remove file descriptor from.
[in]	fd	to remove.
[in]	filter	The type of filter to remove.

Returns

0 if file descriptor was removed.
<0 on error.

Definition at line 1253 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_fd_handle()

fr_event_fd_t* fr_event_fd_handle	(	fr_event_list_t *	el,
		int	fd,
		fr_event_filter_t	filter
	)

Get the opaque event handle from a file descriptor.

Parameters

[in]	el	to search for fd/filter in.
[in]	fd	to search for.
[in]	filter	to search for.

Returns

NULL if no event could be found.
The opaque handle representing an fd event.

Definition at line 1289 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_fd_uctx()

void* fr_event_fd_uctx ( fr_event_fd_t * ef )

Returns the uctx associated with an fr_event_fd_t handle.

Definition at line 1319 of file event.c.

Here is the caller graph for this function:

◆ fr_event_fd_unarmour()

int fr_event_fd_unarmour	(	fr_event_list_t *	el,
		int	fd,
		fr_event_filter_t	filter,
		uintptr_t	armour
	)

Unarmour an FD.

Parameters

[in]	el	to remove file descriptor from.
[in]	fd	to remove.
[in]	filter	The type of filter to remove.
[in]	armour	The armour to remove

Returns

0 if file descriptor was unarmoured
<0 on error.

Definition at line 1365 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_list_alloc()

fr_event_list_t* fr_event_list_alloc	(	TALLOC_CTX *	ctx,
		fr_event_status_cb_t	status,
		void *	status_uctx
	)

Initialise a new event list.

Parameters

[in]	ctx	to allocate memory in.
[in]	status	callback, called on each iteration of the event list.
[in]	status_uctx	context for the status callback

Returns

A pointer to a new event list on success (free with talloc_free).
NULL on error.

Definition at line 2892 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_list_empty()

bool fr_event_list_empty ( fr_event_list_t * el )

Return whether the event loop has any active events.

Definition at line 2972 of file event.c.

Here is the call graph for this function:

◆ fr_event_list_kq()

int fr_event_list_kq ( fr_event_list_t * el )

Return the kq associated with an event list.

Parameters

[in] el to return timer events for.

Returns: kq

Definition at line 618 of file event.c.

◆ fr_event_list_num_fds()

uint64_t fr_event_list_num_fds ( fr_event_list_t * el )

Return the number of file descriptors is_registered with this event loop.

Definition at line 594 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_list_num_timers()

uint64_t fr_event_list_num_timers ( fr_event_list_t * el )

Return the number of timer events currently scheduled.

Parameters

[in] el to return timer events for.

Returns: number of timer events.

Definition at line 606 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_list_reap_signal()

unsigned int fr_event_list_reap_signal	(	fr_event_list_t *	el,
		fr_time_delta_t	timeout,
		int	signal
	)

Send a signal to all the processes we have in our reap list, and reap them.

Parameters

[in]	el	containing the processes to reap.
[in]	timeout	how long to wait before we signal the processes.
[in]	signal	to send to processes. Should be a fatal signal.

Returns: The number of processes reaped.

Definition at line 1997 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_list_set_time_func()

void fr_event_list_set_time_func	(	fr_event_list_t *	el,
		fr_event_time_source_t	func
	)

Override event list time source.

Parameters

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

Definition at line 2964 of file event.c.

Here is the caller graph for this function:

◆ fr_event_list_time()

fr_time_t fr_event_list_time ( fr_event_list_t * el )

Get the current server time according to the event list.

If the event list is currently dispatching events, we return the time this iteration of the event list started.

If the event list is not currently dispatching events, we return the current system time.

Parameters

[in] el to get time from.

Returns: the current time according to the event list.

Definition at line 636 of file event.c.

Here is the caller graph for this function:

◆ fr_event_loop()

int fr_event_loop ( fr_event_list_t * el )

Run an event loop.

Note: Will not return until fr_event_loop_exit is called.

Parameters

[in] el to start processing.

Definition at line 2759 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_loop_exit()

void fr_event_loop_exit	(	fr_event_list_t *	el,
		int	code
	)

Signal an event loop exit with the specified code.

The event loop will complete its current iteration, and then exit with the specified code.

Parameters

[in]	el	to signal to exit.
[in]	code	for fr_event_loop to return.

Definition at line 2737 of file event.c.

Here is the caller graph for this function:

◆ fr_event_loop_exiting()

bool fr_event_loop_exiting ( fr_event_list_t * el )

Check to see whether the event loop is in the process of exiting.

Parameters

[in] el to check.

Definition at line 2748 of file event.c.

Here is the caller graph for this function:

◆ fr_event_post_delete()

int fr_event_post_delete	(	fr_event_list_t *	el,
		fr_event_timer_cb_t	callback,
		void *	uctx
	)

Delete a post-event callback from the event list.

Parameters

[in]	el	Containing the timer events.
[in]	callback	The post-processing callback.
[in]	uctx	for the callback.

Returns

< 0 on error
0 on success

Definition at line 2328 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_post_insert()

int fr_event_post_insert	(	fr_event_list_t *	el,
		fr_event_timer_cb_t	callback,
		void *	uctx
	)

Add a post-event callback to the event list.

Events are serviced in insert order. i.e. insert A, B, we then have A running before B.

Parameters

[in]	el	Containing the timer events.
[in]	callback	The post-processing callback.
[in]	uctx	for the callback.

Returns

< 0 on error
0 on success

Definition at line 2306 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_pre_delete()

int fr_event_pre_delete	(	fr_event_list_t *	el,
		fr_event_status_cb_t	callback,
		void *	uctx
	)

Delete a pre-event callback from the event list.

Parameters

[in]	el	Containing the timer events.
[in]	callback	The pre-processing callback.
[in]	uctx	for the callback.

Returns

< 0 on error
0 on success

Definition at line 2274 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_pre_insert()

int fr_event_pre_insert	(	fr_event_list_t *	el,
		fr_event_status_cb_t	callback,
		void *	uctx
	)

Add a pre-event callback to the event list.

Events are serviced in insert order. i.e. insert A, B, we then have A running before B.

Parameters

[in]	el	Containing the timer events.
[in]	callback	The pre-processing callback.
[in]	uctx	for the callback.

Returns

< 0 on error
0 on success

Definition at line 2252 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_service()

void fr_event_service ( fr_event_list_t * el )

Service any outstanding timer or file descriptor events.

Parameters

[in] el containing events to service.

Definition at line 2542 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_timer_delete()

int fr_event_timer_delete ( fr_event_timer_t const ** ev_p )

Delete a timer event from the event list.

Parameters

[in] ev_p of the event being deleted.

Returns

0 on success.
-1 on failure.

Definition at line 1604 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_timer_run()

int fr_event_timer_run	(	fr_event_list_t *	el,
		fr_time_t *	when
	)

Run a single scheduled timer event.

Parameters

[in]	el	containing the timer events.
[in]	when	Process events scheduled to run before or at this time.

Returns

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

Definition at line 2356 of file event.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_event_timer_when()

fr_time_t fr_event_timer_when ( fr_event_timer_t const * ev )

Internal timestamp representing when the timer should fire.

Returns: When the timestamp should fire.

Definition at line 1626 of file event.c.

Here is the caller graph for this function:

◆ fr_event_user_delete()

int fr_event_user_delete	(	fr_event_list_t *	el,
		fr_event_user_cb_t	user,
		void *	uctx
	)

◆ fr_event_user_trigger()

int fr_event_user_trigger	(	fr_event_list_t *	el,
		fr_event_user_t *	ev
	)

Trigger a user event.

Parameters

[in]	el	containing the user event.
[in]	ev	Handle for the user event.

Returns

0 on success.
-1 on error.

Definition at line 2226 of file event.c.

Here is the call graph for this function:

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ fr_event_funcs_t

◆ fr_event_io_func_t

◆ fr_event_update_t

◆ fr_event_vnode_func_t

Macro Definition Documentation

◆ fr_event_fd_insert

◆ fr_event_fd_mode

◆ fr_event_filter_insert

◆ fr_event_filter_update

◆ fr_event_pid_reap

◆ fr_event_pid_wait

◆ FR_EVENT_RESUME

◆ FR_EVENT_SUSPEND

◆ fr_event_timer_at

◆ fr_event_timer_in

◆ fr_event_user_insert

Typedef Documentation

◆ fr_event_error_cb_t

◆ fr_event_fd_cb_t

◆ fr_event_fd_t

◆ fr_event_list_t

◆ fr_event_pid_cb_t

◆ fr_event_pid_t

◆ fr_event_status_cb_t

◆ fr_event_time_source_t

◆ fr_event_timer_cb_t

◆ fr_event_timer_t

◆ fr_event_user_cb_t

◆ fr_event_user_t

Enumeration Type Documentation

◆ fr_event_filter_t

◆ fr_event_op_t

Function Documentation

◆ _fr_event_fd_insert()

◆ _fr_event_fd_move()

◆ _fr_event_filter_insert()

◆ _fr_event_filter_update()

◆ _fr_event_pid_reap()

◆ _fr_event_pid_wait()

◆ _fr_event_timer_at()

◆ _fr_event_timer_in()

◆ _fr_event_user_insert()

◆ fr_event_corral()

◆ fr_event_fd_armour()

◆ fr_event_fd_cb()

◆ fr_event_fd_delete()

◆ fr_event_fd_handle()

◆ fr_event_fd_uctx()

◆ fr_event_fd_unarmour()

◆ fr_event_list_alloc()

◆ fr_event_list_empty()

◆ fr_event_list_kq()

◆ fr_event_list_num_fds()

◆ fr_event_list_num_timers()

◆ fr_event_list_reap_signal()

◆ fr_event_list_set_time_func()

◆ fr_event_list_time()

◆ fr_event_loop()

◆ fr_event_loop_exit()

◆ fr_event_loop_exiting()

◆ fr_event_post_delete()

◆ fr_event_post_insert()

◆ fr_event_pre_delete()

◆ fr_event_pre_insert()

◆ fr_event_service()

◆ fr_event_timer_delete()

◆ fr_event_timer_run()

◆ fr_event_timer_when()

◆ fr_event_user_delete()

◆ fr_event_user_trigger()