All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
connection.h
Go to the documentation of this file.
1 /*
2  * This program is free software; you can redistribute it and/or modify
3  * it under the terms of the GNU General Public License as published by
4  * the Free Software Foundation; either version 2 of the License, or
5  * (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
15  */
16 #ifndef _FR_CONNECTION_H
17 #define _FR_CONNECTION_H
18 /**
19  * $Id: 700294b080c0fd4303c14a0339337b09546a4dce $
20  *
21  * @file include/connection.h
22  * @brief API to manage pools of persistent connections to external resources.
23  *
24  * @copyright 2012 The FreeRADIUS server project
25  * @copyright 2012 Alan DeKok <aland@deployingradius.com>
26  */
27 RCSIDH(connection_h, "$Id: 700294b080c0fd4303c14a0339337b09546a4dce $")
28 
29 #include <freeradius-devel/conffile.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
36 
37 typedef struct fr_connection_pool_state {
38  uint32_t pending; //!< Number of pending open connections.
39  time_t last_checked; //!< Last time we pruned the connection pool.
40  time_t last_spawned; //!< Last time we spawned a connection.
41  time_t last_failed; //!< Last time we tried to spawn a connection but failed.
42  time_t last_throttled; //!< Last time we refused to spawn a connection because
43  //!< the last connection failed, or we were already spawning
44  //!< a connection.
45  time_t last_at_max; //!< Last time we hit the maximum number of allowed
46  //!< connections.
47  struct timeval last_released; //!< Last time a connection was released.
48  struct timeval last_closed; //!< Last time a connection was closed.
49 
50  int next_delay; //!< The next delay time. cleanup. Initialized to
51  //!< cleanup_interval, and decays from there.
52 
53  uint64_t count; //!< Number of connections spawned over the lifetime
54  //!< of the pool.
55  uint32_t num; //!< Number of connections in the pool.
56  uint32_t active; //!< Number of currently reserved connections.
57 
58  bool reconnecting; //!< We are currently reconnecting the pool.
60 
61 /** Alter the opaque data of a connection pool during reconnection event
62  *
63  * This function will be called whenever we have been signalled to
64  * reconnect all the connections in a pool.
65  *
66  * It is called at a point where we have determined that no connection
67  * spawning is in progress, so it is safe to modify any pointers or
68  * memory associated with the opaque data.
69  *
70  * @param[in,out] opaque pointer passed to fr_connection_pool_init.
71  */
72 typedef void (*fr_connection_pool_reconnect_t)(void *opaque);
73 
74 /** Create a new connection handle
75  *
76  * This function will be called whenever the connection pool manager needs
77  * to spawn a new connection, and on reconnect.
78  *
79  * Memory should be talloced in the parent context to hold the module's
80  * connection structure. The parent context is allocated in the NULL
81  * context, but will be freed when fr_connection_t is freed.
82  *
83  * There is no delete callback, so operations such as closing sockets and
84  * freeing library connection handles should be done by a destructor attached
85  * to memory allocated beneath ctx.
86  *
87  * @note A function pointer matching this prototype must be passed
88  * to fr_connection_pool_init.
89  *
90  * @param[in,out] ctx to allocate memory in.
91  * @param[in] opaque pointer passed to fr_connection_pool_init.
92  * @param[in] timeout The maximum time in ms the function has to complete
93  * the connection. Should be enforced by the function.
94  * @return
95  * - NULL on error.
96  * - A connection handle on success.
97  */
98 typedef void *(*fr_connection_create_t)(TALLOC_CTX *ctx, void *opaque, struct timeval const *timeout);
99 
100 /** Check a connection handle is still viable
101  *
102  * Should check the state of a connection handle.
103  *
104  * @note NULL may be passed to fr_connection_pool_init, if there is no way to check
105  * the state of a connection handle.
106  * @note Not currently use by connection pool manager.
107  * @param[in] opaque pointer passed to fr_connection_pool_init.
108  * @param[in] connection handle returned by fr_connection_create_t.
109  * @return
110  * - 0 on success.
111  * - < 0 on error or if the connection is unusable.
112  */
113 typedef int (*fr_connection_alive_t)(void *opaque, void *connection);
114 
115 /*
116  * Pool allocation/initialisation
117  */
119  CONF_SECTION *cs,
120  void *opaque,
123  char const *log_prefix,
124  char const *trigger_prefix);
125 
126 fr_connection_pool_t *fr_connection_pool_copy(TALLOC_CTX *ctx, fr_connection_pool_t *pool, void *opaque);
127 
128 
129 /*
130  * Pool get/set
131  */
133 
135 
137 
139 
141 
142 /*
143  * Pool management
144  */
146 
148 
149 /*
150  * Connection lifecycle
151  */
153 
154 void fr_connection_release(fr_connection_pool_t *pool, void *conn);
155 
156 void *fr_connection_reconnect(fr_connection_pool_t *pool, void *conn);
157 
158 int fr_connection_close(fr_connection_pool_t *pool, void *conn);
159 
160 #ifdef __cplusplus
161 }
162 #endif
163 #endif /* _FR_CONNECTION_H*/
#define RCSIDH(h, id)
Definition: build.h:136
void const * fr_connection_pool_opaque(fr_connection_pool_t *pool)
Return the opaque data associated with a connection pool.
Definition: connection.c:1101
int(* fr_connection_alive_t)(void *opaque, void *connection)
Check a connection handle is still viable.
Definition: connection.h:113
static float timeout
Definition: radclient.c:43
bool reconnecting
We are currently reconnecting the pool.
Definition: connection.h:58
time_t last_checked
Last time we pruned the connection pool.
Definition: connection.h:39
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.
Definition: connection.c:1122
void(* fr_connection_pool_reconnect_t)(void *opaque)
Alter the opaque data of a connection pool during reconnection event.
Definition: connection.h:72
struct timeval last_released
Last time a connection was released.
Definition: connection.h:47
time_t last_spawned
Last time we spawned a connection.
Definition: connection.h:40
uint32_t active
Number of currently reserved connections.
Definition: connection.h:56
struct timeval fr_connection_pool_timeout(fr_connection_pool_t *pool)
Connection pool get timeout.
Definition: connection.c:1091
struct fr_connection_pool_state fr_connection_pool_state_t
time_t last_failed
Last time we tried to spawn a connection but failed.
Definition: connection.h:41
time_t last_throttled
Last time we refused to spawn a connection because the last connection failed, or we were already spa...
Definition: connection.h:42
void fr_connection_pool_ref(fr_connection_pool_t *pool)
Increment pool reference by one.
Definition: connection.c:1110
uint32_t num
Number of connections in the pool.
Definition: connection.h:55
void * fr_connection_get(fr_connection_pool_t *pool)
Reserve a connection in the connection pool.
Definition: connection.c:1291
A connection pool.
Definition: connection.c:85
int fr_connection_pool_reconnect(fr_connection_pool_t *pool)
Mark connections for reconnection, and spawn at least 'start' connections.
Definition: connection.c:1141
int fr_connection_close(fr_connection_pool_t *pool, void *conn)
Delete a connection from the connection pool.
Definition: connection.c:1403
time_t last_at_max
Last time we hit the maximum number of allowed connections.
Definition: connection.h:45
struct timeval last_closed
Last time a connection was closed.
Definition: connection.h:48
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.
Definition: connection.c:899
uint64_t count
Number of connections spawned over the lifetime of the pool.
Definition: connection.h:53
void fr_connection_release(fr_connection_pool_t *pool, void *conn)
Release a connection.
Definition: connection.c:1305
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.
Definition: connection.c:1070
void *(* fr_connection_create_t)(TALLOC_CTX *ctx, void *opaque, struct timeval const *timeout)
Create a new connection handle.
Definition: connection.h:98
int next_delay
The next delay time.
Definition: connection.h:50
fr_connection_pool_state_t const * fr_connection_pool_state(fr_connection_pool_t *pool)
Get the number of connections currently in the pool.
Definition: connection.c:1081
void * fr_connection_reconnect(fr_connection_pool_t *pool, void *conn)
Reconnect a suspected inviable connection.
Definition: connection.c:1367
uint32_t pending
Number of pending open connections.
Definition: connection.h:38
void fr_connection_pool_free(fr_connection_pool_t *pool)
Delete a connection pool.
Definition: connection.c:1226