The FreeRADIUS server  $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Data Structures | Macros | Typedefs | Functions | Variables
pool.c File Reference

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

#include <freeradius-devel/server/base.h>
#include <freeradius-devel/server/modpriv.h>
#include <freeradius-devel/util/debug.h>
#include <freeradius-devel/util/heap.h>
#include <freeradius-devel/util/misc.h>
#include <time.h>
+ Include dependency graph for pool.c:

Go to the source code of this file.

Data Structures

struct  fr_pool_connection_s
 An individual connection within the connection pool. More...
 
struct  fr_pool_s
 A connection pool. More...
 

Macros

#define LOG_PREFIX   pool->log_prefix
 

Typedefs

typedef struct fr_pool_connection_s fr_pool_connection_t
 

Functions

static int connection_check (fr_pool_t *pool, request_t *request)
 Check whether any connections need to be removed from the pool. More...
 
static void connection_close_internal (fr_pool_t *pool, fr_pool_connection_t *this)
 Close an existing connection. More...
 
static fr_pool_connection_tconnection_find (fr_pool_t *pool, void *conn)
 Find a connection handle in the connection list. More...
 
static void * connection_get_internal (fr_pool_t *pool, request_t *request, bool spawn)
 Get a connection from the connection pool. More...
 
static void connection_link_head (fr_pool_t *pool, fr_pool_connection_t *this)
 Adds a connection to the head of the connection list. More...
 
static int connection_manage (fr_pool_t *pool, request_t *request, fr_pool_connection_t *this, fr_time_t now)
 Check whether a connection needs to be removed from the pool. More...
 
static fr_pool_connection_tconnection_spawn (fr_pool_t *pool, request_t *request, fr_time_t now, bool in_use, bool unlock)
 Spawns a new connection. More...
 
static void connection_unlink (fr_pool_t *pool, fr_pool_connection_t *this)
 Removes a connection from the connection list. More...
 
int fr_pool_connection_close (fr_pool_t *pool, request_t *request, void *conn)
 Delete a connection from the connection pool. More...
 
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, void *conn)
 Reconnect a suspected inviable connection. More...
 
void fr_pool_connection_release (fr_pool_t *pool, request_t *request, void *conn)
 Release a connection. More...
 
fr_pool_tfr_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_tfr_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...
 
static void fr_pool_trigger_exec (fr_pool_t *pool, char const *event)
 Send a connection pool trigger. More...
 
static int8_t last_released_cmp (void const *one, void const *two)
 Order connections by released longest ago. More...
 
static int8_t last_reserved_cmp (void const *one, void const *two)
 Order connections by reserved most recently. More...
 
static int max_dflt (CONF_PAIR **out, UNUSED void *parent, CONF_SECTION *cs, fr_token_t quote, conf_parser_t const *rule)
 
static int max_dflt (CONF_PAIR **out, void *parent, CONF_SECTION *cs, fr_token_t quote, conf_parser_t const *rule)
 

Variables

static const conf_parser_t pool_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 pool.c.


Data Structure Documentation

◆ fr_pool_connection_s

struct fr_pool_connection_s

An individual connection within the connection pool.

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

See also
fr_pool_t

Definition at line 51 of file pool.c.

+ Collaboration diagram for fr_pool_connection_s:
Data Fields
void * connection Pointer to whatever the module uses for a connection handle.
fr_time_t created Time connection was created.
fr_heap_index_t heap_id For the next connection heap.
bool in_use Whether the connection is currently reserved.
fr_time_t last_released Time the connection was released.
fr_time_t last_reserved Last time the connection was reserved.
bool needs_reconnecting Reconnect this connection before use.
fr_pool_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_pool_connection_t * prev Previous connection in list.

◆ fr_pool_s

struct fr_pool_s

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 pool.c.

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

(0 is infinite).

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

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

pthread_cond_t done_reconnecting Before calling the create callback, threads should block on this condition if reconnecting == true.
pthread_cond_t done_spawn Threads that need to ensure no spawning is in progress, should block on this condition if pending != 0.
fr_pool_connection_t * head Start of the connection list.
fr_heap_t * heap For the next connection heap.
fr_time_delta_t held_trigger_max If a connection is held for longer than the specified period, fire a trigger.
fr_time_delta_t held_trigger_min If a connection is held for less than the specified period, fire a trigger.
fr_time_delta_t idle_timeout How long a connection can be idle before being closed.
fr_time_delta_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 pending connections to allow.
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.
pthread_mutex_t mutex Mutex used to keep consistent state when making modifications in threaded mode.
void * opaque Pointer to context data that will be passed to callbacks.
uint32_t pending_window Sliding window of pending connections.
fr_pool_reconnect_t reconnect Called during connection pool reconnect.
int ref Reference counter to prevent connection pool being freed multiple times.
fr_time_delta_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_pool_state_t state Stats and state of the connection pool.
fr_pool_connection_t * tail End of the connection list.
fr_pair_list_t trigger_args Arguments to make available in connection pool triggers.
char const * trigger_prefix Prefix to prepend to names of all triggers fired by the connection pool code.
bool triggers_enabled Whether we call the trigger functions.

Macro Definition Documentation

◆ LOG_PREFIX

#define LOG_PREFIX   pool->log_prefix

Definition at line 28 of file pool.c.

Typedef Documentation

◆ fr_pool_connection_t

Definition at line 1 of file pool.c.

Function Documentation

◆ connection_check()

static int connection_check ( fr_pool_t pool,
request_t request 
)
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]poolto manage.
[in]requestThe current request.
Returns
1

Definition at line 655 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ connection_close_internal()

static void connection_close_internal ( fr_pool_t pool,
fr_pool_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]poolto modify.
[in]thisConnection to delete.

Definition at line 547 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ connection_find()

static fr_pool_connection_t* connection_find ( fr_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 287 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ connection_get_internal()

static void* connection_get_internal ( fr_pool_t pool,
request_t request,
bool  spawn 
)
static

Get a connection from the connection pool.

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

Definition at line 834 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ connection_link_head()

static void connection_link_head ( fr_pool_t pool,
fr_pool_connection_t this 
)
static

Adds a connection to the head of the connection list.

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

Definition at line 232 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ connection_manage()

static int connection_manage ( fr_pool_t pool,
request_t request,
fr_pool_connection_t this,
fr_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]poolto modify.
[in]requestThe current request.
[in]thisConnection to manage.
[in]nowCurrent time.
Returns
  • 0 if connection was closed.
  • 1 if connection handle was left open.

Definition at line 595 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ connection_spawn()

static fr_pool_connection_t* connection_spawn ( fr_pool_t pool,
request_t request,
fr_time_t  now,
bool  in_use,
bool  unlock 
)
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]requestThe current request.
[in]nowCurrent time.
[in]in_usewhether the new connection should be "in_use" or not
[in]unlockwhether we should unlock the mutex before returning
Returns
  • New connection struct.
  • NULL on error.

Definition at line 335 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ connection_unlink()

static void connection_unlink ( fr_pool_t pool,
fr_pool_connection_t this 
)
static

Removes a connection from the connection list.

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

Definition at line 205 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ fr_pool_connection_close()

int fr_pool_connection_close ( fr_pool_t pool,
request_t request,
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]poolConnection pool to modify.
[in]requestThe current request.
[in]connto delete.
Returns
  • 0 If the connection could not be found.
  • 1 if the connection was deleted.

Definition at line 1535 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ 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]poolto reserve the connection from.
[in]requestThe current request.
Returns
  • A pointer to the connection handle.
  • NULL on error.

Definition at line 1390 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,
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_pool_connection_get
Parameters
[in]poolto reconnect the connection in.
[in]requestThe current request.
[in]connto reconnect.
Returns
new connection handle if successful else NULL.

Definition at line 1498 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ fr_pool_connection_release()

void fr_pool_connection_release ( fr_pool_t pool,
request_t request,
void *  conn 
)

Release a connection.

Will mark a connection as unused and decrement the number of active connections.

See also
fr_pool_connection_get
Parameters
[in]poolto release the connection in.
[in]requestThe current request.
[in]connto release.

Definition at line 1405 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ 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]ctxto allocate new pool in.
[in]poolto copy.
[in]opaquedata to pass to connection function.
Returns
  • New connection pool.
  • NULL on error.

Definition at line 1154 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]poolto enable triggers for.
[in]trigger_prefixprefix 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_argsto 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 931 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]poolto delete.

Definition at line 1327 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]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.
Returns
  • New connection pool.
  • NULL on error.

Definition at line 965 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
poolto return data for.
Returns
opaque data associated with pool.

Definition at line 1201 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]poolto reconnect.
[in]requestThe 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 1242 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]poolto set reconnect callback for.
reconnectcallback to call when reconnecting pool's connections.

Definition at line 1222 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]poolto increment reference counter for.

Definition at line 1210 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 1114 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]poolto get connection start for.
Returns
the connection start value configured for the pool.

Definition at line 1191 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]poolto count connections for.
Returns
the number of connections in the pool

Definition at line 1171 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]poolto get connection timeout for.
Returns
the connection timeout configured for the pool.

Definition at line 1181 of file pool.c.

◆ fr_pool_trigger_exec()

static void fr_pool_trigger_exec ( fr_pool_t pool,
char const *  event 
)
inlinestatic

Send a connection pool trigger.

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

Definition at line 259 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ last_released_cmp()

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

Order connections by released longest ago.

Definition at line 191 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ last_reserved_cmp()

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

Order connections by reserved most recently.

Definition at line 182 of file pool.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ max_dflt() [1/2]

static int max_dflt ( CONF_PAIR **  out,
UNUSED void *  parent,
CONF_SECTION cs,
fr_token_t  quote,
conf_parser_t const *  rule 
)
static

Definition at line 169 of file pool.c.

+ Here is the call graph for this function:

◆ max_dflt() [2/2]

static int max_dflt ( CONF_PAIR **  out,
void *  parent,
CONF_SECTION cs,
fr_token_t  quote,
conf_parser_t const *  rule 
)
static

Variable Documentation

◆ pool_config

const conf_parser_t pool_config[]
static
Initial value:
= {
{ FR_CONF_OFFSET("start", fr_pool_t, start), .dflt = "0" },
{ FR_CONF_OFFSET("min", fr_pool_t, min), .dflt = "0" },
{ FR_CONF_OFFSET("max", fr_pool_t, max), .dflt_func = max_dflt },
{ FR_CONF_OFFSET("max_pending", fr_pool_t, max_pending), .dflt = "0" },
{ FR_CONF_OFFSET("spare", fr_pool_t, spare), .dflt = "3" },
{ FR_CONF_OFFSET("uses", fr_pool_t, max_uses), .dflt = "0" },
{ FR_CONF_OFFSET("lifetime", fr_pool_t, lifetime), .dflt = "0" },
{ FR_CONF_OFFSET("cleanup_interval", fr_pool_t, cleanup_interval), .dflt = "30" },
{ FR_CONF_OFFSET("idle_timeout", fr_pool_t, idle_timeout), .dflt = "60" },
{ FR_CONF_OFFSET("connect_timeout", fr_pool_t, connect_timeout), .dflt = "3.0" },
{ FR_CONF_OFFSET("held_trigger_min", fr_pool_t, held_trigger_min), .dflt = "0.0" },
{ FR_CONF_OFFSET("held_trigger_max", fr_pool_t, held_trigger_max), .dflt = "0.5" },
{ FR_CONF_OFFSET("retry_delay", fr_pool_t, retry_delay), .dflt = "1" },
{ FR_CONF_OFFSET("spread", fr_pool_t, spread), .dflt = "no" },
}
#define CONF_PARSER_TERMINATOR
Definition: cf_parse.h:626
#define FR_CONF_OFFSET(_name, _struct, _field)
conf_parser_t which parses a single CONF_PAIR, writing the result to a field in a struct
Definition: cf_parse.h:268
static int max_dflt(CONF_PAIR **out, void *parent, CONF_SECTION *cs, fr_token_t quote, conf_parser_t const *rule)
A connection pool.
Definition: pool.c:85
static size_t min(size_t x, size_t y)
Definition: sbuff.c:135

Definition at line 151 of file pool.c.