src/testbed/gnunet-service-testbed_links.h

   1 /*
   2   This file is part of GNUnet.
   3   Copyright (C) 2008--2013 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_links.h
  21  * @brief TESTBED service components that deals with starting slave controllers
  22  *          and establishing lateral links between controllers
  23  * @author Sree Harsha Totakura
  24  */
  25
  26
  27 /**
  28  * A connected controller which is not our child
  29  */
  30 struct Neighbour;
  31
  32
  33 /**
  34  * Structure representing a connected(directly-linked) controller
  35  */
  36 struct Slave
  37 {
  38   /**
  39    * The controller process handle if we had started the controller
  40    */
  41   struct GNUNET_TESTBED_ControllerProc *controller_proc;
  42
  43   /**
  44    * The controller handle
  45    */
  46   struct GNUNET_TESTBED_Controller *controller;
  47
  48   /**
  49    * handle to lcc which is associated with this slave startup. Should be set to
  50    * NULL when the slave has successfully started up
  51    */
  52   struct LinkControllersContext *lcc;
  53
  54   /**
  55    * Head of the host registration DLL
  56    */
  57   struct HostRegistration *hr_dll_head;
  58
  59   /**
  60    * Tail of the host registration DLL
  61    */
  62   struct HostRegistration *hr_dll_tail;
  63
  64   /**
  65    * The current host registration handle
  66    */
  67   struct GNUNET_TESTBED_HostRegistrationHandle *rhandle;
  68
  69   /**
  70    * Hashmap to hold Registered host contexts
  71    */
  72   struct GNUNET_CONTAINER_MultiHashMap *reghost_map;
  73
  74   /**
  75    * The id of the host this controller is running on
  76    */
  77   uint32_t host_id;
  78 };
  79
  80 /**
  81  * A list of directly linked neighbours
  82  */
  83 extern struct Slave **GST_slave_list;
  84
  85 /**
  86  * The size of directly linked neighbours list
  87  */
  88 extern unsigned int GST_slave_list_size;
  89
  90
  91 /**
  92  * Cleans up the neighbour list
  93  */
  94 void
  95 GST_neighbour_list_clean (void);
  96
  97
  98 /**
  99  * Get a neighbour from the neighbour list
 100  *
 101  * @param id the index of the neighbour in the neighbour list
 102  * @return the Neighbour; NULL if the given index in invalid (index greater than
 103  *           the list size or neighbour at that index is NULL)
 104  */
 105 struct Neighbour *
 106 GST_get_neighbour (uint32_t id);
 107
 108
 109 /**
 110  * Function to cleanup the neighbour connect contexts
 111  */
 112 void
 113 GST_free_nccq (void);
 114
 115
 116 /**
 117  * Notification context to be used to notify when connection to the neighbour's
 118  * controller is opened
 119  */
 120 struct NeighbourConnectNotification;
 121
 122
 123 /**
 124  * The notification callback to call when we are connect to neighbour
 125  *
 126  * @param cls the closure given to GST_neighbour_get_connection()
 127  * @param controller the controller handle to the neighbour
 128  */
 129 typedef void
 130 (*GST_NeigbourConnectNotifyCallback) (void *cls,
 131                                       struct GNUNET_TESTBED_Controller *controller);
 132
 133
 134 /**
 135  * Try to open a connection to the given neigbour.  If the connection is open
 136  * already, then it is re-used.  If not, the request is queued in the operation
 137  * queues responsible for bounding the total number of file descriptors.  The
 138  * actual connection will happen when the operation queue marks the
 139  * corresponding operation as active.
 140  *
 141  * @param n the neighbour to open a connection to
 142  * @param cb the notification callback to call when the connection is opened
 143  * @param cb_cls the closure for the above callback
 144  */
 145 struct NeighbourConnectNotification *
 146 GST_neighbour_get_connection (struct Neighbour *n,
 147                               GST_NeigbourConnectNotifyCallback cb,
 148                               void *cb_cls);
 149
 150
 151 /**
 152  * Cancel the request for opening a connection to the neighbour
 153  *
 154  * @param h the notification handle
 155  */
 156 void
 157 GST_neighbour_get_connection_cancel (struct NeighbourConnectNotification *h);
 158
 159
 160 /**
 161  * Release the connection to the neighbour.  The actual connection will be
 162  * closed if connections to other neighbour are waiting (to maintain a bound on
 163  * the total number of connections that are open).
 164  *
 165  * @param n the neighbour whose connection can be closed
 166  */
 167 void
 168 GST_neighbour_release_connection (struct Neighbour *n);
 169
 170
 171 /**
 172  * Function to create a neigbour and add it into the neighbour list
 173  *
 174  * @param host the host of the neighbour
 175  */
 176 struct Neighbour *
 177 GST_create_neighbour (struct GNUNET_TESTBED_Host *host);
 178
 179
 180 /**
 181  * Message handler for #GNUNET_MESSAGE_TYPE_TESTBED_LCONTROLLERS message
 182  *
 183  * @param cls identification of the client
 184  * @param msg the actual message
 185  */
 186 void
 187 handle_link_controllers (void *cls,
 188                          const struct GNUNET_TESTBED_ControllerLinkRequest *msg);
 189
 190
 191 /**
 192  * Clean up @a client handle if we stored any via #handle_link_controllers(),
 193  * the given client disconnected.
 194  *
 195  * @param client the client that is history
 196  */
 197 void
 198 GST_link_notify_disconnect (struct GNUNET_SERVICE_Client *client);
 199
 200
 201 /**
 202  * Cleans up the slave list
 203  */
 204 void
 205 GST_slave_list_clear (void);