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