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