- towards seperating connection pooling from cache

1 files changed, 161 insertions, 0 deletions

diff --git a/src/testbed/gnunet-service-testbed_connectionpool.h b/src/testbed/gnunet-service-testbed_connectionpool.h
new file mode 100644
index 000000000..c055b32ac
--- /dev/null
+++ b/src/testbed/gnunet-service-testbed_connectionpool.h
@@ -0,0 +1,161 @@
+/*
+  This file is part of GNUnet.
+  (C) 2008--2013 Christian Grothoff (and other contributing authors)
+
+  GNUnet 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 3, or (at your
+  option) any later version.
+
+  GNUnet is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+  General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with GNUnet; see the file COPYING.  If not, write to the
+  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+  Boston, MA 02111-1307, USA.
+*/
+
+/**
+ * @file testbed/gnunet-service-testbed_connectionpool.h
+ * @brief Interface for connection pooling subroutines
+ * @author Sree Harsha Totakura <sreeharsha@totakura.in> 
+ */
+
+
+/**
+ * The request handle for obtaining a pooled connection
+ */
+struct GST_ConnectionPool_GetHandle;
+
+
+/**
+ * The type of service
+ */
+enum GST_ConnectionPool_Service
+{
+  /**
+   * Transport service
+   */
+  GST_CONNECTIONPOOL_SERVICE_TRANSPORT = 1,
+
+  /**
+   * Core service
+   */
+  GST_CONNECTIONPOOL_SERVICE_CORE
+};
+
+
+/**
+ * Initialise the connection pool.
+ *
+ * @param size the size of the connection pool.  Each entry in the connection
+ *   pool can handle a connection to each of the services enumerated in
+ *   #GST_ConnectionPool_Service
+ */
+void
+GST_connection_pool_init (unsigned int size);
+
+
+/**
+ * Cleanup the connection pool
+ */
+void
+GST_connection_pool_destroy ();
+
+/**
+ * Functions of this type are called when the needed handle is available for
+ * usage. These functions are to be registered with the function
+ * GST_connection_pool_get_handle(). The corresponding handles will be set upon
+ * success.  If they are not set, then it signals an error while opening the
+ * handles.
+ *
+ * @param cls the closure passed to GST_connection_pool_get_handle()
+ * @param ch the handle to CORE. Can be NULL if it is not requested
+ * @param th the handle to TRANSPORT. Can be NULL if it is not requested
+ * @param peer_id the identity of the peer. Will be NULL if ch is NULL. In other
+ *          cases, its value being NULL means that CORE connection has failed.
+ */
+typedef void 
+(*GST_connection_pool_connection_ready_cb) (void *cls,
+                                            struct GNUNET_CORE_Handle * ch,
+                                            struct GNUNET_TRANSPORT_Handle * th,
+                                            const struct GNUNET_PeerIdentity *
+                                            peer_id);
+
+
+/**
+ * Callback to notify when the target peer given to
+ * GST_connection_pool_get_handle() is connected.
+ *
+ * @param cls the closure given to GST_connection_pool_get_handle() for this
+ *   callback
+ * @param target the peer identity of the target peer
+ */
+typedef void
+(*GST_connection_pool_peer_connect_notify) (void *cls,
+                                            const struct GNUNET_PeerIdentity
+                                            *target);
+
+
+/**
+ * Get a connection handle to @a service.  If the connection is opened before
+ * and the connection handle is present in the connection pool, it is returned
+ * through @a cb.  @a peer_id is used for the lookup in the connection pool.  If
+ * the connection handle is not present in the connection pool, a new connection
+ * handle is opened for the @a service using @a cfg.  Additionally, @a target,
+ * @a connect_notify_cb can be specified to get notified when @a target is
+ * connected at @a service.
+ *
+ * @note @a connect_notify_cb will not be called if @a target is
+ * already connected @a service level. Use
+ * GNUNET_TRANSPORT_check_neighbour_connected() or a similar function from the
+ * respective @a service's API to check if the target peer is already connected or
+ * not. @a connect_notify_cb will be called only once or never (in case @a target
+ * cannot be connected or is already connected).
+ *
+ * @param peer_id the index of the peer
+ * @param cfg the configuration with which the transport handle has to be
+ *          created if it was not present in the cache
+ * @param service the service of interest
+ * @param cb the callback to notify when the transport handle is available
+ * @param cb_cls the closure for @a cb
+ * @param target the peer identify of the peer whose connection to our TRANSPORT
+ *          subsystem will be notified through the @a connect_notify_cb. Can be NULL
+ * @param connect_notify_cb the callback to call when the @a target peer is
+ *          connected. This callback will only be called once or never again (in
+ *          case the target peer cannot be connected). Can be NULL
+ * @param connect_notify_cb_cls the closure for @a connect_notify_cb
+ * @return the handle which can be used cancel or mark that the handle is no
+ *           longer being used
+ */
+struct GST_ConnectionPool_GetHandle *
+GST_connection_pool_get_handle (unsigned int peer_id,
+                                const struct GNUNET_CONFIGURATION_Handle *cfg,
+                                enum GST_ConnectionPool_Service service,
+                                GST_connection_pool_connection_ready_cb cb,
+                                void *cb_cls,
+                                const struct GNUNET_PeerIdentity *target,
+                                GST_connection_pool_peer_connect_notify connect_notify_cb,
+                                void *connect_notify_cb_cls);
+
+
+/**
+ * Relinquish a #GST_ConnectionPool_GetHandle object.  If the connection
+ * associated with the object is currently being used by other
+ * #GST_ConnectionPool_GetHandle objects, it is left in the connection pool.  If
+ * no other objects are using the connection and the connection pool is not full
+ * then it is placed in a LRU queue.  If the connection pool is full, then
+ * connections from the LRU queue are evicted and closed to create place for this
+ * connection.  If the connection pool if full and the LRU queue is empty, then
+ * the connection is closed.
+ *
+ * @param gh the handle
+ */
+void
+GST_connection_pool_get_handle_done (struct GST_ConnectionPool_GetHandle *gh);
+
+
+/* End of gnunet-service-testbed_connectionpool.h */