API to manage pools of persistent connections to external resources. More...

#include <freeradius-devel/server/stats.h>

Include dependency graph for pool.h:

Data Structures
struct	fr_pool_state_s

Typedefs
typedef int(*	fr_pool_connection_alive_t) (void opaque, void connection)
	Check a connection handle is still viable. More...

typedef void (	fr_pool_connection_create_t) (TALLOC_CTX ctx, void opaque, fr_time_delta_t timeout)
	Create a new connection handle. More...

typedef void(*	fr_pool_reconnect_t) (fr_pool_t pool, void opaque)
	Alter the opaque data of a connection pool during reconnection event. More...

typedef struct fr_pool_state_s	fr_pool_state_t

typedef struct fr_pool_s	fr_pool_t

Functions
int	fr_pool_connection_close (fr_pool_t pool, request_t request, CC_RELEASE_HANDLE("conn_pool_handle") void *conn)

void *	fr_pool_connection_get (fr_pool_t pool, request_t request)
	Reserve a connection in the connection pool. More...

void *	fr_pool_connection_reconnect (fr_pool_t pool, request_t request, CC_RELEASE_HANDLE("conn_pool_handle") void *conn)

void	fr_pool_connection_release (fr_pool_t pool, request_t request, CC_RELEASE_HANDLE("conn_pool_handle") void *conn)

fr_pool_t *	fr_pool_copy (TALLOC_CTX ctx, fr_pool_t pool, void *opaque)
	Allocate a new pool using an existing one as a template. More...

void	fr_pool_enable_triggers (fr_pool_t pool, char const trigger_prefix, fr_pair_list_t *trigger_args)
	Enable triggers for a connection pool. More...

void	fr_pool_free (fr_pool_t *pool)
	Delete a connection pool. More...

fr_pool_t *	fr_pool_init (TALLOC_CTX ctx, CONF_SECTION const cs, void opaque, fr_pool_connection_create_t c, fr_pool_connection_alive_t a, char const log_prefix)
	Create a new connection pool. More...

void const *	fr_pool_opaque (fr_pool_t *pool)
	Return the opaque data associated with a connection pool. More...

int	fr_pool_reconnect (fr_pool_t pool, request_t request)
	Mark connections for reconnection, and spawn at least 'start' connections. More...

void	fr_pool_reconnect_func (fr_pool_t *pool, fr_pool_reconnect_t reconnect)
	Set a reconnection callback for the connection pool. More...

void	fr_pool_ref (fr_pool_t *pool)
	Increment pool reference by one. More...

int	fr_pool_start (fr_pool_t *pool)

int	fr_pool_start_num (fr_pool_t *pool)
	Connection pool get start. More...

fr_pool_state_t const *	fr_pool_state (fr_pool_t *pool)
	Get the number of connections currently in the pool. More...

fr_time_delta_t	fr_pool_timeout (fr_pool_t *pool)
	Connection pool get timeout. More...

Detailed Description

API to manage pools of persistent connections to external resources.

Id: 7f02e5682a89ad8d15be72afd8331064df14611d

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

Definition in file pool.h.

Data Structure Documentation

◆ fr_pool_state_s

struct fr_pool_state_s

Definition at line 46 of file pool.h.

Collaboration diagram for fr_pool_state_s:

Data Fields
uint32_t	active	Number of currently reserved connections.
uint64_t	count	Number of connections spawned over the lifetime of the pool.
fr_time_t	last_at_max	Last time we hit the maximum number of allowed connections.
fr_time_t	last_checked	Last time we pruned the connection pool.
fr_time_t	last_closed	Last time a connection was closed.
fr_time_t	last_failed	Last time we tried to spawn a connection but failed.
fr_time_t	last_held_max	Last time we warned about a high latency event.
fr_time_t	last_held_min	Last time we warned about a low latency event.
fr_time_t	last_released	Last time a connection was released.
fr_time_t	last_spawned	Last time we spawned a connection.
fr_time_t	last_throttled	Last time we refused to spawn a connection because the last connection failed, or we were already spawning a connection.
fr_time_delta_t	next_delay	The next delay time. cleanup. Initialized to cleanup_interval, and decays from there.
uint32_t	num	Number of connections in the pool.
uint32_t	pending	Number of pending open connections.
bool	reconnecting	We are currently reconnecting the pool.

Typedef Documentation

◆ fr_pool_connection_alive_t

typedef int(* fr_pool_connection_alive_t) (void *opaque, void *connection)

Check a connection handle is still viable.

Should check the state of a connection handle.

Note: NULL may be passed to fr_pool_init, if there is no way to check the state of a connection handle.; Not currently use by connection pool manager.

Parameters

[in]	opaque	pointer passed to fr_pool_init.
[in]	connection	handle returned by fr_pool_connection_create_t.

Returns

0 on success.
< 0 on error or if the connection is unusable.

Definition at line 126 of file pool.h.

◆ fr_pool_connection_create_t

typedef void*(* fr_pool_connection_create_t) (TALLOC_CTX *ctx, void *opaque, fr_time_delta_t timeout)

Create a new connection handle.

This function will be called whenever the connection pool manager needs to spawn a new connection, and on reconnect.

Memory should be talloced in the provided context to hold the module's connection structure. The context is allocated in the NULL context, but will be freed when fr_pool_t is freed via some internal magic.

There is no delete callback, so operations such as closing sockets and freeing library connection handles should be done by a destructor attached to memory allocated beneath the provided ctx.

Note: A function pointer matching this prototype must be passed to fr_pool_init.

Parameters

[in,out]	ctx	to allocate memory in.
[in]	opaque	pointer passed to fr_pool_init.
[in]	timeout	The maximum time in ms the function has to complete the connection. Should be enforced by the function.

Returns

NULL on error.
A connection handle on success.

Definition at line 111 of file pool.h.

◆ fr_pool_reconnect_t

typedef void(* fr_pool_reconnect_t) (fr_pool_t *pool, void *opaque)

Alter the opaque data of a connection pool during reconnection event.

This function will be called whenever we have been signalled to reconnect all the connections in a pool.

It is called at a point where we have determined that no connection spawning is in progress, so it is safe to modify any pointers or memory associated with the opaque data.

Parameters

[in]	pool	being reconnected.
[in]	opaque	pointer passed to fr_pool_init.

Definition at line 85 of file pool.h.

◆ fr_pool_state_t

typedef struct fr_pool_state_s fr_pool_state_t

Definition at line 1 of file pool.h.

◆ fr_pool_t

typedef struct fr_pool_s fr_pool_t

Definition at line 1 of file pool.h.

Function Documentation

◆ fr_pool_connection_close()

int fr_pool_connection_close	(	fr_pool_t *	pool,
		request_t *	request,
		CC_RELEASE_HANDLE("conn_pool_handle") void *	conn
	)

◆ fr_pool_connection_get()

void* fr_pool_connection_get	(	fr_pool_t *	pool,
		request_t *	request
	)

Reserve a connection in the connection pool.

Will attempt to find an unused connection in the connection pool, if one is found, will mark it as in in use increment the number of active connections and return the connection handle.

If no free connections are found will attempt to spawn a new one, conditional on a connection spawning not already being in progress, and not being at the 'max' connection limit.

Note: fr_pool_connection_release must be called once the caller has finished using the connection.

See also: fr_pool_connection_release

Parameters

[in]	pool	to reserve the connection from.
[in]	request	The current request.

Returns

A pointer to the connection handle.
NULL on error.

Definition at line 1392 of file pool.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_pool_connection_reconnect()

void* fr_pool_connection_reconnect	(	fr_pool_t *	pool,
		request_t *	request,
		CC_RELEASE_HANDLE("conn_pool_handle") void *	conn
	)

◆ fr_pool_connection_release()

void fr_pool_connection_release	(	fr_pool_t *	pool,
		request_t *	request,
		CC_RELEASE_HANDLE("conn_pool_handle") void *	conn
	)

◆ fr_pool_copy()

fr_pool_t* fr_pool_copy	(	TALLOC_CTX *	ctx,
		fr_pool_t *	pool,
		void *	opaque
	)

Allocate a new pool using an existing one as a template.

Parameters

[in]	ctx	to allocate new pool in.
[in]	pool	to copy.
[in]	opaque	data to pass to connection function.

Returns

New connection pool.
NULL on error.

Definition at line 1156 of file pool.c.

Here is the call graph for this function:

◆ fr_pool_enable_triggers()

void fr_pool_enable_triggers	(	fr_pool_t *	pool,
		char const *	trigger_prefix,
		fr_pair_list_t *	trigger_args
	)

Enable triggers for a connection pool.

Parameters

[in] pool to enable triggers for.

[in]

trigger_prefix

prefix to prepend to all trigger names. Usually a path to the module's trigger configuration .e.g.

modules.<name>.pool

<trigger name>

is appended to form the complete path.

[in] trigger_args to make available in any triggers executed by the connection pool. These will usually be fr_pair_t (s) describing the host associated with the pool. Trigger args will be copied, input trigger_args should be freed if necessary.

Definition at line 933 of file pool.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_pool_free()

void fr_pool_free ( fr_pool_t * pool )

Delete a connection pool.

Closes, unlinks and frees all connections in the connection pool, then frees all memory used by the connection pool.

Note: Will call the 'stop' trigger.; Must be called with the mutex free.

Parameters

[in,out] pool to delete.

Definition at line 1329 of file pool.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_pool_init()

fr_pool_t* fr_pool_init	(	TALLOC_CTX *	ctx,
		CONF_SECTION const *	cs,
		void *	opaque,
		fr_pool_connection_create_t	c,
		fr_pool_connection_alive_t	a,
		char const *	log_prefix
	)

Create a new connection pool.

Allocates structures used by the connection pool, initialises the various configuration options and counters, and sets the callback functions.

Will also spawn the number of connections specified by the 'start' configuration option.

Note: Will call the 'start' trigger.

Parameters

[in]	ctx	Context to link pool's destruction to.
[in]	cs	pool section.
[in]	opaque	data pointer to pass to callbacks.
[in]	c	Callback to create new connections.
[in]	a	Callback to check the status of connections.
[in]	log_prefix	prefix to prepend to all log messages.

Returns

New connection pool.
NULL on error.

Definition at line 967 of file pool.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_pool_opaque()

void const* fr_pool_opaque ( fr_pool_t * pool )

Return the opaque data associated with a connection pool.

Parameters

pool	to return data for.

Returns: opaque data associated with pool.

Definition at line 1203 of file pool.c.

◆ fr_pool_reconnect()

int fr_pool_reconnect	(	fr_pool_t *	pool,
		request_t *	request
	)

Mark connections for reconnection, and spawn at least 'start' connections.

Note: This call may block whilst waiting for pending connection attempts to complete.

This intended to be called on a connection pool that's in use, to have it reflect a configuration change, or because the administrator knows that all connections in the pool are inviable and need to be reconnected.

Parameters

[in]	pool	to reconnect.
[in]	request	The current request.

Returns

0 On success.
-1 If we couldn't create start connections, this may be ignored depending on the context in which this function is being called.

Definition at line 1244 of file pool.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_pool_reconnect_func()

void fr_pool_reconnect_func	(	fr_pool_t *	pool,
		fr_pool_reconnect_t	reconnect
	)

Set a reconnection callback for the connection pool.

This can be called at any time during the pool's lifecycle.

Parameters

[in]	pool	to set reconnect callback for.
	reconnect	callback to call when reconnecting pool's connections.

Definition at line 1224 of file pool.c.

Here is the caller graph for this function:

◆ fr_pool_ref()

void fr_pool_ref ( fr_pool_t * pool )

Increment pool reference by one.

Parameters

[in] pool to increment reference counter for.

Definition at line 1212 of file pool.c.

Here is the caller graph for this function:

◆ fr_pool_start()

int fr_pool_start ( fr_pool_t * pool )

Definition at line 1116 of file pool.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_pool_start_num()

int fr_pool_start_num ( fr_pool_t * pool )

Connection pool get start.

Parameters

[in] pool to get connection start for.

Returns: the connection start value configured for the pool.

Definition at line 1193 of file pool.c.

Here is the caller graph for this function:

◆ fr_pool_state()

fr_pool_state_t const* fr_pool_state ( fr_pool_t * pool )

Get the number of connections currently in the pool.

Parameters

[in] pool to count connections for.

Returns: the number of connections in the pool

Definition at line 1173 of file pool.c.

Here is the caller graph for this function:

◆ fr_pool_timeout()

fr_time_delta_t fr_pool_timeout ( fr_pool_t * pool )

Connection pool get timeout.

Parameters

[in] pool to get connection timeout for.

Returns: the connection timeout configured for the pool.

Definition at line 1183 of file pool.c.

Data Structures

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ fr_pool_state_s

Typedef Documentation

◆ fr_pool_connection_alive_t

◆ fr_pool_connection_create_t

◆ fr_pool_reconnect_t

◆ fr_pool_state_t

◆ fr_pool_t

Function Documentation

◆ fr_pool_connection_close()

◆ fr_pool_connection_get()

◆ fr_pool_connection_reconnect()

◆ fr_pool_connection_release()

◆ fr_pool_copy()

◆ fr_pool_enable_triggers()

◆ fr_pool_free()

◆ fr_pool_init()

◆ fr_pool_opaque()

◆ fr_pool_reconnect()

◆ fr_pool_reconnect_func()

◆ fr_pool_ref()

◆ fr_pool_start()

◆ fr_pool_start_num()

◆ fr_pool_state()

◆ fr_pool_timeout()