src/testbed/gnunet-service-testbed_connectionpool.h

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