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	connection_conf_t

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

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

Macros
#define	_CONST const

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

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

typedef connection_state_t(*	connection_init_t) (void *h_out, connection_t conn, void *uctx)
	Callback for the initialise state. More...

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

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

typedef struct connection_pub_s	connection_t

typedef struct connection_watch_entry_s	connection_watch_entry_t

typedef void(*	connection_watch_t) (connection_t conn, connection_state_t prev, connection_state_t state, void uctx)
	Receive a notification when a connection enters a particular state. More...

Enumerations
enum	connection_reason_t { CONNECTION_FAILED = 0 , CONNECTION_EXPIRED }

enum	connection_state_t { CONNECTION_STATE_HALTED = 0 , CONNECTION_STATE_INIT , CONNECTION_STATE_CONNECTING , CONNECTION_STATE_TIMEOUT , CONNECTION_STATE_CONNECTED , CONNECTION_STATE_SHUTDOWN , CONNECTION_STATE_FAILED , CONNECTION_STATE_CLOSED , CONNECTION_STATE_MAX }

Variables
fr_table_num_ordered_t const	connection_states []

size_t	connection_states_len

Add watcher functions that get called before (pre) the state callback and after (post)
connection_watch_entry_t *	connection_add_watch_post (connection_t conn, connection_state_t state, connection_watch_t watch, bool oneshot, void const uctx)
	Add a callback to be executed after a state function has been called. More...

connection_watch_entry_t *	connection_add_watch_pre (connection_t conn, connection_state_t state, connection_watch_t watch, bool oneshot, void const uctx)
	Add a callback to be executed before a state function has been called. More...

int	connection_del_watch_post (connection_t *conn, connection_state_t state, connection_watch_t watch)
	Remove a watch function from a post list. More...

int	connection_del_watch_pre (connection_t *conn, connection_state_t state, connection_watch_t watch)
	Remove a watch function from a pre list. More...

void	connection_watch_disable (connection_watch_entry_t *entry)
	Disable a watcher. More...

void	connection_watch_enable (connection_watch_entry_t *entry)
	Enable a watcher. More...

void	connection_watch_enable_set_uctx (connection_watch_entry_t entry, void const uctx)
	Enable a watcher and replace the uctx. More...

bool	connection_watch_is_enabled (connection_watch_entry_t *entry)
	Return the state of a watch entry. More...

void	connection_watch_set_uctx (connection_watch_entry_t entry, void const uctx)
	Change the uctx of an entry. More...

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

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

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

void	connection_signal_halt (connection_t *conn)
	Shuts down a connection ungracefully. More...

void	connection_signal_init (connection_t *conn)
	Asynchronously signal a halted connection to start. More...

void	connection_signal_reconnect (connection_t *conn, connection_reason_t reason)
	Asynchronously signal the connection should be reconnected. More...

void	connection_signal_shutdown (connection_t *conn)
	Shuts down a connection gracefully. More...

void	connection_signals_pause (connection_t *conn)
	Pause processing of deferred signals. More...

void	connection_signals_resume (connection_t *conn)
	Resume processing of deferred signals. More...

Install generic I/O events on an FD to signal state changes
int	connection_signal_on_fd (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
connection_t *	connection_alloc (TALLOC_CTX ctx, fr_event_list_t el, connection_funcs_t const funcs, 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: 524f5d1ca431424c85351c91d0ea390f4a54e23f

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

◆ connection_conf_t

struct connection_conf_t

Definition at line 91 of file connection.h.

Collaboration diagram for 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.

◆ connection_funcs_t

struct connection_funcs_t

Holds a complete set of functions for a connection.

Definition at line 186 of file connection.h.

Collaboration diagram for connection_funcs_t:

Data Fields
connection_close_t	close
connection_failed_t	failed
connection_init_t	init
connection_open_t	open
connection_shutdown_t	shutdown

◆ connection_pub_s

struct 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 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.
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.
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

◆ connection_close_t

typedef void(* 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.

◆ connection_failed_t

typedef connection_state_t(* connection_failed_t) (void *h, connection_state_t state, void *uctx)

Notification that a connection attempt has failed.

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

Parameters

[in]	h	Handle that failed.
[in]	state	the connection was in when it failed. Usually one of: CONNECTION_STATE_CONNECTING the connection attempt explicitly failed. CONNECTION_STATE_CONNECTED something called connection_signal_reconnect. CONNECTION_STATE_TIMEOUT the connection attempt timed out.
[in]	uctx	User context.

Returns

CONNECTION_STATE_INIT to transition to the init state.
CONNECTION_STATE_HALTED To prevent further reconnection attempts Can be restarted with connection_signal_init().

Definition at line 167 of file connection.h.

◆ connection_init_t

typedef connection_state_t(* connection_init_t) (void **h_out, 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

CONNECTION_STATE_CONNECTING if a handle was successfully created.
CONNECTION_STATE_FAILED if we could not create a handle.

Definition at line 116 of file connection.h.

◆ connection_open_t

typedef connection_state_t(* 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

CONNECTION_STATE_CONNECTED if the handle is usable.
CONNECTION_STATE_FAILED if the handle is unusable.

Definition at line 130 of file connection.h.

◆ connection_shutdown_t

typedef connection_state_t(* 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

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

Definition at line 149 of file connection.h.

◆ connection_t

typedef struct connection_pub_s connection_t

Definition at line 1 of file connection.h.

◆ connection_watch_entry_t

typedef struct connection_watch_entry_s connection_watch_entry_t

Definition at line 1 of file connection.h.

◆ connection_watch_t

typedef void(* connection_watch_t) (connection_t *conn, connection_state_t prev, 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 connection_add_watch_*.

Definition at line 204 of file connection.h.

Enumeration Type Documentation

◆ connection_reason_t

enum connection_reason_t

Enumerator

CONNECTION_FAILED

Connection is being reconnected because it failed.

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.

◆ connection_state_t

enum connection_state_t

Enumerator
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.
CONNECTION_STATE_INIT	Init state, sets up connection.
CONNECTION_STATE_CONNECTING	Waiting for connection to establish.
CONNECTION_STATE_TIMEOUT	Timeout during CONNECTION_STATE_CONNECTING.
CONNECTION_STATE_CONNECTED	File descriptor is open (ready for writing).
CONNECTION_STATE_SHUTDOWN	Connection is shutting down.
CONNECTION_STATE_FAILED	Connection has failed.
CONNECTION_STATE_CLOSED	Connection has been closed.
CONNECTION_STATE_MAX

Definition at line 45 of file connection.h.

Function Documentation

◆ connection_add_watch_post()

connection_watch_entry_t* connection_add_watch_post	(	connection_t *	conn,
		connection_state_t	state,
		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 532 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_add_watch_pre()

connection_watch_entry_t* connection_add_watch_pre	(	connection_t *	conn,
		connection_state_t	state,
		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 510 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_alloc()

connection_t* connection_alloc	(	TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		connection_funcs_t const *	funcs,
		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 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 connection_signal_on_fd.
You can call either connection_signal_connected or 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 connection_state_t is CONNECTION_STATE_CONNECTING or CONNECTION_STATE_CONNECTED the close callback will be called.
[in]	el	to use for timer events, and to pass to the 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 connection_t on success.
NULL on failure.

Definition at line 1512 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_del_watch_post()

int connection_del_watch_post	(	connection_t *	conn,
		connection_state_t	state,
		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 472 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_del_watch_pre()

int connection_del_watch_pre	(	connection_t *	conn,
		connection_state_t	state,
		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 455 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_get_num_reconnected()

uint64_t connection_get_num_reconnected ( 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 601 of file connection.c.

Here is the caller graph for this function:

◆ connection_get_num_timed_out()

uint64_t connection_get_num_timed_out ( 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 613 of file connection.c.

Here is the caller graph for this function:

◆ connection_signal_connected()

void connection_signal_connected ( 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 1137 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_signal_halt()

void connection_signal_halt ( 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 1291 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_signal_init()

void connection_signal_init ( connection_t * conn )

Asynchronously signal a halted connection to start.

Definition at line 1107 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_signal_on_fd()

int connection_signal_on_fd	(	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 1405 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_signal_reconnect()

void connection_signal_reconnect	(	connection_t *	conn,
		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 1167 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_signal_shutdown()

void connection_signal_shutdown ( 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 connection_signal_halt.

Parameters

[in] conn to shutdown.

Definition at line 1228 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ connection_signals_pause()

void connection_signals_pause ( 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:

◆ connection_signals_resume()

void connection_signals_resume ( 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:

◆ connection_watch_disable()

void connection_watch_disable ( connection_watch_entry_t * entry )

Disable a watcher.

Parameters

[in] entry to disable.

Definition at line 554 of file connection.c.

Here is the caller graph for this function:

◆ connection_watch_enable()

void connection_watch_enable ( connection_watch_entry_t * entry )

Enable a watcher.

Parameters

[in] entry to enabled.

Definition at line 544 of file connection.c.

◆ connection_watch_enable_set_uctx()

void connection_watch_enable_set_uctx	(	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 565 of file connection.c.

Here is the caller graph for this function:

◆ connection_watch_is_enabled()

bool connection_watch_is_enabled ( 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 590 of file connection.c.

◆ connection_watch_set_uctx()

void connection_watch_set_uctx	(	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 577 of file connection.c.

Variable Documentation

◆ connection_states

fr_table_num_ordered_t const connection_states[]

extern

Definition at line 46 of file connection.c.

◆ connection_states_len

size_t 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

◆ connection_conf_t

◆ connection_funcs_t

◆ connection_pub_s

Macro Definition Documentation

◆ _CONST

Typedef Documentation

◆ connection_close_t

◆ connection_failed_t

◆ connection_init_t

◆ connection_open_t

◆ connection_shutdown_t

◆ connection_t

◆ connection_watch_entry_t

◆ connection_watch_t

Enumeration Type Documentation

◆ connection_reason_t

◆ connection_state_t

Function Documentation

◆ connection_add_watch_post()

◆ connection_add_watch_pre()

◆ connection_alloc()

◆ connection_del_watch_post()

◆ connection_del_watch_pre()

◆ connection_get_num_reconnected()

◆ connection_get_num_timed_out()

◆ connection_signal_connected()

◆ connection_signal_halt()

◆ connection_signal_init()

◆ connection_signal_on_fd()

◆ connection_signal_reconnect()

◆ connection_signal_shutdown()

◆ connection_signals_pause()

◆ connection_signals_resume()

◆ connection_watch_disable()

◆ connection_watch_enable()

◆ connection_watch_enable_set_uctx()

◆ connection_watch_is_enabled()

◆ connection_watch_set_uctx()

Variable Documentation

◆ connection_states

◆ connection_states_len