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