src/include/gnunet_testbed_service.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008, 2009, 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 include/gnunet_testbed_service.h
  23  * @brief API for writing tests and creating large-scale
  24  *        emulation testbeds for GNUnet.
  25  * @author Christian Grothoff
  26  */
  27
  28 #ifndef GNUNET_TESTBED_SERVICE_H
  29 #define GNUNET_TESTBED_SERVICE_H
  30
  31 #include "gnunet_util_lib.h"
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41
  42 /**
  43  * Opaque handle to a host running experiments managed by the testbed framework.
  44  * The master process must be able to SSH to this host without password (via
  45  * ssh-agent).
  46  */
  47 struct GNUNET_TESTBED_Host;
  48
  49 /**
  50  * Opaque handle to a peer controlled by the testbed framework.  A peer runs
  51  * at a particular host.
  52  */
  53 struct GNUNET_TESTBED_Peer;
  54
  55 /**
  56  * Opaque handle to an abstract operation to be executed by the testbed framework.
  57  */
  58 struct GNUNET_TESTBED_Operation;
  59
  60 /**
  61  * Handle to interact with a GNUnet testbed controller.  Each controller has at
  62  * least one master handle which is created when the controller is created; this
  63  * master handle interacts with the controller via stdin/stdout of the controller
  64  * process.  Additionally, controllers can interact with each other (in a P2P
  65  * fashion); those links are established via TCP/IP on the controller's service
  66  * port.
  67  */
  68 struct GNUNET_TESTBED_Controller;
  69
  70 /**
  71  * Handle to a large-scale testbed that is managed at a high level.
  72  */
  73 struct GNUNET_TESTBED_Testbed;
  74
  75
  76 /**
  77  * Create a host to run peers and controllers on.
  78  *
  79  * @param hostname name of the host, use "NULL" for localhost
  80  * @param username username to use for the login; may be NULL
  81  * @param port port number to use for ssh; use 0 to let ssh decide
  82  * @return handle to the host, NULL on error
  83  */
  84 struct GNUNET_TESTBED_Host *
  85 GNUNET_TESTBED_host_create (const char *hostname,
  86                             const char *username,
  87                             uint16_t port);
  88
  89
  90 /**
  91  * Load a set of hosts from a configuration file.
  92  *
  93  * @param filename file with the host specification
  94  * @param hosts set to the hosts found in the file
  95  * @return number of hosts returned in 'hosts', 0 on error
  96  */
  97 unsigned int
  98 GNUNET_TESTBED_hosts_load_from_file (const char *filename,
  99                                      struct GNUNET_TESTBED_Host **hosts);
 100
 101
 102 /**
 103  * Destroy a host handle.  Must only be called once everything
 104  * running on that host has been stopped.
 105  *
 106  * @param host handle to destroy
 107  */
 108 void
 109 GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host);
 110
 111
 112 /**
 113  * Enumeration with (at most 64) possible event types that
 114  * can be monitored using the testbed framework.
 115  */
 116 enum GNUNET_TESTBED_EventType
 117 {
 118   /**
 119    * A peer has been started.
 120    */
 121   GNUNET_TESTBED_ET_PEER_START = 0,
 122
 123   /**
 124    * A peer has been stopped.
 125    */
 126   GNUNET_TESTBED_ET_PEER_STOP = 1,
 127
 128   /**
 129    * A connection between two peers was established.
 130    */
 131   GNUNET_TESTBED_ET_CONNECT = 2,
 132
 133   /**
 134    * A connection between two peers was torn down.
 135    */
 136   GNUNET_TESTBED_ET_DISCONNECT = 3,
 137
 138   /**
 139    * A requested testbed operation has been completed.
 140    */
 141   GNUNET_TESTBED_ET_OPERATION_FINISHED = 4,
 142
 143   /**
 144    * The 'GNUNET_TESTBED_run' operation has been completed
 145    */
 146   GNUNET_TESTBED_ET_TESTBED_ONLINE = 5
 147
 148 };
 149
 150
 151 /**
 152  * Types of information that can be requested about a peer.
 153  */
 154 enum GNUNET_TESTBED_PeerInformationType
 155 {
 156
 157   /**
 158    * Special value (not valid for requesting information)
 159    * that is used in the event struct if a 'generic' pointer
 160    * is returned (for other operations not related to this
 161    * enumeration).
 162    */
 163   GNUNET_TESTBED_PIT_GENERIC = 0,
 164
 165   /**
 166    * What host is the peer running on?  Returns a 'const struct
 167    * GNUNET_TESTBED_Host *'.  Valid until
 168    * 'GNUNET_TESTBED_operation_done' is called.
 169    */
 170   GNUNET_TESTBED_PIT_HOST,
 171
 172   /**
 173    * What configuration is the peer using?  Returns a 'const struct
 174    * GNUNET_CONFIGURATION_Handle *'.  Valid until
 175    * 'GNUNET_TESTNIG_operation_done' is called.  However, the
 176    * values may be inaccurate if the peer is reconfigured in
 177    * the meantime.
 178    */
 179   GNUNET_TESTBED_PIT_CONFIGURATION,
 180
 181   /**
 182    * What is the identity of the peer?  Returns a
 183    * 'const struct GNUNET_PeerIdentity *'.  Valid until
 184    * 'GNUNET_TESTNIG_operation_done' is called.
 185    */
 186   GNUNET_TESTBED_PIT_IDENTITY
 187
 188 };
 189
 190
 191 /**
 192  * Argument to GNUNET_TESTBED_ControllerCallback with details about
 193  * the event.
 194  */
 195 struct GNUNET_TESTBED_EventInformation
 196 {
 197
 198   /**
 199    * Type of the event.
 200    */
 201   enum GNUNET_TESTBED_EventType type;
 202
 203   /**
 204    * Details about the event.
 205    */
 206   union
 207   {
 208
 209     /**
 210      * Details about peer start event.
 211      */
 212     struct
 213     {
 214       /**
 215        * Handle for the host where the peer
 216        * was started.
 217        */
 218       struct GNUNET_TESTBED_Host *host;
 219
 220       /**
 221        * Handle for the peer that was started.
 222        */
 223       struct GNUNET_TESTBED_Peer *peer;
 224
 225     } peer_start;
 226
 227     /**
 228      * Details about peer stop event.
 229      */
 230     struct
 231     {
 232
 233       /**
 234        * Handle for the peer that was started.
 235        */
 236       struct GNUNET_TESTBED_Peer *peer;
 237
 238     } peer_stop;
 239
 240     /**
 241      * Details about connect event.
 242      */
 243     struct
 244     {
 245       /**
 246        * Handle for one of the connected peers.
 247        */
 248       struct GNUNET_TESTBED_Peer *peer1;
 249
 250       /**
 251        * Handle for one of the connected peers.
 252        */
 253       struct GNUNET_TESTBED_Peer *peer2;
 254
 255     } peer_connect;
 256
 257     /**
 258      * Details about disconnect event.
 259      */
 260     struct
 261     {
 262       /**
 263        * Handle for one of the disconnected peers.
 264        */
 265       struct GNUNET_TESTBED_Peer *peer1;
 266
 267       /**
 268        * Handle for one of the disconnected peers.
 269        */
 270       struct GNUNET_TESTBED_Peer *peer2;
 271
 272     } peer_disconnect;
 273
 274     /**
 275      * Details about an operation finished event.
 276      */
 277     struct
 278     {
 279
 280       /**
 281        * Handle for the operation that was finished.
 282        */
 283       struct GNUNET_TESTBED_Operation *operation;
 284
 285       /**
 286        * Closure that was passed in when the event was
 287        * requested.
 288        */
 289       void *op_cls;
 290
 291       /**
 292        * Error message for the operation, NULL on success.
 293        */
 294       const char *emsg;
 295
 296       /**
 297        * Peer information type; captures which of the types
 298        * in the 'op_result' is actually in use.
 299        */
 300       enum GNUNET_TESTBED_PeerInformationType pit;
 301
 302       /**
 303        * Pointer to an operation-specific return value; NULL on error;
 304        * can be NULL for certain operations.  Valid until
 305        * 'GNUNET_TESTBED_operation_done' is called.
 306        */
 307       union
 308       {
 309         /**
 310          * No result (NULL pointer) or generic result
 311          * (whatever the GNUNET_TESTBED_ConnectAdapter returned).
 312          */
 313         void *generic;
 314
 315         /**
 316          * Identity of host running the peer.
 317          */
 318         struct GNUNET_TESTBED_Host *host;
 319
 320         /**
 321          * Identity of the peer.
 322          */
 323         const struct GNUNET_PeerIdentity *pid;
 324
 325         /**
 326          * Configuration of the peer.
 327          */
 328         const struct GNUNET_CONFIGURATION_Handle *cfg;
 329
 330       } op_result;
 331
 332     } operation_finished;
 333
 334
 335     /**
 336      * Details about an testbed run completed event.
 337      */
 338     struct
 339     {
 340
 341       /**
 342        * Error message for the operation, NULL on success.
 343        */
 344       const char *emsg;
 345
 346       /**
 347        * Array of peers now running (valid until
 348        * 'GNUNET_TESTBED_testbed_stop' is called).  Note that it is
 349        * not allowed to call 'GNUNET_TESTBED_peer_destroy' on peers
 350        * from this array.
 351        */
 352       struct GNUNET_TESTBED_Peer **peers;
 353
 354       /**
 355        * Size of the 'peers' array.
 356        */
 357       unsigned int num_peers;
 358
 359     } testbed_run_finished;
 360
 361   } details;
 362
 363 };
 364
 365
 366 /**
 367  * Signature of the event handler function called by the
 368  * respective event controller.
 369  *
 370  * @param cls closure
 371  * @param event information about the event
 372  */
 373 typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls,
 374                                                   const struct GNUNET_TESTBED_EventInformation *event);
 375
 376
 377 /**
 378  * Start a controller process using the given configuration at the
 379  * given host.
 380  *
 381  * @param cfg configuration to use
 382  * @param host host to run the controller on, NULL for 'localhost'
 383  * @param event_mask bit mask with set of events to call 'cc' for;
 384  *                   or-ed values of "1LL" shifted by the
 385  *                   respective 'enum GNUNET_TESTBED_EventType'
 386  *                   (i.e.  "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...")
 387  * @param cc controller callback to invoke on events
 388  * @param cc_cls closure for cc
 389  * @return handle to the controller
 390  */
 391 struct GNUNET_TESTBED_Controller *
 392 GNUNET_TESTBED_controller_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 393                                  struct GNUNET_TESTBED_Host *host,
 394                                  uint64_t event_mask,
 395                                  GNUNET_TESTBED_ControllerCallback cc,
 396                                  void *cc_cls);
 397
 398
 399 /**
 400  * Configure shared services at a controller.  Using this function,
 401  * you can specify that certain services (such as "resolver")
 402  * should not be run for each peer but instead be shared
 403  * across N peers on the specified host.  This function
 404  * must be called before any peers are created at the host.
 405  *
 406  * @param controller controller to configure
 407  * @param service_name name of the service to share
 408  * @param num_peers number of peers that should share one instance
 409  *        of the specified service (1 for no sharing is the default),
 410  *        use 0 to disable the service
 411  */
 412 void
 413 GNUNET_TESTBED_controller_configure_sharing (struct GNUNET_TESTBED_Controller *controller,
 414                                              const char *service_name,
 415                                              uint32_t num_peers);
 416
 417
 418 /**
 419  * Stop the given controller (also will terminate all peers and
 420  * controllers dependent on this controller).  This function
 421  * blocks until the testbed has been fully terminated (!).
 422  *
 423  * @param controller handle to controller to stop
 424  */
 425 void
 426 GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_Controller *controller);
 427
 428
 429 /**
 430  * Create a link from a 'master' controller to a slave controller.
 431  * Whenever the master controller is asked to start a peer at the
 432  * given 'delegated_host', it will delegate the request to the
 433  * specified slave controller.  Note that the slave controller runs at
 434  * the 'slave_host', which may or may not be the same host as the
 435  * 'delegated_host' (for hierarchical delegations).  The configuration
 436  * of the slave controller is given and to be used to either create
 437  * the slave controller or to connect to an existing slave controller
 438  * process.  'is_subordinate' specifies if the given slave controller
 439  * should be started and managed by the master controller, or if the
 440  * slave already has a master and this is just a secondary master that
 441  * is also allowed to use the existing slave.
 442  *
 443  * @param master handle to the master controller who creates the association
 444  * @param delegated_host requests to which host should be delegated
 445  * @param slave_host which host is used to run the slave controller
 446  * @param slave_cfg configuration to use for the slave controller
 447  * @param is_subordinate GNUNET_YES if the slave should be started (and stopped)
 448  *                       by the master controller; GNUNET_NO if we are just
 449  *                       allowed to use the slave via TCP/IP
 450  */
 451 void
 452 GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master,
 453                                 struct GNUNET_TESTBED_Host *delegated_host,
 454                                 struct GNUNET_TESTBED_Host *slave_host,
 455                                 const struct GNUNET_CONFIGURATION_Handle *slave_cfg,
 456                                 int is_subordinate);
 457
 458
 459 /**
 460  * Create the given peer at the specified host using the given
 461  * controller.  If the given controller is not running on the target
 462  * host, it should find or create a controller at the target host and
 463  * delegate creating the peer.  Explicit delegation paths can be setup
 464  * using 'GNUNET_TESTBED_controller_link'.  If no explicit delegation
 465  * path exists, a direct link with a subordinate controller is setup
 466  * for the first delegated peer to a particular host; the subordinate
 467  * controller is then destroyed once the last peer that was delegated
 468  * to the remote host is stopped.
 469  *
 470  * Creating the peer only creates the handle to manipulate and further
 471  * configure the peer; use "GNUNET_TESTBED_peer_start" and
 472  * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's
 473  * processes.
 474  *
 475  * Note that the given configuration will be adjusted by the
 476  * controller to avoid port/path conflicts with other peers.
 477  * The "final" configuration can be obtained using
 478  * 'GNUNET_TESTBED_peer_get_information'.
 479  *
 480  * @param controller controller process to use
 481  * @param host host to run the peer on
 482  * @param cfg configuration to use for the peer
 483  * @return handle to the peer (actual startup will happen asynchronously)
 484  */
 485 struct GNUNET_TESTBED_Peer *
 486 GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller,
 487                             struct GNUNET_TESTBED_Host *host,
 488                             const struct GNUNET_CONFIGURATION_Handle *cfg);
 489
 490
 491 /**
 492  * Start the given peer.
 493  *
 494  * @param peer peer to start
 495  * @return handle to the operation
 496  */
 497 struct GNUNET_TESTBED_Operation *
 498 GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer);
 499
 500
 501 /**
 502  * Stop the given peer.  The handle remains valid (use
 503  * "GNUNET_TESTBED_peer_destroy" to fully clean up the
 504  * state of the peer).
 505  *
 506  * @param peer peer to stop
 507  * @return handle to the operation
 508  */
 509 struct GNUNET_TESTBED_Operation *
 510 GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer);
 511
 512
 513 /**
 514  * Request information about a peer.
 515  *
 516  * @param peer peer to request information about
 517  * @param pit desired information
 518  * @return handle to the operation
 519  */
 520 struct GNUNET_TESTBED_Operation *
 521 GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer,
 522                                      enum GNUNET_TESTBED_PeerInformationType pit);
 523
 524
 525 /**
 526  * Change peer configuration.  Must only be called while the
 527  * peer is stopped.  Ports and paths cannot be changed this
 528  * way.
 529  *
 530  * @param peer peer to change configuration for
 531  * @param cfg new configuration (differences to existing
 532  *            configuration only)
 533  * @return handle to the operation
 534  */
 535 struct GNUNET_TESTBED_Operation *
 536 GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer,
 537                                           const struct GNUNET_CONFIGURATION_Handle *cfg);
 538
 539
 540 /**
 541  * Destroy the given peer; the peer should have been
 542  * stopped first (if it was started).
 543  *
 544  * @param peer peer to stop
 545  * @return handle to the operation
 546  */
 547 struct GNUNET_TESTBED_Operation *
 548 GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer);
 549
 550
 551 /**
 552  * Options for peer connections.
 553  */
 554 enum GNUNET_TESTBED_ConnectOption
 555 {
 556   /**
 557    * No option (not valid as an argument).
 558    */
 559   GNUNET_TESTBED_CO_NONE = 0,
 560
 561   /**
 562    * Allow or disallow a connection between the specified peers.
 563    * Followed by GNUNET_NO (int) if a connection is disallowed
 564    * or GNUNET_YES if a connection is allowed.  Note that the
 565    * default (all connections allowed or disallowed) is
 566    * specified in the configuration of the controller.
 567    */
 568   GNUNET_TESTBED_CO_ALLOW = 1,
 569
 570   /**
 571    * FIXME: add (and implement) options to limit connection to
 572    * particular transports, force simulation of particular latencies
 573    * or message loss rates, or set bandwidth limitations.
 574    */
 575
 576 };
 577
 578
 579 /**
 580  * Manipulate the P2P underlay topology by configuring a link
 581  * between two peers.
 582  *
 583  * @param op_cls closure argument to give with the operation event
 584  * @param p1 first peer
 585  * @param p2 second peer
 586  * @param co option to change
 587  * @param ap option-specific values
 588  * @return handle to the operation, NULL if configuring the link at this
 589  *         time is not allowed
 590  */
 591 struct GNUNET_TESTBED_Operation *
 592 GNUNET_TESTBED_underlay_configure_link_va (void *op_cls,
 593                                            struct GNUNET_TESTBED_Peer *p1,
 594                                            struct GNUNET_TESTBED_Peer *p2,
 595                                            enum GNUNET_TESTBED_ConnectOption co,
 596                                            va_list ap);
 597
 598
 599 /**
 600  * Manipulate the P2P underlay topology by configuring a link
 601  * between two peers.
 602  *
 603  * @param op_cls closure argument to give with the operation event
 604  * @param p1 first peer
 605  * @param p2 second peer
 606  * @param co option to change
 607  * @param ... option-specific values
 608  * @return handle to the operation, NULL if configuring the link at this
 609  *         time is not allowed
 610  */
 611 struct GNUNET_TESTBED_Operation *
 612 GNUNET_TESTBED_underlay_configure_link (void *op_cls,
 613                                         struct GNUNET_TESTBED_Peer *p1,
 614                                         struct GNUNET_TESTBED_Peer *p2,
 615                                         enum GNUNET_TESTBED_ConnectOption co, ...);
 616
 617
 618
 619 /**
 620  * Topologies supported for testbeds.
 621  */
 622 enum GNUNET_TESTBED_TopologyOption
 623 {
 624   /**
 625    * A clique (everyone connected to everyone else).  No options.
 626    */
 627   GNUNET_TESTBED_TOPOLOGY_CLIQUE,
 628
 629   /**
 630    * Small-world network (2d torus plus random links).  Followed
 631    * by the number of random links to add (unsigned int).
 632    */
 633   GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD,
 634
 635   /**
 636    * Small-world network (ring plus random links).  Followed
 637    * by the number of random links to add (unsigned int).
 638    */
 639   GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING,
 640
 641   /**
 642    * Ring topology.  No options.
 643    */
 644   GNUNET_TESTBED_TOPOLOGY_RING,
 645
 646   /**
 647    * 2-d torus.  No options.
 648    */
 649   GNUNET_TESTBED_TOPOLOGY_2D_TORUS,
 650
 651   /**
 652    * Random graph.  Followed by the link density, that is the
 653    * percentage of links present in relation to a clique
 654    * (float).
 655    */
 656   GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI,
 657
 658   /**
 659    * Certain percentage of peers are unable to communicate directly
 660    * replicating NAT conditions.  Followed by the fraction of
 661    * NAT'ed peers (float).
 662    */
 663   GNUNET_TESTBED_TOPOLOGY_INTERNAT,
 664
 665   /**
 666    * Scale free topology.   FIXME: options?
 667    */
 668   GNUNET_TESTBED_TOPOLOGY_SCALE_FREE,
 669
 670   /**
 671    * Straight line topology.  No options.
 672    */
 673   GNUNET_TESTBED_TOPOLOGY_LINE,
 674
 675   /**
 676    * All peers are disconnected.  No options.
 677    */
 678   GNUNET_TESTBED_TOPOLOGY_NONE,
 679
 680   /**
 681    * Read a topology from a given file.  Followed by the name of the file (const char *).
 682    */
 683   GNUNET_TESTBED_TOPOLOGY_FROM_FILE
 684 };
 685
 686
 687 /**
 688  * Configure overall network topology to have a particular shape.
 689  *
 690  * @param op_cls closure argument to give with the operation event
 691  * @param num_peers number of peers in 'peers'
 692  * @param peers array of 'num_peers' with the peers to configure
 693  * @param topo desired underlay topology to use
 694  * @param ap topology-specific options
 695  * @return handle to the operation, NULL if configuring the topology
 696  *         is not allowed at this time
 697  */
 698 struct GNUNET_TESTBED_Operation *
 699 GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls,
 700                                                unsigned int num_peers,
 701                                                struct GNUNET_TESTBED_Peer **peers,
 702                                                enum GNUNET_TESTBED_TopologyOption topo,
 703                                                va_list ap);
 704
 705
 706 /**
 707  * Configure overall network topology to have a particular shape.
 708  *
 709  * @param op_cls closure argument to give with the operation event
 710  * @param num_peers number of peers in 'peers'
 711  * @param peers array of 'num_peers' with the peers to configure
 712  * @param topo desired underlay topology to use
 713  * @param ... topology-specific options
 714  * @return handle to the operation, NULL if configuring the topology
 715  *         is not allowed at this time
 716  */
 717 struct GNUNET_TESTBED_Operation *
 718 GNUNET_TESTBED_underlay_configure_topology (void *op_cls,
 719                                             unsigned int num_peers,
 720                                             struct GNUNET_TESTBED_Peer **peers,
 721                                             enum GNUNET_TESTBED_TopologyOption topo,
 722                                             ...);
 723
 724
 725 /**
 726  * Both peers must have been started before calling this function.
 727  * This function then obtains a HELLO from 'p1', gives it to 'p2'
 728  * and asks 'p2' to connect to 'p1'.
 729  *
 730  * @param op_cls closure argument to give with the operation event
 731  * @param p1 first peer
 732  * @param p2 second peer
 733  * @return handle to the operation, NULL if connecting these two
 734  *         peers is fundamentally not possible at this time (peers
 735  *         not running or underlay disallows)
 736  */
 737 struct GNUNET_TESTBED_Operation *
 738 GNUNET_TESTBED_overlay_connect (void *op_cls,
 739                                 struct GNUNET_TESTBED_Peer *p1,
 740                                 struct GNUNET_TESTBED_Peer *p2);
 741
 742
 743 /**
 744  * All peers must have been started before calling this function.
 745  * This function then connects the given peers in the P2P overlay
 746  * using the given topology.
 747  *
 748  * @param op_cls closure argument to give with the operation event
 749  * @param num_peers number of peers in 'peers'
 750  * @param peers array of 'num_peers' with the peers to configure
 751  * @param topo desired underlay topology to use
 752  * @param va topology-specific options
 753  * @return handle to the operation, NULL if connecting these
 754  *         peers is fundamentally not possible at this time (peers
 755  *         not running or underlay disallows)
 756  */
 757 struct GNUNET_TESTBED_Operation *
 758 GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls,
 759                                               unsigned int num_peers,
 760                                               struct GNUNET_TESTBED_Peer *peers,
 761                                               enum GNUNET_TESTBED_TopologyOption topo,
 762                                               va_list va);
 763
 764
 765 /**
 766  * All peers must have been started before calling this function.
 767  * This function then connects the given peers in the P2P overlay
 768  * using the given topology.
 769  *
 770  * @param op_cls closure argument to give with the operation event
 771  * @param num_peers number of peers in 'peers'
 772  * @param peers array of 'num_peers' with the peers to configure
 773  * @param topo desired underlay topology to use
 774  * @param ... topology-specific options
 775  * @return handle to the operation, NULL if connecting these
 776  *         peers is fundamentally not possible at this time (peers
 777  *         not running or underlay disallows)
 778  */
 779 struct GNUNET_TESTBED_Operation *
 780 GNUNET_TESTBED_overlay_configure_topology (void *op_cls,
 781                                            unsigned int num_peers,
 782                                            struct GNUNET_TESTBED_Peer *peers,
 783                                            enum GNUNET_TESTBED_TopologyOption topo,
 784                                            ...);
 785
 786
 787
 788 /**
 789  * Ask the testbed controller to write the current overlay topology to
 790  * a file.  Naturally, the file will only contain a snapshot as the
 791  * topology may evolve all the time.
 792  *
 793  * @param controller overlay controller to inspect
 794  * @param filename name of the file the topology should
 795  *        be written to.
 796  */
 797 void
 798 GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller *controller,
 799                                                const char *filename);
 800
 801
 802 /**
 803  * Adapter function called to establish a connection to
 804  * a service.
 805  *
 806  * @param cls closure
 807  * @param cfg configuration of the peer to connect to
 808  * @return service handle to return in 'op_result', NULL on error
 809  */
 810 typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls,
 811                                                 const struct GNUNET_CONFIGURATION_Handle *cfg);
 812
 813
 814 /**
 815  * Adapter function called to destroy a connection to
 816  * a service.
 817  *
 818  * @param cls closure
 819  * @param op_result service handle returned from the connect adapter
 820  */
 821 typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls,
 822                                                  void *op_result);
 823
 824
 825 /**
 826  * Connect to a service offered by the given peer.  Will ensure that
 827  * the request is queued to not overwhelm our ability to create and
 828  * maintain connections with other systems.  The actual service
 829  * handle is then returned via the 'op_result' member in the event
 830  * callback.  The 'ca' callback is used to create the connection
 831  * when the time is right; the 'da' callback will be used to
 832  * destroy the connection (upon 'GNUNET_TESTBED_operation_done').
 833  * 'GNUNET_TESTBED_operation_cancel' can be used to abort this
 834  * operation until the event callback has been called.
 835  *
 836  * @param op_cls closure to pass in operation event
 837  * @param peer peer that runs the service
 838  * @param service_name name of the service to connect to
 839  * @param ca helper function to establish the connection
 840  * @param da helper function to close the connection
 841  * @param cada_cls closure for ca and da
 842  * @return handle for the operation
 843  */
 844 struct GNUNET_TESTBED_Operation *
 845 GNUNET_TESTBED_service_connect (void *op_cls,
 846                                 struct GNUNET_TESTBED_Peer *peer,
 847                                 const char *service_name,
 848                                 GNUNET_TESTBED_ConnectAdapter ca,
 849                                 GNUNET_TESTBED_DisconnectAdapter da,
 850                                 void *cada_cls);
 851
 852
 853 /**
 854  * Cancel a pending operation.  Releases all resources
 855  * of the operation and will ensure that no event
 856  * is generated for the operation.  Does NOT guarantee
 857  * that the operation will be fully undone (or that
 858  * nothing ever happened).
 859  *
 860  * @param operation operation to cancel
 861  */
 862 void
 863 GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation);
 864
 865
 866 /**
 867  * Signal that the information from an operation has been fully
 868  * processed.  This function MUST be called for each event
 869  * of type 'operation_finished' to fully remove the operation
 870  * from the operation queue.  After calling this function, the
 871  * 'op_result' becomes invalid (!).
 872  *
 873  * @param operation operation to signal completion for
 874  */
 875 void
 876 GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation);
 877
 878
 879 /**
 880  * Configure and run a testbed using the given
 881  * master controller on 'num_hosts' starting
 882  * 'num_peers' using the given peer configuration.
 883  *
 884  * @param controller master controller for the testbed
 885  *                   (must not be destroyed until after the
 886  *                    testbed is destroyed).
 887  * @param num_hosts number of hosts in 'hosts', 0 to only
 888  *        use 'localhost'
 889  * @param hosts list of hosts to use for the testbed
 890  * @param num_peers number of peers to start
 891  * @param peer_cfg peer configuration template to use
 892  * @param underlay_topology underlay topology to create
 893  * @param va topology-specific options
 894  * @return handle to the testbed
 895  */
 896 struct GNUNET_TESTBED_Testbed *
 897 GNUNET_TESTBED_create_va (struct GNUNET_TESTBED_Controller *controller,
 898                           unsigned int num_hosts,
 899                           struct GNUNET_TESTBED_Host **hosts,
 900                           unsigned int num_peers,
 901                           const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
 902                           enum GNUNET_TESTBED_TopologyOption underlay_topology,
 903                           va_list va);
 904
 905
 906 /**
 907  * Configure and run a testbed using the given
 908  * master controller on 'num_hosts' starting
 909  * 'num_peers' using the given peer configuration.
 910  *
 911  * @param controller master controller for the testbed
 912  *                   (must not be destroyed until after the
 913  *                    testbed is destroyed).
 914  * @param num_hosts number of hosts in 'hosts', 0 to only
 915  *        use 'localhost'
 916  * @param hosts list of hosts to use for the testbed
 917  * @param num_peers number of peers to start
 918  * @param peer_cfg peer configuration template to use
 919  * @param underlay_topology underlay topology to create
 920  * @param ... topology-specific options
 921  */
 922 struct GNUNET_TESTBED_Testbed *
 923 GNUNET_TESTBED_create (struct GNUNET_TESTBED_Controller *controller,
 924                        unsigned int num_hosts,
 925                        struct GNUNET_TESTBED_Host **hosts,
 926                        unsigned int num_peers,
 927                        const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
 928                        enum GNUNET_TESTBED_TopologyOption underlay_topology,
 929                        ...);
 930
 931
 932 /**
 933  * Destroy a testbed.  Stops all running peers and then
 934  * destroys all peers.  Does NOT destroy the master controller.
 935  *
 936  * @param testbed testbed to destroy
 937  */
 938 void
 939 GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed);
 940
 941
 942 /**
 943  * Convenience method for running a testbed with
 944  * a single call.  Underlay and overlay topology
 945  * are configured using the "UNDERLAY" and "OVERLAY"
 946  * options in the "[testbed]" section of the configuration\
 947  * (with possible options given in "UNDERLAY_XXX" and/or
 948  * "OVERLAY_XXX").
 949  *
 950  * The testbed is to be terminated using a call to
 951  * "GNUNET_SCHEDULER_shutdown".
 952  *
 953  * @param host_filename name of the file with the 'hosts', NULL
 954  *        to run everything on 'localhost'
 955  * @param cfg configuration to use (for testbed, controller and peers)
 956  * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg?
 957  * @param event_mask bit mask with set of events to call 'cc' for;
 958  *                   or-ed values of "1LL" shifted by the
 959  *                   respective 'enum GNUNET_TESTBED_EventType'
 960  *                   (i.e.  "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...")
 961  * @param cc controller callback to invoke on events
 962  * @param cc_cls closure for cc
 963  * @param master task to run once the testbed is ready
 964  * @param master_cls closure for 'task'.
 965  */
 966 void
 967 GNUNET_TESTBED_run (const char *host_filename,
 968                     const struct GNUNET_CONFIGURATION_Handle *cfg,
 969                     unsigned int num_peers,
 970                     uint64_t event_mask,
 971                     GNUNET_TESTBED_ControllerCallback cc,
 972                     void *cc_cls,
 973                     GNUNET_SCHEDULER_Task master,
 974                     void *master_cls);
 975
 976
 977 /**
 978  * Signature of a main function for a testcase.
 979  *
 980  * @param cls closure
 981  * @param num_peers number of peers in 'peers'
 982  * @param peers handle to peers run in the testbed
 983  */
 984 typedef void (*GNUNET_TESTBED_TestMaster)(void *cls,
 985                                           unsigned int num_peers,
 986                                           struct GNUNET_TESTBED_Peer **peers);
 987
 988
 989 /**
 990  * Convenience method for running a "simple" test on the local system
 991  * with a single call from 'main'.  Underlay and overlay topology are
 992  * configured using the "UNDERLAY" and "OVERLAY" options in the
 993  * "[testbed]" section of the configuration (with possible options
 994  * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX").
 995  *
 996  * The test is to be terminated using a call to
 997  * "GNUNET_SCHEDULER_shutdown".  If starting the test fails,
 998  * the program is stopped without 'master' ever being run.
 999  *
1000  * NOTE: this function should be called from 'main', NOT from
1001  * within a GNUNET_SCHEDULER-loop.  This function will initialze
1002  * the scheduler loop, the testbed and then pass control to
1003  * 'master'.
1004  *
1005  * @param testname name of the testcase (to configure logging, etc.)
1006  * @param cfg_filename configuration filename to use
1007  *              (for testbed, controller and peers)
1008  * @param num_peers number of peers to start
1009  * @param test_master task to run once the test is ready
1010  * @param test_master_cls closure for 'task'.
1011  */
1012 void
1013 GNUNET_TESTBED_test_run (const char *testname,
1014                          const char *cfg_filename,
1015                          unsigned int num_peers,
1016                          GNUNET_TESTBED_TestMaster test_master,
1017                          void *test_master_cls);
1018
1019
1020 #if 0                           /* keep Emacsens' auto-indent happy */
1021 {
1022 #endif
1023
1024
1025 #ifdef __cplusplus
1026 }
1027 #endif
1028
1029 #endif