All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Typedefs | Functions
connection.h File Reference

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

#include <freeradius-devel/conffile.h>
+ Include dependency graph for connection.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_tfr_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_tfr_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...
 

Detailed Description

API to manage pools of persistent connections to external resources.

Id:
700294b080c0fd4303c14a0339337b09546a4dce

Definition in file connection.h.


Data Structure Documentation

struct fr_connection_pool_state

Definition at line 37 of file connection.h.

Data Fields
uint32_t active Number of currently reserved connections.
uint64_t count Number of connections spawned over the lifetime of the pool.
time_t last_at_max Last time we hit the maximum number of allowed connections.
time_t last_checked Last time we pruned the connection pool.
struct timeval last_closed Last time a connection was closed.
time_t last_failed Last time we tried to spawn a connection but failed.
struct timeval last_released Last time a connection was released.
time_t last_spawned Last time we spawned a connection.
time_t last_throttled Last time we refused to spawn a connection because the last connection failed, or we were already spawning a connection.
int 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

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.

Note
NULL may be passed to fr_connection_pool_init, if there is no way to check the state of a connection handle.
Not currently use by connection pool manager.
Parameters
[in]opaquepointer passed to fr_connection_pool_init.
[in]connectionhandle returned by fr_connection_create_t.
Returns
  • 0 on success.
  • < 0 on error or if the connection is unusable.

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.

Note
A function pointer matching this prototype must be passed to fr_connection_pool_init.
Parameters
[in,out]ctxto allocate memory in.
[in]opaquepointer passed to fr_connection_pool_init.
[in]timeoutThe 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 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.

Parameters
[in,out]opaquepointer passed to fr_connection_pool_init.

Definition at line 72 of file connection.h.

Definition at line 35 of file connection.h.

Function Documentation

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.

Note
Must be called with the mutex free.
Parameters
[in,out]poolConnection pool to modify.
[in]connto delete.
Returns
  • 0 If the connection could not be found.
  • 1 if the connection was deleted.

Definition at line 1403 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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.

Note
fr_connection_release must be called once the caller has finished using the connection.
See Also
fr_connection_release
Parameters
[in,out]poolto reserve the connection from.
Returns
  • A pointer to the connection handle.
  • NULL on error.

Definition at line 1291 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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.

Parameters
ctxto allocate new pool in.
poolto copy.
opaquedata to pass to connection function.
Returns
  • New connection pool.
  • NULL on error.

Definition at line 1070 of file connection.c.

+ Here is the call graph for this function:

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.

Note
Will call the 'stop' trigger.
Must be called with the mutex free.
Parameters
[in,out]poolto delete.

Definition at line 1226 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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.

Note
Will call the 'start' trigger.
Parameters
[in]ctxContext to link pool's destruction to.
[in]cspool section.
[in]opaquedata pointer to pass to callbacks.
[in]cCallback to create new connections.
[in]aCallback to check the status of connections.
[in]log_prefixprefix to prepend to all log messages.
[in]trigger_prefixprefix to prepend to all trigger names.
Returns
  • New connection pool.
  • NULL on error.

Definition at line 899 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void const* fr_connection_pool_opaque ( fr_connection_pool_t pool)

Return the opaque data associated with a connection pool.

Parameters
poolto return data for.
Returns
opaque data associated with pool.

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.

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]poolto reconnect.
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 1141 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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.

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

Definition at line 1122 of file connection.c.

+ Here is the caller graph for this function:

void fr_connection_pool_ref ( fr_connection_pool_t pool)

Increment pool reference by one.

Parameters
[in]poolto increment reference counter for.

Definition at line 1110 of file connection.c.

+ Here is the caller graph for this function:

Get the number of connections currently in the pool.

Parameters
[in]poolto count connections for.
Returns
the number of connections in the pool

Definition at line 1081 of file connection.c.

+ Here is the caller graph for this function:

struct timeval fr_connection_pool_timeout ( fr_connection_pool_t pool)

Connection pool get timeout.

Parameters
[in]poolto get connection timeout for.
Returns
the connection timeout configured for the pool.

Definition at line 1091 of file connection.c.

+ Here is the caller graph for this function:

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.

Note
Will free any talloced memory hung off the context of the connection, being reconnected.
Warning
After calling reconnect the caller MUST NOT attempt to use the old handle in any other operations, as its memory will have been freed.
See Also
fr_connection_get
Parameters
[in,out]poolto reconnect the connection in.
[in,out]connto reconnect.
Returns
new connection handle if successful else NULL.

Definition at line 1367 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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.

See Also
fr_connection_get
Parameters
[in,out]poolto release the connection in.
[in,out]connto release.

Definition at line 1305 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function: