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