Simple state machine for managing connection states. More...

#include <freeradius-devel/util/event.h>
#include <freeradius-devel/util/table.h>
#include <freeradius-devel/util/talloc.h>

Include dependency graph for connection.h:

Go to the source code of this file.

Data Structures
struct	fr_connection_conf_t

struct	fr_connection_funcs_t
	Holds a complete set of functions for a connection. More...

struct	fr_connection_pub_s
	Public fields for the connection. More...

Macros
#define	_CONST const

Typedefs
typedef void(*	fr_connection_close_t) (fr_event_list_t el, void h, void *uctx)
	Notification that the connection has errored and must be closed. More...

typedef fr_connection_state_t(*	fr_connection_failed_t) (void h, fr_connection_state_t state, void uctx)
	Notification that a connection attempt has failed. More...

typedef fr_connection_state_t(*	fr_connection_init_t) (void *h_out, fr_connection_t conn, void *uctx)
	Callback for the initialise state. More...

typedef fr_connection_state_t(*	fr_connection_open_t) (fr_event_list_t el, void h, void *uctx)
	Notification that the connection is now open. More...

typedef fr_connection_state_t(*	fr_connection_shutdown_t) (fr_event_list_t el, void h, void *uctx)
	Start the process of gracefully shutting down the connection. More...

typedef struct fr_connection_pub_s	fr_connection_t

typedef struct fr_connection_watch_entry_s	fr_connection_watch_entry_t

typedef void(*	fr_connection_watch_t) (fr_connection_t conn, fr_connection_state_t prev, fr_connection_state_t state, void uctx)
	Receive a notification when a connection enters a particular state. More...

Enumerations
enum	fr_connection_reason_t { FR_CONNECTION_FAILED = 0 , FR_CONNECTION_EXPIRED }

enum	fr_connection_state_t { FR_CONNECTION_STATE_HALTED = 0 , FR_CONNECTION_STATE_INIT , FR_CONNECTION_STATE_CONNECTING , FR_CONNECTION_STATE_TIMEOUT , FR_CONNECTION_STATE_CONNECTED , FR_CONNECTION_STATE_SHUTDOWN , FR_CONNECTION_STATE_FAILED , FR_CONNECTION_STATE_CLOSED , FR_CONNECTION_STATE_MAX }

Variables
fr_table_num_ordered_t const	fr_connection_states []

size_t	fr_connection_states_len

Add watcher functions that get called before (pre) the state callback and after (post)
fr_connection_watch_entry_t *	fr_connection_add_watch_post (fr_connection_t conn, fr_connection_state_t state, fr_connection_watch_t watch, bool oneshot, void const uctx)
	Add a callback to be executed after a state function has been called. More...

fr_connection_watch_entry_t *	fr_connection_add_watch_pre (fr_connection_t conn, fr_connection_state_t state, fr_connection_watch_t watch, bool oneshot, void const uctx)
	Add a callback to be executed before a state function has been called. More...

int	fr_connection_del_watch_post (fr_connection_t *conn, fr_connection_state_t state, fr_connection_watch_t watch)
	Remove a watch function from a post list. More...

int	fr_connection_del_watch_pre (fr_connection_t *conn, fr_connection_state_t state, fr_connection_watch_t watch)
	Remove a watch function from a pre list. More...

void	fr_connection_watch_disable (fr_connection_watch_entry_t *entry)
	Disable a watcher. More...

void	fr_connection_watch_enable (fr_connection_watch_entry_t *entry)
	Enable a watcher. More...

void	fr_connection_watch_enable_set_uctx (fr_connection_watch_entry_t entry, void const uctx)
	Enable a watcher and replace the uctx. More...

bool	fr_connection_watch_is_enabled (fr_connection_watch_entry_t *entry)
	Return the state of a watch entry. More...

void	fr_connection_watch_set_uctx (fr_connection_watch_entry_t entry, void const uctx)
	Change the uctx of an entry. More...

Statistics
uint64_t	fr_connection_get_num_reconnected (fr_connection_t const *conn)
	Return the number of times we've attempted to establish or re-establish this connection. More...

uint64_t	fr_connection_get_num_timed_out (fr_connection_t const *conn)
	Return the number of times this connection has timed out whilst connecting. More...

Signal the connection to change states
void	fr_connection_signal_connected (fr_connection_t *conn)
	Asynchronously signal that the connection is open. More...

void	fr_connection_signal_halt (fr_connection_t *conn)
	Shuts down a connection ungracefully. More...

void	fr_connection_signal_init (fr_connection_t *conn)
	Asynchronously signal a halted connection to start. More...

void	fr_connection_signal_reconnect (fr_connection_t *conn, fr_connection_reason_t reason)
	Asynchronously signal the connection should be reconnected. More...

void	fr_connection_signal_shutdown (fr_connection_t *conn)
	Shuts down a connection gracefully. More...

void	fr_connection_signals_pause (fr_connection_t *conn)
	Pause processing of deferred signals. More...

void	fr_connection_signals_resume (fr_connection_t *conn)
	Resume processing of deferred signals. More...

Install generic I/O events on an FD to signal state changes
int	fr_connection_signal_on_fd (fr_connection_t *conn, int fd)
	Setup the connection to change states to connected or failed based on I/O events. More...

Allocate a new connection
fr_connection_t *	fr_connection_alloc (TALLOC_CTX ctx, fr_event_list_t el, fr_connection_funcs_t const funcs, fr_connection_conf_t const conf, char const log_prefix, void const uctx)
	Allocate a new connection. More...

Detailed Description

Simple state machine for managing connection states.

Id: 6b671eabf4f042e0d23377fd0dbf8c9b12d52646

Copyright: 2017-2020 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 connection.h.

Data Structure Documentation

◆ fr_connection_conf_t

struct fr_connection_conf_t

Definition at line 91 of file connection.h.

Collaboration diagram for fr_connection_conf_t:

Data Fields
fr_time_delta_t	connection_timeout	How long to wait for the connection to open or for shutdown to close the connection.
fr_time_delta_t	reconnection_delay	How long to wait after failures.

◆ fr_connection_funcs_t

struct fr_connection_funcs_t

Holds a complete set of functions for a connection.

Definition at line 186 of file connection.h.

Collaboration diagram for fr_connection_funcs_t:

Data Fields
fr_connection_close_t	close
fr_connection_failed_t	failed
fr_connection_init_t	init
fr_connection_open_t	open
fr_connection_shutdown_t	shutdown

◆ fr_connection_pub_s

struct fr_connection_pub_s

Public fields for the connection.

This saves the overhead of using accessors for commonly used fields in connections.

Though these fields are public, they should NOT be modified by clients of the connection API.

Definition at line 67 of file connection.h.

Collaboration diagram for fr_connection_pub_s:

Data Fields
fr_event_list_t *_CONST	el	Event list for timers and I/O events.
void *_CONST	h	Connection handle.
uint64_t _CONST	id	Unique identifier for the connection.
char const *_CONST	name	Prefix to add to log messages.
fr_connection_state_t _CONST	prev	The previous state the connection was in.
uint64_t _CONST	reconnected	How many times we've attempted to establish or re-establish this connection.
fr_connection_state_t _CONST	state	Current connection state.
uint64_t _CONST	timed_out	How many times has this connection timed out when connecting.
bool _CONST	triggers	do we run the triggers?

Macro Definition Documentation

◆ _CONST

#define _CONST const

Definition at line 40 of file connection.h.

Typedef Documentation

◆ fr_connection_close_t

typedef void(* fr_connection_close_t) (fr_event_list_t *el, void *h, void *uctx)

Notification that the connection has errored and must be closed.

This should be used to close the file descriptor. It is assumed that the file descriptor is invalid after this callback has been executed.

If this callback does not close the file descriptor, the server will leak file descriptors.

Parameters

[in]	el	to use for inserting I/O events.
[in]	h	Handle to close.
[in]	uctx	User context.

Definition at line 181 of file connection.h.

◆ fr_connection_failed_t

typedef fr_connection_state_t(* fr_connection_failed_t) (void *h, fr_connection_state_t state, void *uctx)

Notification that a connection attempt has failed.

Note: If the callback frees the connection, it must return FR_CONNECTION_STATE_HALTED.

Parameters

[in]	h	Handle that failed.
[in]	state	the connection was in when it failed. Usually one of: FR_CONNECTION_STATE_CONNECTING the connection attempt explicitly failed. FR_CONNECTION_STATE_CONNECTED something called fr_connection_signal_reconnect. FR_CONNECTION_STATE_TIMEOUT the connection attempt timed out.
[in]	uctx	User context.

Returns

FR_CONNECTION_STATE_INIT to transition to the init state.
FR_CONNECTION_STATE_HALTED To prevent further reconnection attempts Can be restarted with fr_connection_signal_init().

Definition at line 167 of file connection.h.

◆ fr_connection_init_t

typedef fr_connection_state_t(* fr_connection_init_t) (void **h_out, fr_connection_t *conn, void *uctx)

Callback for the initialise state.

Should attempt to open a non-blocking connection and return it in fd_out.

Parameters

[out]	h_out	Where to write the new handle.
[in]	conn	If integrating with a 3rd party library that will trigger connection API state transitions, the connection should be passed as the uctx argument for library I/O callbacks.
[in]	uctx	User context.

Returns

FR_CONNECTION_STATE_CONNECTING if a handle was successfully created.
FR_CONNECTION_STATE_FAILED if we could not create a handle.

Definition at line 116 of file connection.h.

◆ fr_connection_open_t

typedef fr_connection_state_t(* fr_connection_open_t) (fr_event_list_t *el, void *h, void *uctx)

Notification that the connection is now open.

This should be used to add any additional I/O events for the file descriptor to call other code if it becomes readable or writable.

Parameters

[in]	el	to use for inserting I/O events.
[in]	h	Handle that was successfully opened.
[in]	uctx	User context.

Returns

FR_CONNECTION_STATE_CONNECTED if the handle is usable.
FR_CONNECTION_STATE_FAILED if the handle is unusable.

Definition at line 130 of file connection.h.

◆ fr_connection_shutdown_t

typedef fr_connection_state_t(* fr_connection_shutdown_t) (fr_event_list_t *el, void *h, void *uctx)

Start the process of gracefully shutting down the connection.

This function is called when the connection is signalled to gracefully disconnect. It should place the connection in a state where pending I/O operations complete, and buffers are flushed.

After all pending events are complete, the connection should be signalled that the handle is in the closed state.

Parameters

[in]	el	to use for inserting I/O events.
[in]	h	Handle that needs to be closed.
[in]	uctx	User context.

Returns

FR_CONNECTION_STATE_SHUTDOWN if the handle has shutdown.
FR_CONNECTION_STATE_FAILED if the handle is unusable, and we should just transition directly to failed.

Definition at line 149 of file connection.h.

◆ fr_connection_t

typedef struct fr_connection_pub_s fr_connection_t

Definition at line 1 of file connection.h.

◆ fr_connection_watch_entry_t

typedef struct fr_connection_watch_entry_s fr_connection_watch_entry_t

Definition at line 1 of file connection.h.

◆ fr_connection_watch_t

typedef void(* fr_connection_watch_t) (fr_connection_t *conn, fr_connection_state_t prev, fr_connection_state_t state, void *uctx)

Receive a notification when a connection enters a particular state.

It is permitted for watchers to signal state changes, and/or to free the connection. The actual free will be deferred until the watcher returns.

Parameters

[in]	conn	Being watched.
[in]	prev	State we came from.
[in]	state	State that was entered (the current state)
[in]	uctx	that was passed to fr_connection_add_watch_*.

Definition at line 204 of file connection.h.

Enumeration Type Documentation

◆ fr_connection_reason_t

enum fr_connection_reason_t

Enumerator

FR_CONNECTION_FAILED

Connection is being reconnected because it failed.

FR_CONNECTION_EXPIRED

Connection is being reconnected because it's at the end of its life.

In this case we enter the closing state and try and close the connection gracefully.

Definition at line 83 of file connection.h.

◆ fr_connection_state_t

enum fr_connection_state_t

Enumerator
FR_CONNECTION_STATE_HALTED	The connection is in a halted stat. It does not have a valid file descriptor, and it will not try and and create one.
FR_CONNECTION_STATE_INIT	Init state, sets up connection.
FR_CONNECTION_STATE_CONNECTING	Waiting for connection to establish.
FR_CONNECTION_STATE_TIMEOUT	Timeout during FR_CONNECTION_STATE_CONNECTING.
FR_CONNECTION_STATE_CONNECTED	File descriptor is open (ready for writing).
FR_CONNECTION_STATE_SHUTDOWN	Connection is shutting down.
FR_CONNECTION_STATE_FAILED	Connection has failed.
FR_CONNECTION_STATE_CLOSED	Connection has been closed.
FR_CONNECTION_STATE_MAX

Definition at line 45 of file connection.h.

Function Documentation

◆ fr_connection_add_watch_post()

fr_connection_watch_entry_t* fr_connection_add_watch_post	(	fr_connection_t *	conn,
		fr_connection_state_t	state,
		fr_connection_watch_t	watch,
		bool	oneshot,
		void const *	uctx
	)

Add a callback to be executed after a state function has been called.

Where a user callback is executed on state change, the post function is only called if the callback succeeds.

Parameters

[in]	conn	to add watcher to.
[in]	state	to call watcher on entering.
[in]	watch	function to call.
[in]	oneshot	If true, remove the function after calling.
[in]	uctx	to pass to callbacks.

Returns

NULL if state value is invalid.
A new watch entry handle.

Definition at line 531 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_add_watch_pre()

fr_connection_watch_entry_t* fr_connection_add_watch_pre	(	fr_connection_t *	conn,
		fr_connection_state_t	state,
		fr_connection_watch_t	watch,
		bool	oneshot,
		void const *	uctx
	)

Add a callback to be executed before a state function has been called.

Parameters

[in]	conn	to add watcher to.
[in]	state	to call watcher on entering.
[in]	watch	function to call.
[in]	oneshot	If true, remove the function after calling.
[in]	uctx	to pass to callbacks.

Returns

NULL if state value is invalid.
A new watch entry handle.

Definition at line 509 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_alloc()

fr_connection_t* fr_connection_alloc	(	TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		fr_connection_funcs_t const *	funcs,
		fr_connection_conf_t const *	conf,
		char const *	log_prefix,
		void const *	uctx
	)

Allocate a new connection.

After the connection has been allocated, it should be started with a call to fr_connection_signal_init.

The connection state machine can detect when the connection is open in one of two ways.

You can install a generic socket open/fail callback, using fr_connection_signal_on_fd.
You can call either fr_connection_signal_connected or fr_connection_signal_recommend. This allows the connection state machine to work with more difficult library APIs, which may not return control to the caller as connections are opened.

Parameters

[in]	ctx	to allocate connection handle in. If the connection handle is freed, and the fr_connection_state_t is FR_CONNECTION_STATE_CONNECTING or FR_CONNECTION_STATE_CONNECTED the close callback will be called.
[in]	el	to use for timer events, and to pass to the fr_connection_open_t callback.
[in]	funcs	callback functions.
[in]	conf	our configuration.
[in]	log_prefix	To prepend to log messages.
[in]	uctx	User context to pass to callbacks.

Returns

A new fr_connection_t on success.
NULL on failure.

Definition at line 1507 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_del_watch_post()

int fr_connection_del_watch_post	(	fr_connection_t *	conn,
		fr_connection_state_t	state,
		fr_connection_watch_t	watch
	)

Remove a watch function from a post list.

Parameters

[in]	conn	The connection to remove the watcher from.
[in]	state	to remove the watch from.
[in]	watch	Function to remove.

Returns

0 if the function was removed successfully.
-1 if the function wasn't present in the watch list.
-2 an invalid state was passed.

Definition at line 471 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_del_watch_pre()

int fr_connection_del_watch_pre	(	fr_connection_t *	conn,
		fr_connection_state_t	state,
		fr_connection_watch_t	watch
	)

Remove a watch function from a pre list.

Parameters

[in]	conn	The connection to remove the watcher from.
[in]	state	to remove the watch from.
[in]	watch	Function to remove.

Returns

0 if the function was removed successfully.
-1 if the function wasn't present in the watch list.
-2 an invalid state was passed.

Definition at line 454 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_get_num_reconnected()

uint64_t fr_connection_get_num_reconnected ( fr_connection_t const * conn )

Return the number of times we've attempted to establish or re-establish this connection.

Parameters

[in] conn to get count from.

Returns: the number of times the connection has reconnected.

Definition at line 600 of file connection.c.

Here is the caller graph for this function:

◆ fr_connection_get_num_timed_out()

uint64_t fr_connection_get_num_timed_out ( fr_connection_t const * conn )

Return the number of times this connection has timed out whilst connecting.

Parameters

[in] conn to get count from.

Returns: the number of times the connection has timed out whilst connecting.

Definition at line 612 of file connection.c.

Here is the caller graph for this function:

◆ fr_connection_signal_connected()

void fr_connection_signal_connected ( fr_connection_t * conn )

Asynchronously signal that the connection is open.

Some libraries like libldap are extremely annoying and only return control to the caller after a connection is open.

For these libraries, we can't use an I/O handler to determine when the connection is open so we rely on callbacks built into the library to signal that the transition has occurred.

Definition at line 1136 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_signal_halt()

void fr_connection_signal_halt ( fr_connection_t * conn )

Shuts down a connection ungracefully.

If a connection is in an open or connection state it will be closed immediately. Otherwise the connection will transition directly to the halted state.

Parameters

[in] conn to halt.

Definition at line 1290 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_signal_init()

void fr_connection_signal_init ( fr_connection_t * conn )

Asynchronously signal a halted connection to start.

Definition at line 1106 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_signal_on_fd()

int fr_connection_signal_on_fd	(	fr_connection_t *	conn,
		int	fd
	)

Setup the connection to change states to connected or failed based on I/O events.

Will automatically cleanup after itself, in preparation for new I/O handlers to be installed in the open() callback.

Returns

0 on success.
-1 on failure.

Definition at line 1400 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_signal_reconnect()

void fr_connection_signal_reconnect	(	fr_connection_t *	conn,
		fr_connection_reason_t	reason
	)

Asynchronously signal the connection should be reconnected.

Should be called if the caller has knowledge that the connection is bad and should be reconnected.

Parameters

[in]	conn	to reconnect.
[in]	reason	Why the connection was signalled to reconnect.

Definition at line 1166 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_signal_shutdown()

void fr_connection_signal_shutdown ( fr_connection_t * conn )

Shuts down a connection gracefully.

If a shutdown function has been provided, it is called. It's then up to the shutdown function to install I/O handlers to signal when the connection has finished shutting down and should be closed via fr_connection_signal_halt.

Parameters

[in] conn to shutdown.

Definition at line 1227 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_signals_pause()

void fr_connection_signals_pause ( fr_connection_t * conn )

Pause processing of deferred signals.

Parameters

[in] conn to pause signal processing for.

Definition at line 310 of file connection.c.

Here is the caller graph for this function:

◆ fr_connection_signals_resume()

void fr_connection_signals_resume ( fr_connection_t * conn )

Resume processing of deferred signals.

Parameters

[in] conn to resume signal processing for.

Definition at line 319 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_connection_watch_disable()

void fr_connection_watch_disable ( fr_connection_watch_entry_t * entry )

Disable a watcher.

Parameters

[in] entry to disable.

Definition at line 553 of file connection.c.

Here is the caller graph for this function:

◆ fr_connection_watch_enable()

void fr_connection_watch_enable ( fr_connection_watch_entry_t * entry )

Enable a watcher.

Parameters

[in] entry to enabled.

Definition at line 543 of file connection.c.

◆ fr_connection_watch_enable_set_uctx()

void fr_connection_watch_enable_set_uctx	(	fr_connection_watch_entry_t *	entry,
		void const *	uctx
	)

Enable a watcher and replace the uctx.

Parameters

[in]	entry	to enabled.
[in]	uctx	Opaque data to pass to the callback.

Definition at line 564 of file connection.c.

Here is the caller graph for this function:

◆ fr_connection_watch_is_enabled()

bool fr_connection_watch_is_enabled ( fr_connection_watch_entry_t * entry )

Return the state of a watch entry.

Parameters

[in] entry to return state of.

Returns

true if enabled.
false if disabled.

Definition at line 589 of file connection.c.

◆ fr_connection_watch_set_uctx()

void fr_connection_watch_set_uctx	(	fr_connection_watch_entry_t *	entry,
		void const *	uctx
	)

Change the uctx of an entry.

Parameters

[in]	entry	to enabled.
[in]	uctx	Opaque data to pass to the callback.

Definition at line 576 of file connection.c.

Variable Documentation

◆ fr_connection_states

fr_table_num_ordered_t const fr_connection_states[]

extern

Definition at line 46 of file connection.c.

◆ fr_connection_states_len

size_t fr_connection_states_len

extern

Definition at line 56 of file connection.c.

Data Structures

Macros

Typedefs

Enumerations

Variables

Add watcher functions that get called before (pre) the state callback and after (post)

Statistics

Signal the connection to change states

Install generic I/O events on an FD to signal state changes

Allocate a new connection

Detailed Description

Data Structure Documentation

◆ fr_connection_conf_t

◆ fr_connection_funcs_t

◆ fr_connection_pub_s

Macro Definition Documentation

◆ _CONST

Typedef Documentation

◆ fr_connection_close_t

◆ fr_connection_failed_t

◆ fr_connection_init_t

◆ fr_connection_open_t

◆ fr_connection_shutdown_t

◆ fr_connection_t

◆ fr_connection_watch_entry_t

◆ fr_connection_watch_t

Enumeration Type Documentation

◆ fr_connection_reason_t

◆ fr_connection_state_t

Function Documentation

◆ fr_connection_add_watch_post()

◆ fr_connection_add_watch_pre()

◆ fr_connection_alloc()

◆ fr_connection_del_watch_post()

◆ fr_connection_del_watch_pre()

◆ fr_connection_get_num_reconnected()

◆ fr_connection_get_num_timed_out()

◆ fr_connection_signal_connected()

◆ fr_connection_signal_halt()

◆ fr_connection_signal_init()

◆ fr_connection_signal_on_fd()

◆ fr_connection_signal_reconnect()

◆ fr_connection_signal_shutdown()

◆ fr_connection_signals_pause()

◆ fr_connection_signals_resume()

◆ fr_connection_watch_disable()

◆ fr_connection_watch_enable()

◆ fr_connection_watch_enable_set_uctx()

◆ fr_connection_watch_is_enabled()

◆ fr_connection_watch_set_uctx()

Variable Documentation

◆ fr_connection_states

◆ fr_connection_states_len