API to manage pools of persistent connections to external resources. More...
#include <freeradius-devel/conffile.h>
Go to the source code of this file.
Data Structures | |
struct | fr_connection_pool_state |
Typedefs | |
typedef int(* | fr_connection_alive_t )(void *opaque, void *connection) |
Check a connection handle is still viable. More... | |
typedef void *(* | fr_connection_create_t )(TALLOC_CTX *ctx, void *opaque, struct timeval const *timeout) |
Create a new connection handle. More... | |
typedef void(* | fr_connection_pool_reconnect_t )(void *opaque) |
Alter the opaque data of a connection pool during reconnection event. More... | |
typedef struct fr_connection_pool_state | fr_connection_pool_state_t |
typedef struct fr_connection_pool_t | fr_connection_pool_t |
Functions | |
int | fr_connection_close (fr_connection_pool_t *pool, void *conn) |
Delete a connection from the connection pool. More... | |
void * | fr_connection_get (fr_connection_pool_t *pool) |
Reserve a connection in the connection pool. More... | |
fr_connection_pool_t * | fr_connection_pool_copy (TALLOC_CTX *ctx, fr_connection_pool_t *pool, void *opaque) |
Allocate a new pool using an existing one as a template. More... | |
void | fr_connection_pool_free (fr_connection_pool_t *pool) |
Delete a connection pool. More... | |
fr_connection_pool_t * | fr_connection_pool_init (TALLOC_CTX *ctx, CONF_SECTION *cs, void *opaque, fr_connection_create_t c, fr_connection_alive_t a, char const *log_prefix, char const *trigger_prefix) |
Create a new connection pool. More... | |
void const * | fr_connection_pool_opaque (fr_connection_pool_t *pool) |
Return the opaque data associated with a connection pool. More... | |
int | fr_connection_pool_reconnect (fr_connection_pool_t *pool) |
Mark connections for reconnection, and spawn at least 'start' connections. More... | |
void | fr_connection_pool_reconnect_func (fr_connection_pool_t *pool, fr_connection_pool_reconnect_t reconnect) |
Set a reconnection callback for the connection pool. More... | |
void | fr_connection_pool_ref (fr_connection_pool_t *pool) |
Increment pool reference by one. More... | |
fr_connection_pool_state_t const * | fr_connection_pool_state (fr_connection_pool_t *pool) |
Get the number of connections currently in the pool. More... | |
struct timeval | fr_connection_pool_timeout (fr_connection_pool_t *pool) |
Connection pool get timeout. More... | |
void * | fr_connection_reconnect (fr_connection_pool_t *pool, void *conn) |
Reconnect a suspected inviable connection. More... | |
void | fr_connection_release (fr_connection_pool_t *pool, void *conn) |
Release a connection. More... | |
API to manage pools of persistent connections to external resources.
Definition in file connection.h.
struct fr_connection_pool_state |
Definition at line 37 of file connection.h.
typedef int(* fr_connection_alive_t)(void *opaque, void *connection) |
Check a connection handle is still viable.
Should check the state of a connection handle.
[in] | opaque | pointer passed to fr_connection_pool_init. |
[in] | connection | handle returned by fr_connection_create_t. |
Definition at line 113 of file connection.h.
typedef void*(* fr_connection_create_t)(TALLOC_CTX *ctx, void *opaque, struct timeval const *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 parent context to hold the module's connection structure. The parent context is allocated in the NULL context, but will be freed when fr_connection_t is freed.
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 ctx.
[in,out] | ctx | to allocate memory in. |
[in] | opaque | pointer passed to fr_connection_pool_init. |
[in] | timeout | The maximum time in ms the function has to complete the connection. Should be enforced by the function. |
Definition at line 98 of file connection.h.
typedef void(* fr_connection_pool_reconnect_t)(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.
[in,out] | opaque | pointer passed to fr_connection_pool_init. |
Definition at line 72 of file connection.h.
typedef struct fr_connection_pool_state fr_connection_pool_state_t |
typedef struct fr_connection_pool_t fr_connection_pool_t |
Definition at line 35 of file connection.h.
int fr_connection_close | ( | fr_connection_pool_t * | pool, |
void * | conn | ||
) |
Delete a connection from the connection pool.
Resolves the connection handle to a connection, then (if found) closes, unlinks and frees that connection.
[in,out] | pool | Connection pool to modify. |
[in] | conn | to delete. |
Definition at line 1403 of file connection.c.
void* fr_connection_get | ( | fr_connection_pool_t * | pool | ) |
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.
[in,out] | pool | to reserve the connection from. |
Definition at line 1291 of file connection.c.
fr_connection_pool_t* fr_connection_pool_copy | ( | TALLOC_CTX * | ctx, |
fr_connection_pool_t * | pool, | ||
void * | opaque | ||
) |
Allocate a new pool using an existing one as a template.
ctx | to allocate new pool in. |
pool | to copy. |
opaque | data to pass to connection function. |
Definition at line 1070 of file connection.c.
void fr_connection_pool_free | ( | fr_connection_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.
[in,out] | pool | to delete. |
Definition at line 1226 of file connection.c.
fr_connection_pool_t* fr_connection_pool_init | ( | TALLOC_CTX * | ctx, |
CONF_SECTION * | cs, | ||
void * | opaque, | ||
fr_connection_create_t | c, | ||
fr_connection_alive_t | a, | ||
char const * | log_prefix, | ||
char const * | trigger_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 options.
[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. |
[in] | trigger_prefix | prefix to prepend to all trigger names. |
Definition at line 899 of file connection.c.
void const* fr_connection_pool_opaque | ( | fr_connection_pool_t * | pool | ) |
Return the opaque data associated with a connection pool.
pool | to return data for. |
Definition at line 1101 of file connection.c.
int fr_connection_pool_reconnect | ( | fr_connection_pool_t * | pool | ) |
Mark connections for reconnection, and spawn at least 'start' connections.
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.
[in] | pool | to reconnect. |
Definition at line 1141 of file connection.c.
void fr_connection_pool_reconnect_func | ( | fr_connection_pool_t * | pool, |
fr_connection_pool_reconnect_t | reconnect | ||
) |
Set a reconnection callback for the connection pool.
This can be called at any time during the pool's lifecycle.
[in] | pool | to set reconnect callback for. |
reconnect | callback to call when reconnecting pool's connections. |
Definition at line 1122 of file connection.c.
void fr_connection_pool_ref | ( | fr_connection_pool_t * | pool | ) |
Increment pool reference by one.
[in] | pool | to increment reference counter for. |
Definition at line 1110 of file connection.c.
fr_connection_pool_state_t const* fr_connection_pool_state | ( | fr_connection_pool_t * | pool | ) |
Get the number of connections currently in the pool.
[in] | pool | to count connections for. |
Definition at line 1081 of file connection.c.
struct timeval fr_connection_pool_timeout | ( | fr_connection_pool_t * | pool | ) |
Connection pool get timeout.
[in] | pool | to get connection timeout for. |
Definition at line 1091 of file connection.c.
void* fr_connection_reconnect | ( | fr_connection_pool_t * | pool, |
void * | conn | ||
) |
Reconnect a suspected inviable connection.
This should be called by the module if it suspects that a connection is not viable (e.g. the server has closed it).
When implementing a module that uses the connection pool API, it is advisable to pass a pointer to the pointer to the handle (void **conn) to all functions which may call reconnect. This is so that if a new handle is created and returned, the handle pointer can be updated up the callstack, and a function higher up the stack doesn't attempt to use a now invalid connection handle.
[in,out] | pool | to reconnect the connection in. |
[in,out] | conn | to reconnect. |
Definition at line 1367 of file connection.c.
void fr_connection_release | ( | fr_connection_pool_t * | pool, |
void * | conn | ||
) |
Release a connection.
Will mark a connection as unused and decrement the number of active connections.
[in,out] | pool | to release the connection in. |
[in,out] | conn | to release. |
Definition at line 1305 of file connection.c.