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