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

Handle pools of connections (threads, sockets, etc.) More...

#include <freeradius-devel/radiusd.h>
#include <freeradius-devel/heap.h>
#include <freeradius-devel/modpriv.h>
#include <freeradius-devel/rad_assert.h>
+ Include dependency graph for connection.c:

Go to the source code of this file.

Data Structures

struct  fr_connection
 An individual connection within the connection pool. More...
 
struct  fr_connection_pool_t
 A connection pool. More...
 

Macros

#define PTHREAD_COND_BROADCAST(_x)
 
#define PTHREAD_MUTEX_LOCK(_x)
 
#define PTHREAD_MUTEX_UNLOCK(_x)
 

Typedefs

typedef struct fr_connection fr_connection_t
 

Functions

int fr_connection_close (fr_connection_pool_t *pool, void *conn)
 Delete a connection from the connection pool. More...
 
static void fr_connection_close_internal (fr_connection_pool_t *pool, fr_connection_t *this)
 Close an existing connection. More...
 
static void fr_connection_exec_trigger (fr_connection_pool_t *pool, char const *name_suffix)
 Send a connection pool trigger. More...
 
static fr_connection_tfr_connection_find (fr_connection_pool_t *pool, void *conn)
 Find a connection handle in the connection list. More...
 
void * fr_connection_get (fr_connection_pool_t *pool)
 Reserve a connection in the connection pool. More...
 
static void * fr_connection_get_internal (fr_connection_pool_t *pool, bool spawn)
 Get a connection from the connection pool. More...
 
static void fr_connection_link_head (fr_connection_pool_t *pool, fr_connection_t *this)
 Adds a connection to the head of the connection list. More...
 
static int fr_connection_manage (fr_connection_pool_t *pool, fr_connection_t *this, time_t now)
 Check whether a connection needs to be removed from the pool. More...
 
static int fr_connection_pool_check (fr_connection_pool_t *pool)
 Check whether any connections need to be removed from the 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...
 
static fr_connection_tfr_connection_spawn (fr_connection_pool_t *pool, time_t now, bool in_use)
 Spawns a new connection. More...
 
static void fr_connection_unlink (fr_connection_pool_t *pool, fr_connection_t *this)
 Removes a connection from the connection list. More...
 
static int last_released_cmp (void const *one, void const *two)
 Order connections by released longest ago. More...
 
static int last_reserved_cmp (void const *one, void const *two)
 Order connections by reserved most recently. More...
 

Variables

static const CONF_PARSER connection_config []
 

Detailed Description

Handle pools of connections (threads, sockets, etc.)

Note
This API must be used by all modules in the public distribution that maintain pools of connections.

Definition in file connection.c.


Data Structure Documentation

struct fr_connection

An individual connection within the connection pool.

Defines connection counters, timestamps, and holds a pointer to the connection handle itself.

See Also
fr_connection_pool_t

Definition at line 50 of file connection.c.

+ Collaboration diagram for fr_connection:
Data Fields
void * connection Pointer to whatever the module uses for a connection handle.
time_t created Time connection was created.
int heap For the next connection heap.
bool in_use Whether the connection is currently reserved.
struct timeval last_released Time the connection was released.
struct timeval last_reserved Last time the connection was reserved.
bool needs_reconnecting Reconnect this connection before use.
fr_connection_t * next Next connection in list.
uint32_t num_uses Number of times the connection has been reserved.
uint64_t number Unique ID assigned when the connection is created, these will monotonically increase over the lifetime of the connection pool.
fr_connection_t * prev Previous connection in list.
struct fr_connection_pool_t

A connection pool.

Defines the configuration of the connection pool, all the counters and timestamps related to the connection pool, the mutex that stops multiple threads leaving the pool in an inconsistent state, and the callbacks required to open, close and check the status of connections within the pool.

See Also
fr_connection

Definition at line 85 of file connection.c.

+ Collaboration diagram for fr_connection_pool_t:
Data Fields
fr_connection_alive_t alive Function used to check status of connections.
uint32_t cleanup_interval Initial timer for how often we sweep the pool for free connections.

(0 is infinite).

struct timeval connect_timeout New connection timeout, enforced by the create callback.
fr_connection_create_t create Function used to create new connections.
CONF_SECTION * cs Configuration section holding the section of parsed config file that relates to this pool.
int delay_interval When we next do a cleanup.

Initialized to cleanup_interval, and increase from there based on the delay.

fr_connection_t * head Start of the connection list.
fr_heap_t * heap For the next connection heap.
uint32_t idle_timeout How long a connection can be idle before being closed.
uint32_t lifetime How long a connection can be open before being closed (irrespective of whether it's idle or not).
char const * log_prefix Log prefix to prepend to all log messages created by the connection pool code.
uint32_t max Maximum number of concurrent connections to allow.
uint32_t max_pending Max number of connections to open.
uint64_t max_uses Maximum number of times a connection can be used before being closed.
uint32_t min Minimum number of concurrent connections to keep open.
void * opaque Pointer to context data that will be passed to callbacks.
fr_connection_pool_reconnect_t reconnect Called during connection pool reconnect.
int ref Reference counter to prevent connection pool being freed multiple times.
uint32_t retry_delay seconds to delay re-open after a failed open.
uint32_t spare Number of spare connections to try.
bool spread If true we spread requests over the connections, using the connection released longest ago, first.
uint32_t start Number of initial connections.
fr_connection_pool_state_t state Stats and state of the connection pool.
fr_connection_t * tail End of the connection list.
char const * trigger_prefix Prefix to prepend to names of all triggers fired by the connection pool code.

Macro Definition Documentation

#define PTHREAD_COND_BROADCAST (   _x)

Definition at line 149 of file connection.c.

#define PTHREAD_MUTEX_LOCK (   _x)

Definition at line 147 of file connection.c.

#define PTHREAD_MUTEX_UNLOCK (   _x)

Definition at line 148 of file connection.c.

Typedef Documentation

Definition at line 33 of file connection.c.

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:

static void fr_connection_close_internal ( fr_connection_pool_t pool,
fr_connection_t this 
)
static

Close an existing connection.

Removes the connection from the list, calls the delete callback to close the connection, then frees memory allocated to the connection.

Note
Will call the 'close' trigger.
Must be called with the mutex held.
Parameters
[in,out]poolto modify.
[in,out]thisConnection to delete.

Definition at line 527 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static void fr_connection_exec_trigger ( fr_connection_pool_t pool,
char const *  name_suffix 
)
static

Send a connection pool trigger.

Parameters
[in]poolto send trigger for.
[in]name_suffixtrigger name suffix.

Definition at line 261 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static fr_connection_t* fr_connection_find ( fr_connection_pool_t pool,
void *  conn 
)
static

Find a connection handle in the connection list.

Walks over the list of connections searching for a specified connection handle and returns the first connection that contains that pointer.

Note
Will lock mutex and only release mutex if connection handle is not found, so will usually return will mutex held.
Must be called with the mutex free.
Parameters
[in]poolto search in.
[in]connhandle to search for.
Returns
  • Connection containing the specified handle.
  • NULL if non if connection was found.

Definition at line 285 of file connection.c.

+ 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:

static void* fr_connection_get_internal ( fr_connection_pool_t pool,
bool  spawn 
)
static

Get a connection from the connection pool.

Note
Must be called with the mutex free.
Parameters
[in,out]poolto reserve the connection from.
[in]spawnwhether to spawn a new connection
Returns
  • A pointer to the connection handle.
  • NULL on error.

Definition at line 798 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static void fr_connection_link_head ( fr_connection_pool_t pool,
fr_connection_t this 
)
static

Adds a connection to the head of the connection list.

Note
Must be called with the mutex held.
Parameters
[in,out]poolto modify.
[in]thisConnection to add.

Definition at line 234 of file connection.c.

+ Here is the caller graph for this function:

static int fr_connection_manage ( fr_connection_pool_t pool,
fr_connection_t this,
time_t  now 
)
static

Check whether a connection needs to be removed from the pool.

Will verify that the connection is within idle_timeout, max_uses, and lifetime values. If it is not, the connection will be closed.

Note
Will only close connections not in use.
Must be called with the mutex held.
Parameters
[in,out]poolto modify.
[in,out]thisConnection to manage.
[in]nowCurrent time.
Returns
  • 0 if connection was closed.
  • 1 if connection handle was left open.

Definition at line 574 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static int fr_connection_pool_check ( fr_connection_pool_t pool)
static

Check whether any connections need to be removed from the pool.

Maintains the number of connections in the pool as per the configuration parameters for the connection pool.

Note
Will only run checks the first time it's called in a given second, to throttle connection spawning/closing.
Will only close connections not in use.
Must be called with the mutex held, will release mutex before returning.
Parameters
[in,out]poolto manage.
Returns
1

Definition at line 636 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:

static fr_connection_t* fr_connection_spawn ( fr_connection_pool_t pool,
time_t  now,
bool  in_use 
)
static

Spawns a new connection.

Spawns a new connection using the create callback, and returns it for adding to the connection list.

Note
Will call the 'open' trigger.
Must be called with the mutex free.
Parameters
[in]poolto modify.
[in]nowCurrent time.
[in]in_usewhether the new connection should be "in_use" or not
Returns
  • New connection struct.
  • NULL on error.

Definition at line 331 of file connection.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static void fr_connection_unlink ( fr_connection_pool_t pool,
fr_connection_t this 
)
static

Removes a connection from the connection list.

Note
Must be called with the mutex held.
Parameters
[in,out]poolto modify.
[in]thisConnection to delete.

Definition at line 207 of file connection.c.

+ Here is the caller graph for this function:

static int last_released_cmp ( void const *  one,
void const *  two 
)
static

Order connections by released longest ago.

Definition at line 186 of file connection.c.

+ Here is the caller graph for this function:

static int last_reserved_cmp ( void const *  one,
void const *  two 
)
static

Order connections by reserved most recently.

Definition at line 170 of file connection.c.

+ Here is the caller graph for this function:

Variable Documentation

const CONF_PARSER connection_config[]
static
Initial value:
= {
{ FR_CONF_OFFSET("start", PW_TYPE_INTEGER, fr_connection_pool_t, start), .dflt = "5" },
{ FR_CONF_OFFSET("min", PW_TYPE_INTEGER, fr_connection_pool_t, min), .dflt = "5" },
{ FR_CONF_OFFSET("max", PW_TYPE_INTEGER, fr_connection_pool_t, max), .dflt = "10" },
{ FR_CONF_OFFSET("spare", PW_TYPE_INTEGER, fr_connection_pool_t, spare), .dflt = "3" },
{ FR_CONF_OFFSET("uses", PW_TYPE_INTEGER64, fr_connection_pool_t, max_uses), .dflt = "0" },
{ FR_CONF_OFFSET("lifetime", PW_TYPE_INTEGER, fr_connection_pool_t, lifetime), .dflt = "0" },
{ FR_CONF_OFFSET("cleanup_delay", PW_TYPE_INTEGER, fr_connection_pool_t, cleanup_interval) },
{ FR_CONF_OFFSET("cleanup_interval", PW_TYPE_INTEGER, fr_connection_pool_t, cleanup_interval), .dflt = "30" },
{ FR_CONF_OFFSET("idle_timeout", PW_TYPE_INTEGER, fr_connection_pool_t, idle_timeout), .dflt = "60" },
{ FR_CONF_OFFSET("connect_timeout", PW_TYPE_TIMEVAL, fr_connection_pool_t, connect_timeout), .dflt = "3.0" },
{ FR_CONF_OFFSET("retry_delay", PW_TYPE_INTEGER, fr_connection_pool_t, retry_delay), .dflt = "1" },
{ FR_CONF_OFFSET("spread", PW_TYPE_BOOLEAN, fr_connection_pool_t, spread), .dflt = "no" },
}
Time value (struct timeval), only for config items.
Definition: radius.h:55
#define CONF_PARSER_TERMINATOR
Definition: conffile.h:289
A truth value.
Definition: radius.h:56
32 Bit unsigned integer.
Definition: radius.h:34
64 Bit unsigned integer.
Definition: radius.h:51
#define FR_CONF_OFFSET(_n, _t, _s, _f)
Definition: conffile.h:168
A connection pool.
Definition: connection.c:85

Definition at line 152 of file connection.c.