src/testbed/testbed_api_peers.c

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008--2012 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 testing/new_testing_api_peers.c
  23  * @brief management of the knowledge about peers in this library
  24  *        (we know the peer ID, its host, pending operations, etc.)
  25  * @author Christian Grothoff
  26  */
  27 #include "platform.h"
  28 #include "new_testing_api_peers.h"
  29
  30
  31 /**
  32  * Details about a peer; kept in a separate struct to avoid bloating
  33  * memory consumption everywhere...
  34  */
  35 struct PeerDetails
  36 {
  37   /**
  38    * Configuration of the peer; NULL if we are not sure what the peer's correct
  39    * configuration actually is; non-NULL if this peer is controlled by this
  40    * process.
  41    */
  42   struct GNUNET_CONFIGURATION_Handle *cfg;
  43
  44   /**
  45    * If this process has started this peer's ARM process, this is the handle
  46    * to the 'gnunet-service-arm' process of the peer.
  47    */
  48   struct GNUNET_OS_Process *arm;
  49
  50   // ...
  51
  52 };
  53
  54
  55 /**
  56  * A peer controlled by the testing framework.  A peer runs
  57  * at a particular host.
  58  */
  59 struct GNUNET_TESTBED_Peer
  60 {
  61   /**
  62    * Our controller context (not necessarily the controller
  63    * that is responsible for starting/running the peer!).
  64    */
  65   struct GNUNET_TESTBED_Controller *controller;
  66
  67   /**
  68    * Which host does this peer run on?
  69    */
  70   struct GNUENT_TESTING_Host *host;
  71
  72   /**
  73    * Globally unique ID of the peer.
  74    */
  75   uint32_t unique_id;
  76
  77   /**
  78    * Internals of the peer for the controlling process; NULL if
  79    * this process is not controlling this peer.
  80    */
  81   struct PeerDetails *details;
  82
  83 };
  84
  85
  86 /**
  87  * Lookup a peer by ID.
  88  *
  89  * @param id global peer ID assigned to the peer
  90  * @return handle to the host, NULL on error
  91  */
  92 struct GNUNET_TESTBED_Peer *
  93 GNUNET_TESTBED_peer_lookup_by_id_ (uint32_t id)
  94 {
  95   GNUNET_break (0);
  96   return NULL;
  97 }
  98
  99
 100 /**
 101  * Create the given peer at the specified host using the given
 102  * controller.  If the given controller is not running on the target
 103  * host, it should find or create a controller at the target host and
 104  * delegate creating the peer.  Explicit delegation paths can be setup
 105  * using 'GNUNET_TESTBED_controller_link'.  If no explicit delegation
 106  * path exists, a direct link with a subordinate controller is setup
 107  * for the first delegated peer to a particular host; the subordinate
 108  * controller is then destroyed once the last peer that was delegated
 109  * to the remote host is stopped.  This function is used in particular
 110  * if some other controller has already assigned a unique ID to the
 111  * peer.
 112  *
 113  * Creating the peer only creates the handle to manipulate and further
 114  * configure the peer; use "GNUNET_TESTBED_peer_start" and
 115  * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's
 116  * processes.
 117  *
 118  * Note that the given configuration will be adjusted by the
 119  * controller to avoid port/path conflicts with other peers.
 120  * The "final" configuration can be obtained using
 121  * 'GNUNET_TESTBED_peer_get_information'.
 122  *
 123  * @param unique_id unique ID for this peer
 124  * @param controller controller process to use
 125  * @param host host to run the peer on
 126  * @param cfg configuration to use for the peer
 127  * @return handle to the peer (actual startup will happen asynchronously)
 128  */
 129 struct GNUNET_TESTBED_Peer *
 130 GNUNET_TESTBED_peer_create_with_id_ (uint32_t unique_id,
 131                                      struct GNUNET_TESTBED_Controller *controller,
 132                                      struct GNUNET_TESTBED_Host *host,
 133                                      const struct GNUNET_CONFIGURATION_Handle *cfg)
 134 {
 135   // FIXME: create locally or delegate...
 136   GNUNET_break (0);
 137   return NULL;
 138 }
 139
 140
 141 /**
 142  * Create the given peer at the specified host using the given
 143  * controller.  If the given controller is not running on the target
 144  * host, it should find or create a controller at the target host and
 145  * delegate creating the peer.  Explicit delegation paths can be setup
 146  * using 'GNUNET_TESTBED_controller_link'.  If no explicit delegation
 147  * path exists, a direct link with a subordinate controller is setup
 148  * for the first delegated peer to a particular host; the subordinate
 149  * controller is then destroyed once the last peer that was delegated
 150  * to the remote host is stopped.
 151  *
 152  * Creating the peer only creates the handle to manipulate and further
 153  * configure the peer; use "GNUNET_TESTBED_peer_start" and
 154  * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's
 155  * processes.
 156  *
 157  * Note that the given configuration will be adjusted by the
 158  * controller to avoid port/path conflicts with other peers.
 159  * The "final" configuration can be obtained using
 160  * 'GNUNET_TESTBED_peer_get_information'.
 161  *
 162  * @param controller controller process to use
 163  * @param host host to run the peer on
 164  * @param cfg configuration to use for the peer
 165  * @return handle to the peer (actual startup will happen asynchronously)
 166  */
 167 struct GNUNET_TESTBED_Peer *
 168 GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller,
 169                             struct GNUNET_TESTBED_Host *host,
 170                             const struct GNUNET_CONFIGURATION_Handle *cfg)
 171 {
 172   static uint32_t id_gen;
 173
 174   return GNUNET_TESTBED_peer_create_with_id_ (++id_gen,
 175                                               controller,
 176                                               host,
 177                                               cfg);
 178 }
 179
 180
 181 /**
 182  * Start the given peer.
 183  *
 184  * @param peer peer to start
 185  * @return handle to the operation
 186  */
 187 struct GNUNET_TESTBED_Operation *
 188 GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer)
 189 {
 190   // FIXME: start locally or delegate...
 191   GNUNET_break (0);
 192   return NULL;
 193 }
 194
 195
 196 /**
 197  * Stop the given peer.  The handle remains valid (use
 198  * "GNUNET_TESTBED_peer_destroy" to fully clean up the
 199  * state of the peer).
 200  *
 201  * @param peer peer to stop
 202  * @return handle to the operation
 203  */
 204 struct GNUNET_TESTBED_Operation *
 205 GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer)
 206 {
 207   // FIXME: stop locally or delegate...
 208   GNUNET_break (0);
 209   return NULL;
 210 }
 211
 212
 213 /**
 214  * Request information about a peer.
 215  *
 216  * @param peer peer to request information about
 217  * @param pit desired information
 218  * @return handle to the operation
 219  */
 220 struct GNUNET_TESTBED_Operation *
 221 GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer,
 222                                      enum GNUNET_TESTBED_PeerInformationType pit)
 223 {
 224   // FIXME: handle locally or delegate...
 225   GNUNET_break (0);
 226   return NULL;
 227 }
 228
 229
 230 /**
 231  * Change peer configuration.  Must only be called while the
 232  * peer is stopped.  Ports and paths cannot be changed this
 233  * way.
 234  *
 235  * @param peer peer to change configuration for
 236  * @param cfg new configuration (differences to existing
 237  *            configuration only)
 238  * @return handle to the operation
 239  */
 240 struct GNUNET_TESTBED_Operation *
 241 GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer,
 242                                           const struct GNUNET_CONFIGURATION_Handle *cfg)
 243 {
 244   // FIXME: handle locally or delegate...
 245   GNUNET_break (0);
 246   return NULL;
 247 }
 248
 249
 250 /**
 251  * Manipulate the P2P underlay topology by configuring a link
 252  * between two peers.
 253  *
 254  * @param op_cls closure argument to give with the operation event
 255  * @param p1 first peer
 256  * @param p2 second peer
 257  * @param co option to change
 258  * @param ... option-specific values
 259  * @return handle to the operation, NULL if configuring the link at this
 260  *         time is not allowed
 261  */
 262 struct GNUNET_TESTBED_Operation *
 263 GNUNET_TESTBED_underlay_configure_link (void *op_cls,
 264                                         struct GNUNET_TESTBED_Peer *p1,
 265                                         struct GNUNET_TESTBED_Peer *p2,
 266                                         enum GNUNET_TESTBED_ConnectOption co, ...)
 267 {
 268   GNUNET_break (0);
 269   return NULL;
 270 }
 271
 272
 273
 274 /**
 275  * Both peers must have been started before calling this function.
 276  * This function then obtains a HELLO from 'p1', gives it to 'p2'
 277  * and asks 'p2' to connect to 'p1'.
 278  *
 279  * @param op_cls closure argument to give with the operation event
 280  * @param p1 first peer
 281  * @param p2 second peer
 282  * @return handle to the operation, NULL if connecting these two
 283  *         peers is fundamentally not possible at this time (peers
 284  *         not running or underlay disallows)
 285  */
 286 struct GNUNET_TESTBED_Operation *
 287 GNUNET_TESTBED_overlay_connect (void *op_cls,
 288                                 struct GNUNET_TESTBED_Peer *p1,
 289                                 struct GNUNET_TESTBED_Peer *p2)
 290 {
 291   GNUNET_break (0);
 292   return NULL;
 293 }
 294
 295
 296
 297 /* end of new_testing_api_peers.c */