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