Pass a threadsafe ctx into fr_connection_pool create callback

[freeradius.git] / src / include / connection.h

diff --git a/src/include/connection.h b/src/include/connection.h
index 3b03f06..8b7473a 100644 (file)
--- a/src/include/connection.h
+++ b/src/include/connection.h
@@ -1,12 +1,4 @@
-#ifndef FR_CONNECTION_H
-#define FR_CONNECTION_H
-/**
- * @file connection.h
- * @brief      Structures, prototypes and global variables
- *             for server connection pools.
- *
- * Version:    $Id$
- *
+/*
  *   This program is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU General Public License as published by
  *   the Free Software Foundation; either version 2 of the License, or
@@ -20,15 +12,21 @@
  *   You should have received a copy of the GNU General Public License
  *   along with this program; if not, write to the Free Software
  *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+#ifndef FR_CONNECTION_H
+#define FR_CONNECTION_H
+/*
+ * $Id$
  *
- * Copyright 1999,2000,2002,2003,2004,2005,2006,2007,2008  The FreeRADIUS server project
+ * @file connection.h
+ * @brief Structures, prototypes and global variables for server connection pools.
  *
+ * @copyright 2012  The FreeRADIUS server project
+ * @copyright 2012  Alan DeKok <aland@deployingradius.com>
  */
 
-#include <freeradius-devel/ident.h>
 RCSIDH(connection_h, "$Id$")
 
-#include <freeradius-devel/radiusd.h>
 #include <freeradius-devel/conffile.h>
 
 #ifdef __cplusplus
@@ -37,21 +35,65 @@ extern "C" {
 
 typedef struct fr_connection_pool_t fr_connection_pool_t;
 
-typedef void *(*fr_connection_create_t)(void *ctx);
-typedef int (*fr_connection_alive_t)(void *ctx, void *connection);
-typedef int (*fr_connection_delete_t)(void *ctx, void *connection);
+/** 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 parent.
+ *
+ * @note A function pointer matching this prototype must be passed
+ * to fr_connection_pool.
+ *
+ * @param[in,out] ctx to allocate memory in.
+ * @param[in] opaque pointer passed to fr_connection_pool_init.
+ * @return NULL on error, else a connection handle.
+ */
+typedef void *(*fr_connection_create_t)(TALLOC_CTX *ctx, void *opaque);
+
+/** Check a connection handle is still viable
+ *
+ * Should check the state  of a connection handle.
+ *
+ * @note NULL may be passed to fr_connection_init, if there is no way to check
+ * the state of a connection handle.
+ * @note Not currently use by connection pool manager.
+ * @param[in] opaque pointer passed to fr_connection_pool_init.
+ * @param[in] connection handle returned by fr_connection_create_t.
+ * @return < 0 on error or if the connection is unusable, else 0.
+ */
+typedef int (*fr_connection_alive_t)(void *opaque, void *connection);
+
+/** Delete a connection and free allocated memory
+ *
+ * Should close any sockets associated with the passed connection handle,
+ * and free any memory allocated to it.
+ *
+ * @param[in] opaque pointer passed to fr_connection_pool_init.
+ * @param[in,out] connection handle returned by fr_connection_create_t.
+ * @return < 0 on error else 0 if connection was closed successfully.
+ */
+typedef int (*fr_connection_delete_t)(void *opaque, void *connection);
 
 fr_connection_pool_t *fr_connection_pool_init(CONF_SECTION *cs,
-                                             void *ctx,
+                                             void *opaque,
                                              fr_connection_create_t c,
                                              fr_connection_alive_t a,
-                                             fr_connection_delete_t d);
-void fr_connection_pool_delete(fr_connection_pool_t *fc);
+                                             fr_connection_delete_t d,
+                                             char const *prefix);
+void fr_connection_pool_delete(fr_connection_pool_t *pool);
 
-int fr_connection_check(fr_connection_pool_t *fc, void *conn);
-void *fr_connection_get(fr_connection_pool_t *fc);
-void fr_connection_release(fr_connection_pool_t *fc, void *conn);
-void *fr_connection_reconnect(fr_connection_pool_t *fc, void *conn);
+void *fr_connection_get(fr_connection_pool_t *pool);
+int fr_connection_get_num(fr_connection_pool_t *pool);
+void fr_connection_release(fr_connection_pool_t *pool, void *conn);
+void *fr_connection_reconnect(fr_connection_pool_t *pool, void *conn);
+int fr_connection_del(fr_connection_pool_t *pool, void *conn);
 
 #ifdef __cplusplus
 }