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
   6   it under the terms of the GNU General Public License as published
   7   by the Free Software Foundation; either version 3, or (at your
   8   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   General Public License for more details.
  14
  15   You should have received a copy of the GNU General Public License
  16   along with GNUnet; see the file COPYING.  If not, write to the
  17   Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18   Boston, MA 02110-1301, USA.
  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_core_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
  91 (*GST_connection_pool_connection_ready_cb) (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
 108 (*GST_connection_pool_peer_connect_notify) (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 or
 125  * not. @a connect_notify_cb will be called only once or never (in case @a target
 126  * 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 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 (unsigned int peer_id,
 145                                 const struct GNUNET_CONFIGURATION_Handle *cfg,
 146                                 enum GST_ConnectionPool_Service service,
 147                                 GST_connection_pool_connection_ready_cb cb,
 148                                 void *cb_cls,
 149                                 const struct GNUNET_PeerIdentity *target,
 150                                 GST_connection_pool_peer_connect_notify connect_notify_cb,
 151                                 void *connect_notify_cb_cls);
 152
 153
 154 /**
 155  * Relinquish a #GST_ConnectionPool_GetHandle object.  If the connection
 156  * associated with the object is currently being used by other
 157  * #GST_ConnectionPool_GetHandle objects, it is left in the connection pool.  If
 158  * no other objects are using the connection and the connection pool is not full
 159  * then it is placed in a LRU queue.  If the connection pool is full, then
 160  * connections from the LRU queue are evicted and closed to create place for this
 161  * connection.  If the connection pool if full and the LRU queue is empty, then
 162  * the connection is closed.
 163  *
 164  * @param gh the handle
 165  */
 166 void
 167 GST_connection_pool_get_handle_done (struct GST_ConnectionPool_GetHandle *gh);
 168
 169
 170 /* End of gnunet-service-testbed_connectionpool.h */