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