src/testbed/gnunet-service-testbed_connectionpool.h

   1 /*
   2   This file is part of GNUnet.
   3   Copyright (C) 2008--2015 GNUnet e.V.
   4
   5   GNUnet is free software: you can redistribute it and/or modify it
   6   under the terms of the GNU Affero General Public License as published
   7   by the Free Software Foundation, either version 3 of the License,
   8   or (at your option) any later version.
   9
  10   GNUnet is distributed in the hope that it will be useful, but
  11   WITHOUT ANY WARRANTY; without even the implied warranty of
  12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13   Affero General Public License for more details.
  14
  15   You should have received a copy of the GNU Affero General Public License
  16   along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @file testbed/gnunet-service-testbed_connectionpool.h
  21  * @brief Interface for connection pooling subroutines
  22  * @author Sree Harsha Totakura <sreeharsha@totakura.in>
  23  */
  24 #include "gnunet_ats_service.h"
  25 #include "gnunet_core_service.h"
  26 #include "gnunet_transport_core_service.h"
  27
  28 /**
  29  * The request handle for obtaining a pooled connection
  30  */
  31 struct GST_ConnectionPool_GetHandle;
  32
  33
  34 /**
  35  * The type of service
  36  */
  37 enum GST_ConnectionPool_Service
  38 {
  39   /**
  40    * Transport service
  41    */
  42   GST_CONNECTIONPOOL_SERVICE_TRANSPORT = 1,
  43
  44   /**
  45    * Core service
  46    */
  47   GST_CONNECTIONPOOL_SERVICE_CORE,
  48
  49   /**
  50    * ATS service
  51    */
  52   GST_CONNECTIONPOOL_SERVICE_ATS_CONNECTIVITY
  53 };
  54
  55
  56 /**
  57  * Initialise the connection pool.
  58  *
  59  * @param size the size of the connection pool.  Each entry in the connection
  60  *   pool can handle a connection to each of the services enumerated in
  61  *   #GST_ConnectionPool_Service
  62  */
  63 void
  64 GST_connection_pool_init (unsigned int size);
  65
  66
  67 /**
  68  * Cleanup the connection pool
  69  */
  70 void
  71 GST_connection_pool_destroy (void);
  72
  73 /**
  74  * Functions of this type are called when the needed handle is available for
  75  * usage. These functions are to be registered with the function
  76  * GST_connection_pool_get_handle(). The corresponding handles will be set upon
  77  * success.  If they are not set, then it signals an error while opening the
  78  * handles.
  79  *
  80  * @param cls the closure passed to GST_connection_pool_get_handle()
  81  * @param ch the handle to CORE. Can be NULL if it is not requested
  82  * @param th the handle to TRANSPORT. Can be NULL if it is not requested
  83  * @param ac the handle to ATS, can be NULL if it is not requested
  84  * @param peer_id the identity of the peer. Will be NULL if ch is NULL. In other
  85  *          cases, its value being NULL means that CORE connection has failed.
  86  * @param cfg configuration of the peer
  87  */
  88 typedef void
  89 (*GST_connection_pool_connection_ready_cb) (void *cls,
  90                                             struct GNUNET_CORE_Handle *ch,
  91                                             struct GNUNET_TRANSPORT_CoreHandle *th,
  92                                             struct GNUNET_ATS_ConnectivityHandle *ac,
  93                                             const struct GNUNET_PeerIdentity *peer_id,
  94                                             const struct GNUNET_CONFIGURATION_Handle *cfg);
  95
  96
  97 /**
  98  * Callback to notify when the target peer given to
  99  * GST_connection_pool_get_handle() is connected.
 100  *
 101  * @param cls the closure given to GST_connection_pool_get_handle() for this
 102  *   callback
 103  * @param target the peer identity of the target peer
 104  */
 105 typedef void
 106 (*GST_connection_pool_peer_connect_notify) (void *cls,
 107                                             const struct GNUNET_PeerIdentity *target);
 108
 109
 110 /**
 111  * Get a connection handle to @a service.  If the connection is opened before
 112  * and the connection handle is present in the connection pool, it is returned
 113  * through @a cb.  @a peer_id is used for the lookup in the connection pool.  If
 114  * the connection handle is not present in the connection pool, a new connection
 115  * handle is opened for the @a service using @a cfg.  Additionally, @a target,
 116  * @a connect_notify_cb can be specified to get notified when @a target is
 117  * connected at @a service.
 118  *
 119  * @note @a connect_notify_cb will not be called if @a target is
 120  * already connected @a service level. Use
 121  * GNUNET_TRANSPORT_check_peer_connected() or a similar function from the
 122  * respective @a service's API to check if the target peer is already connected or
 123  * not. @a connect_notify_cb will be called only once or never (in case @a target
 124  * cannot be connected or is already connected).
 125  *
 126  * @param peer_id the index of the peer
 127  * @param cfg the configuration with which the transport handle has to be
 128  *          created if it was not present in the cache
 129  * @param service the service of interest
 130  * @param cb the callback to notify when the transport handle is available
 131  * @param cb_cls the closure for @a cb
 132  * @param target the peer identify of the peer whose connection to our TRANSPORT
 133  *          subsystem will be notified through the @a connect_notify_cb. Can be NULL
 134  * @param connect_notify_cb the callback to call when the @a target peer is
 135  *          connected. This callback will only be called once or never again (in
 136  *          case the target peer cannot be connected). Can be NULL
 137  * @param connect_notify_cb_cls the closure for @a connect_notify_cb
 138  * @return the handle which can be used cancel or mark that the handle is no
 139  *           longer being used
 140  */
 141 struct GST_ConnectionPool_GetHandle *
 142 GST_connection_pool_get_handle (unsigned int peer_id,
 143                                 const struct GNUNET_CONFIGURATION_Handle *cfg,
 144                                 enum GST_ConnectionPool_Service service,
 145                                 GST_connection_pool_connection_ready_cb cb,
 146                                 void *cb_cls,
 147                                 const struct GNUNET_PeerIdentity *target,
 148                                 GST_connection_pool_peer_connect_notify connect_notify_cb,
 149                                 void *connect_notify_cb_cls);
 150
 151
 152 /**
 153  * Relinquish a #GST_ConnectionPool_GetHandle object.  If the connection
 154  * associated with the object is currently being used by other
 155  * #GST_ConnectionPool_GetHandle objects, it is left in the connection pool.  If
 156  * no other objects are using the connection and the connection pool is not full
 157  * then it is placed in a LRU queue.  If the connection pool is full, then
 158  * connections from the LRU queue are evicted and closed to create place for this
 159  * connection.  If the connection pool if full and the LRU queue is empty, then
 160  * the connection is closed.
 161  *
 162  * @param gh the handle
 163  */
 164 void
 165 GST_connection_pool_get_handle_done (struct GST_ConnectionPool_GetHandle *gh);
 166
 167
 168 /* End of gnunet-service-testbed_connectionpool.h */