src/include/gnunet_testbed_service.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008, 2009, 2012 Christian Grothoff (and other contributing authors)
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18       Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file include/gnunet_testbed_service.h
  23  * @brief API for writing tests and creating large-scale
  24  *        emulation testbeds for GNUnet.
  25  * @author Christian Grothoff
  26  */
  27
  28 #ifndef GNUNET_TESTBED_SERVICE_H
  29 #define GNUNET_TESTBED_SERVICE_H
  30
  31 #include "gnunet_util_lib.h"
  32 #include "gnunet_testing_lib-new.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 testbed framework.
  45  * The master process must be able to SSH to this host without password (via
  46  * ssh-agent).
  47  */
  48 struct GNUNET_TESTBED_Host;
  49
  50 /**
  51  * Opaque handle to a peer controlled by the testbed framework.  A peer runs
  52  * at a particular host.
  53  */
  54 struct GNUNET_TESTBED_Peer;
  55
  56 /**
  57  * Opaque handle to an abstract operation to be executed by the testbed framework.
  58  */
  59 struct GNUNET_TESTBED_Operation;
  60
  61 /**
  62  * Handle to interact with a GNUnet testbed controller.  Each
  63  * controller has at least one master handle which is created when the
  64  * controller is created; this master handle interacts with the
  65  * controller process, destroying it destroys the controller (by
  66  * closing stdin of the controller process).  Additionally,
  67  * controllers can interact with each other (in a P2P fashion); those
  68  * links are established via TCP/IP on the controller's service port.
  69  */
  70 struct GNUNET_TESTBED_Controller;
  71
  72 /**
  73  * Handle to a large-scale testbed that is managed at a high level.
  74  */
  75 struct GNUNET_TESTBED_Testbed;
  76
  77
  78 /**
  79  * Create a host to run peers and controllers on.
  80  *
  81  * @param hostname name of the host, use "NULL" for localhost
  82  * @param username username to use for the login; may be NULL
  83  * @param port port number to use for ssh; use 0 to let ssh decide
  84  * @return handle to the host, NULL on error
  85  */
  86 struct GNUNET_TESTBED_Host *
  87 GNUNET_TESTBED_host_create (const char *hostname,
  88                             const char *username,
  89                             uint16_t port);
  90
  91
  92
  93 /**
  94  * Create a host to run peers and controllers on.  This function is used
  95  * if a peer learns about a host via IPC between controllers (and thus
  96  * some higher-level controller has already determined the unique IDs).
  97  *
  98  * @param id global host ID assigned to the host; 0 is
  99  *        reserved to always mean 'localhost'
 100  * @param hostname name of the host, use "NULL" for localhost
 101  * @param username username to use for the login; may be NULL
 102  * @param port port number to use for ssh; use 0 to let ssh decide
 103  * @return handle to the host, NULL on error
 104  */
 105 struct GNUNET_TESTBED_Host *
 106 GNUNET_TESTBED_host_create_with_id (uint32_t id,
 107                                     const char *hostname,
 108                                     const char *username,
 109                                     uint16_t port);
 110
 111
 112 /**
 113  * Load a set of hosts from a configuration file.
 114  *
 115  * @param filename file with the host specification
 116  * @param hosts set to the hosts found in the file
 117  * @return number of hosts returned in 'hosts', 0 on error
 118  */
 119 unsigned int
 120 GNUNET_TESTBED_hosts_load_from_file (const char *filename,
 121                                      struct GNUNET_TESTBED_Host ***hosts);
 122
 123
 124 /**
 125  * Destroy a host handle.  Must only be called once everything
 126  * running on that host has been stopped.
 127  *
 128  * @param host handle to destroy
 129  */
 130 void
 131 GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host);
 132
 133
 134 /**
 135  * Enumeration with (at most 64) possible event types that
 136  * can be monitored using the testbed framework.
 137  */
 138 enum GNUNET_TESTBED_EventType
 139 {
 140   /**
 141    * A peer has been started.
 142    */
 143   GNUNET_TESTBED_ET_PEER_START = 0,
 144
 145   /**
 146    * A peer has been stopped.
 147    */
 148   GNUNET_TESTBED_ET_PEER_STOP = 1,
 149
 150   /**
 151    * A connection between two peers was established.
 152    */
 153   GNUNET_TESTBED_ET_CONNECT = 2,
 154
 155   /**
 156    * A connection between two peers was torn down.
 157    */
 158   GNUNET_TESTBED_ET_DISCONNECT = 3,
 159
 160   /**
 161    * A requested testbed operation has been completed.
 162    */
 163   GNUNET_TESTBED_ET_OPERATION_FINISHED = 4,
 164
 165   /**
 166    * The 'GNUNET_TESTBED_run' operation has been completed
 167    */
 168   GNUNET_TESTBED_ET_TESTBED_ONLINE = 5
 169
 170 };
 171
 172
 173 /**
 174  * Types of information that can be requested about a peer.
 175  */
 176 enum GNUNET_TESTBED_PeerInformationType
 177 {
 178
 179   /**
 180    * Special value (not valid for requesting information)
 181    * that is used in the event struct if a 'generic' pointer
 182    * is returned (for other operations not related to this
 183    * enumeration).
 184    */
 185   GNUNET_TESTBED_PIT_GENERIC = 0,
 186
 187   /**
 188    * What configuration is the peer using?  Returns a 'const struct
 189    * GNUNET_CONFIGURATION_Handle *'.  Valid until
 190    * 'GNUNET_TESTNIG_operation_done' is called.  However, the
 191    * values may be inaccurate if the peer is reconfigured in
 192    * the meantime.
 193    */
 194   GNUNET_TESTBED_PIT_CONFIGURATION,
 195
 196   /**
 197    * What is the identity of the peer?  Returns a
 198    * 'const struct GNUNET_PeerIdentity *'.  Valid until
 199    * 'GNUNET_TESTNIG_operation_done' is called.
 200    */
 201   GNUNET_TESTBED_PIT_IDENTITY
 202
 203 };
 204
 205
 206 /**
 207  * Argument to GNUNET_TESTBED_ControllerCallback with details about
 208  * the event.
 209  */
 210 struct GNUNET_TESTBED_EventInformation
 211 {
 212
 213   /**
 214    * Type of the event.
 215    */
 216   enum GNUNET_TESTBED_EventType type;
 217
 218   /**
 219    * Details about the event.
 220    */
 221   union
 222   {
 223
 224     /**
 225      * Details about peer start event.
 226      */
 227     struct
 228     {
 229       /**
 230        * Handle for the host where the peer
 231        * was started.
 232        */
 233       struct GNUNET_TESTBED_Host *host;
 234
 235       /**
 236        * Handle for the peer that was started.
 237        */
 238       struct GNUNET_TESTBED_Peer *peer;
 239
 240     } peer_start;
 241
 242     /**
 243      * Details about peer stop event.
 244      */
 245     struct
 246     {
 247
 248       /**
 249        * Handle for the peer that was started.
 250        */
 251       struct GNUNET_TESTBED_Peer *peer;
 252
 253     } peer_stop;
 254
 255     /**
 256      * Details about connect event.
 257      */
 258     struct
 259     {
 260       /**
 261        * Handle for one of the connected peers.
 262        */
 263       struct GNUNET_TESTBED_Peer *peer1;
 264
 265       /**
 266        * Handle for one of the connected peers.
 267        */
 268       struct GNUNET_TESTBED_Peer *peer2;
 269
 270     } peer_connect;
 271
 272     /**
 273      * Details about disconnect event.
 274      */
 275     struct
 276     {
 277       /**
 278        * Handle for one of the disconnected peers.
 279        */
 280       struct GNUNET_TESTBED_Peer *peer1;
 281
 282       /**
 283        * Handle for one of the disconnected peers.
 284        */
 285       struct GNUNET_TESTBED_Peer *peer2;
 286
 287     } peer_disconnect;
 288
 289     /**
 290      * Details about an operation finished event.
 291      */
 292     struct
 293     {
 294
 295       /**
 296        * Handle for the operation that was finished.
 297        */
 298       struct GNUNET_TESTBED_Operation *operation;
 299
 300       /**
 301        * Closure that was passed in when the event was
 302        * requested.
 303        */
 304       void *op_cls;
 305
 306       /**
 307        * Error message for the operation, NULL on success.
 308        */
 309       const char *emsg;
 310
 311       /**
 312        * No result (NULL pointer) or generic result
 313        * (whatever the GNUNET_TESTBED_ConnectAdapter returned).
 314        */
 315       void *generic;
 316
 317     } operation_finished;
 318
 319     /**
 320      * Details about an testbed run completed event.
 321      */
 322     struct
 323     {
 324
 325       /**
 326        * Error message for the operation, NULL on success.
 327        */
 328       const char *emsg;
 329
 330       /**
 331        * Array of peers now running (valid until
 332        * 'GNUNET_TESTBED_testbed_stop' is called).  Note that it is
 333        * not allowed to call 'GNUNET_TESTBED_peer_destroy' on peers
 334        * from this array.
 335        */
 336       struct GNUNET_TESTBED_Peer **peers;
 337
 338       /**
 339        * Size of the 'peers' array.
 340        */
 341       unsigned int num_peers;
 342
 343     } testbed_run_finished;
 344
 345   } details;
 346
 347 };
 348
 349
 350 /**
 351  * Signature of the event handler function called by the
 352  * respective event controller.
 353  *
 354  * @param cls closure
 355  * @param event information about the event
 356  */
 357 typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls,
 358                                                   const struct GNUNET_TESTBED_EventInformation *event);
 359
 360
 361 /**
 362  * Opaque Handle for Controller process
 363  */
 364 struct GNUNET_TESTBED_ControllerProc;
 365
 366
 367 /**
 368  * Callback to signal successfull startup of the controller process
 369  *
 370  * @param cls the closure from GNUNET_TESTBED_controller_start()
 371  * @param cfg the configuration with which the controller has been started;
 372  *          NULL if status is not GNUNET_OK
 373  * @param status GNUNET_OK if the startup is successfull; GNUNET_SYSERR if not,
 374  *          GNUNET_TESTBED_controller_stop() shouldn't be called in this case
 375  */
 376 typedef void (*GNUNET_TESTBED_ControllerStatusCallback) (void *cls,
 377                                                         const struct GNUNET_CONFIGURATION_Handle *cfg,
 378                                                         int status);
 379
 380
 381 /**
 382  * Starts a controller process at the host.
 383  *
 384  * @param controller_ip the ip address of the controller. Will be set as TRUSTED
 385  *          host when starting testbed controller at host
 386  * @param host the host where the controller has to be started; NULL for
 387  *          localhost
 388  * @param cfg template configuration to use for the remote controller; the
 389  *          remote controller will be started with a slightly modified
 390  *          configuration (port numbers, unix domain sockets and service home
 391  *          values are changed as per TESTING library on the remote host)
 392  * @param cb function called when the controller is successfully started or
 393  *          dies unexpectedly; GNUNET_TESTBED_controller_stop shouldn't be
 394  *          called if cb is called with GNUNET_SYSERR as status. Will never be
 395  *          called in the same task as 'GNUNET_TESTBED_controller_start'
 396  *          (synchronous errors will be signalled by returning NULL). This
 397  *          parameter cannot be NULL.
 398  * @param cls closure for above callbacks
 399  * @return the controller process handle, NULL on errors
 400  */
 401 struct GNUNET_TESTBED_ControllerProc *
 402 GNUNET_TESTBED_controller_start (const char *controller_ip,
 403                                  struct GNUNET_TESTBED_Host *host,
 404                                  const struct GNUNET_CONFIGURATION_Handle *cfg,
 405                                  GNUNET_TESTBED_ControllerStatusCallback cb,
 406                                  void *cls);
 407
 408
 409 /**
 410  * Stop the controller process (also will terminate all peers and controllers
 411  * dependent on this controller).  This function blocks until the testbed has
 412  * been fully terminated (!).
 413  *
 414  * @param cproc the controller process handle
 415  */
 416 void
 417 GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_ControllerProc *cproc);
 418
 419
 420 /**
 421  * Connect to a controller process using the given configuration at the
 422  * given host.
 423  *
 424  * @param cfg configuration to use
 425  * @param host host to run the controller on; This should be the same host if
 426  *          the controller was previously started with
 427  *          GNUNET_TESTBED_controller_start; NULL for localhost
 428  * @param host host where this controller is being run;
 429  * @param event_mask bit mask with set of events to call 'cc' for;
 430  *                   or-ed values of "1LL" shifted by the
 431  *                   respective 'enum GNUNET_TESTBED_EventType'
 432  *                   (i.e.  "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...")
 433  * @param cc controller callback to invoke on events
 434  * @param cc_cls closure for cc
 435  * @return handle to the controller
 436  */
 437 struct GNUNET_TESTBED_Controller *
 438 GNUNET_TESTBED_controller_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 439                                    struct GNUNET_TESTBED_Host *host,
 440                                    uint64_t event_mask,
 441                                    GNUNET_TESTBED_ControllerCallback cc,
 442                                    void *cc_cls);
 443
 444
 445 /**
 446  * Configure shared services at a controller.  Using this function,
 447  * you can specify that certain services (such as "resolver")
 448  * should not be run for each peer but instead be shared
 449  * across N peers on the specified host.  This function
 450  * must be called before any peers are created at the host.
 451  *
 452  * @param controller controller to configure
 453  * @param service_name name of the service to share
 454  * @param num_peers number of peers that should share one instance
 455  *        of the specified service (1 for no sharing is the default),
 456  *        use 0 to disable the service
 457  */
 458 void
 459 GNUNET_TESTBED_controller_configure_sharing (struct GNUNET_TESTBED_Controller *controller,
 460                                              const char *service_name,
 461                                              uint32_t num_peers);
 462
 463
 464 /**
 465  * Stop the given controller (also will terminate all peers and
 466  * controllers dependent on this controller).  This function
 467  * blocks until the testbed has been fully terminated (!).
 468  *
 469  * @param controller handle to controller to stop
 470  */
 471 void
 472 GNUNET_TESTBED_controller_disconnect (struct GNUNET_TESTBED_Controller *controller);
 473
 474
 475 /**
 476  * Opaque handle for host registration
 477  */
 478 struct GNUNET_TESTBED_HostRegistrationHandle;
 479
 480
 481 /**
 482  * Callback which will be called to after a host registration succeeded or failed
 483  *
 484  * @param cls the closure
 485  * @param emsg the error message; NULL if host registration is successful
 486  */
 487 typedef void (* GNUNET_TESTBED_HostRegistrationCompletion) (void *cls,
 488                                                             const char *emsg);
 489
 490
 491 /**
 492  * Register a host with the controller
 493  *
 494  * @param controller the controller handle
 495  * @param host the host to register
 496  * @param cc the completion callback to call to inform the status of
 497  *          registration. After calling this callback the registration handle
 498  *          will be invalid. Cannot be NULL
 499  * @param cc_cls the closure for the cc
 500  * @return handle to the host registration which can be used to cancel the
 501  *           registration; NULL if another registration handle is present and
 502  *           is not cancelled
 503  */
 504 struct GNUNET_TESTBED_HostRegistrationHandle *
 505 GNUNET_TESTBED_register_host (struct GNUNET_TESTBED_Controller *controller,
 506                               struct GNUNET_TESTBED_Host *host,
 507                               GNUNET_TESTBED_HostRegistrationCompletion cc,
 508                               void *cc_cls);
 509
 510
 511 /**
 512  * Cancel the pending registration. Note that the registration message will
 513  * already be queued to be sent to the service, cancellation has only the
 514  * effect that the registration completion callback for the registration is
 515  * never called and from our perspective the host is not registered until the
 516  * completion callback is called.
 517  *
 518  * @param handle the registration handle to cancel
 519  */
 520 void
 521 GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle
 522                                     *handle);
 523
 524
 525 /**
 526  * Callback to be called when an operation is completed
 527  *
 528  * @param cls the callback closure from functions generating an operation
 529  * @param op the operation that has been finished
 530  * @param emsg error message in case the operation has failed; will be NULL if
 531  *          operation has executed successfully.
 532  */
 533 typedef void (*GNUNET_TESTBED_OperationCompletionCallback) (void *cls,
 534                                                             struct
 535                                                             GNUNET_TESTBED_Operation
 536                                                             *op,
 537                                                             const char *emsg);
 538
 539
 540 /**
 541  * Create a link from slave controller to delegated controller. Whenever the
 542  * master controller is asked to start a peer at the delegated controller the
 543  * request will be routed towards slave controller (if a route exists). The
 544  * slave controller will then route it to the delegated controller. The
 545  * configuration of the slave controller is given and to be used to either
 546  * create the slave controller or to connect to an existing slave controller
 547  * process.  'is_subordinate' specifies if the given slave controller should be
 548  * started and managed by the master controller, or if the slave already has a
 549  * master and this is just a secondary master that is also allowed to use the
 550  * existing slave.
 551  *
 552  * @param master handle to the master controller who creates the association
 553  * @param delegated_host requests to which host should be delegated; cannot be NULL
 554  * @param slave_host which host is used to run the slave controller; use NULL to
 555  *          make the master controller connect to the delegated host
 556  * @param slave_cfg configuration to use for the slave controller
 557  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 558  *          be started by the master controller; GNUNET_NO if we are just
 559  *          allowed to use the slave via TCP/IP
 560  * @return the operation handle
 561  */
 562 struct GNUNET_TESTBED_Operation *
 563 GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master,
 564                                 struct GNUNET_TESTBED_Host *delegated_host,
 565                                 struct GNUNET_TESTBED_Host *slave_host,
 566                                 const struct GNUNET_CONFIGURATION_Handle *slave_cfg,
 567                                 int is_subordinate);
 568
 569
 570 /**
 571  * Same as the GNUNET_TESTBED_controller_link, however expects configuration in
 572  * serialized and compressed
 573  *
 574  * @param master handle to the master controller who creates the association
 575  * @param delegated_host requests to which host should be delegated; cannot be NULL
 576  * @param slave_host which host is used to run the slave controller; use NULL to
 577  *          make the master controller connect to the delegated host
 578  * @param sxcfg serialized and compressed configuration
 579  * @param sxcfg_size the size sxcfg
 580  * @param scfg_size the size of uncompressed serialized configuration
 581  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 582  *          be started by the master controller; GNUNET_NO if we are just
 583  *          allowed to use the slave via TCP/IP
 584  * @return the operation handle
 585  */
 586 struct GNUNET_TESTBED_Operation *
 587 GNUNET_TESTBED_controller_link_2 (struct GNUNET_TESTBED_Controller *master,
 588                                   struct GNUNET_TESTBED_Host *delegated_host,
 589                                   struct GNUNET_TESTBED_Host *slave_host,
 590                                   const char *sxcfg,
 591                                   size_t sxcfg_size,
 592                                   size_t scfg_size,
 593                                   int is_subordinate);
 594
 595
 596 /**
 597  * Function to acquire the configuration of a running slave controller. The
 598  * completion of the operation is signalled through the controller_cb from
 599  * GNUNET_TESTBED_controller_connect(). If the operation is successful the
 600  * handle to the configuration is available in the generic pointer of
 601  * operation_finished field of struct GNUNET_TESTBED_EventInformation.
 602  *
 603  * @param op_cls the closure for the operation
 604  * @param master the handle to master controller
 605  * @param slave_host the host where the slave controller is running
 606  * @return the operation handle
 607  */
 608 struct GNUNET_TESTBED_Operation *
 609 GNUNET_TESTBED_get_slave_config (void *op_cls,
 610                                  struct GNUNET_TESTBED_Controller *master,
 611                                  struct GNUNET_TESTBED_Host *slave_host);
 612
 613
 614 /**
 615  * Functions of this signature are called when a peer has been successfully
 616  * created
 617  *
 618  * @param cls the closure from GNUNET_TESTBED_peer_create()
 619  * @param peer the handle for the created peer; NULL on any error during
 620  *          creation
 621  * @param emsg NULL if peer is not NULL; else MAY contain the error description
 622  */
 623 typedef void (*GNUNET_TESTBED_PeerCreateCallback) (void *cls,
 624                                                    struct GNUNET_TESTBED_Peer *peer,
 625                                                    const char *emsg);
 626
 627
 628 /**
 629  * Create the given peer at the specified host using the given
 630  * controller.  If the given controller is not running on the target
 631  * host, it should find or create a controller at the target host and
 632  * delegate creating the peer.  Explicit delegation paths can be setup
 633  * using 'GNUNET_TESTBED_controller_link'.  If no explicit delegation
 634  * path exists, a direct link with a subordinate controller is setup
 635  * for the first delegated peer to a particular host; the subordinate
 636  * controller is then destroyed once the last peer that was delegated
 637  * to the remote host is stopped.
 638  *
 639  * Creating the peer only creates the handle to manipulate and further
 640  * configure the peer; use "GNUNET_TESTBED_peer_start" and
 641  * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's
 642  * processes.
 643  *
 644  * Note that the given configuration will be adjusted by the
 645  * controller to avoid port/path conflicts with other peers.
 646  * The "final" configuration can be obtained using
 647  * 'GNUNET_TESTBED_peer_get_information'.
 648  *
 649  * @param controller controller process to use
 650  * @param host host to run the peer on
 651  * @param cfg Template configuration to use for the peer. Should exist until
 652  *          operation is cancelled or GNUNET_TESTBED_operation_done() is called
 653  * @param cb the callback to call when the peer has been created
 654  * @param cls the closure to the above callback
 655  * @return the operation handle
 656  */
 657 struct GNUNET_TESTBED_Operation *
 658 GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller,
 659                             struct GNUNET_TESTBED_Host *host,
 660                             const struct GNUNET_CONFIGURATION_Handle *cfg,
 661                             GNUNET_TESTBED_PeerCreateCallback cb,
 662                             void *cls);
 663
 664
 665 /**
 666  * Functions of this signature are called when a peer has been successfully
 667  * started or stopped.
 668  *
 669  * @param cls the closure from GNUNET_TESTBED_peer_start/stop()
 670  * @param emsg NULL on success; otherwise an error description
 671  */
 672 typedef void (*GNUNET_TESTBED_PeerChurnCallback) (void *cls,
 673                                                   const char *emsg);
 674
 675
 676 /**
 677  * Start the given peer.
 678  *
 679  * @param peer peer to start
 680  * @param pcc function to call upon completion
 681  * @param pcc_cls closure for 'pcc'
 682  * @return handle to the operation
 683  */
 684 struct GNUNET_TESTBED_Operation *
 685 GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer,
 686                            GNUNET_TESTBED_PeerChurnCallback pcc,
 687                            void *pcc_cls);
 688
 689
 690 /**
 691  * Stop the given peer.  The handle remains valid (use
 692  * "GNUNET_TESTBED_peer_destroy" to fully clean up the
 693  * state of the peer).
 694  *
 695  * @param peer peer to stop
 696  * @param pcc function to call upon completion
 697  * @param pcc_cls closure for 'pcc'
 698  * @return handle to the operation
 699  */
 700 struct GNUNET_TESTBED_Operation *
 701 GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer,
 702                           GNUNET_TESTBED_PeerChurnCallback pcc,
 703                           void *pcc_cls);
 704
 705
 706 /**
 707  * Data returned from GNUNET_TESTBED_peer_get_information
 708  */
 709 struct GNUNET_TESTBED_PeerInformation
 710 {
 711   /**
 712    * Peer information type; captures which of the types
 713    * in the 'op_result' is actually in use.
 714    */
 715   enum GNUNET_TESTBED_PeerInformationType pit;
 716
 717   /**
 718    * The result of the get information operation; Choose according to the pit
 719    */
 720   union
 721   {
 722     /**
 723      * The configuration of the peer
 724      */
 725     struct GNUNET_CONFIGURATION_Handle *cfg;
 726
 727     /**
 728      * The identity of the peer
 729      */
 730     struct GNUNET_PeerIdentity *id;
 731   } result;
 732 };
 733
 734
 735 /**
 736  * Callback to be called when the requested peer information is available
 737  *
 738  * @param cb_cls the closure from GNUNET_TETSBED_peer_get_information()
 739  * @param op the operation this callback corresponds to
 740  * @param pinfo the result; will be NULL if the operation has failed
 741  * @param emsg error message if the operation has failed; will be NULL if the
 742  *          operation is successfull
 743  */
 744 typedef void (*GNUNET_TESTBED_PeerInfoCallback) (void *cb_cls,
 745                                                  struct GNUNET_TESTBED_Operation
 746                                                  *op,
 747                                                  const struct
 748                                                  GNUNET_TESTBED_PeerInformation
 749                                                  *pinfo,
 750                                                  const char *emsg);
 751
 752
 753 /**
 754  * Request information about a peer. The controller callback will not be called
 755  * with event type GNUNET_TESTBED_ET_OPERATION_FINISHED when result for this
 756  * operation is available. Instead, the GNUNET_TESTBED_PeerInfoCallback() will
 757  * be called.
 758  *
 759  * @param peer peer to request information about
 760  * @param pit desired information
 761  * @param cb the convenience callback to be called when results for this
 762  *          operation are available
 763  * @param cb_cls the closure for the above callback
 764  * @return handle to the operation
 765  */
 766 struct GNUNET_TESTBED_Operation *
 767 GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer,
 768                                      enum GNUNET_TESTBED_PeerInformationType
 769                                      pit,
 770                                      GNUNET_TESTBED_PeerInfoCallback cb,
 771                                      void *cb_cls);
 772
 773
 774 /**
 775  * Change peer configuration.  Must only be called while the
 776  * peer is stopped.  Ports and paths cannot be changed this
 777  * way.
 778  *
 779  * @param peer peer to change configuration for
 780  * @param cfg new configuration (differences to existing
 781  *            configuration only)
 782  * @return handle to the operation
 783  */
 784 struct GNUNET_TESTBED_Operation *
 785 GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer,
 786                                           const struct GNUNET_CONFIGURATION_Handle *cfg);
 787
 788
 789 /**
 790  * Destroy the given peer; the peer should have been
 791  * stopped first (if it was started).
 792  *
 793  * @param peer peer to stop
 794  * @return handle to the operation
 795  */
 796 struct GNUNET_TESTBED_Operation *
 797 GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer);
 798
 799
 800 /**
 801  * Options for peer connections.
 802  */
 803 enum GNUNET_TESTBED_ConnectOption
 804 {
 805   /**
 806    * No option (not valid as an argument).
 807    */
 808   GNUNET_TESTBED_CO_NONE = 0,
 809
 810   /**
 811    * Allow or disallow a connection between the specified peers.
 812    * Followed by GNUNET_NO (int) if a connection is disallowed
 813    * or GNUNET_YES if a connection is allowed.  Note that the
 814    * default (all connections allowed or disallowed) is
 815    * specified in the configuration of the controller.
 816    */
 817   GNUNET_TESTBED_CO_ALLOW = 1,
 818
 819   /**
 820    * FIXME: add (and implement) options to limit connection to
 821    * particular transports, force simulation of particular latencies
 822    * or message loss rates, or set bandwidth limitations.
 823    */
 824
 825 };
 826
 827
 828 /**
 829  * Manipulate the P2P underlay topology by configuring a link
 830  * between two peers.
 831  *
 832  * @param op_cls closure argument to give with the operation event
 833  * @param p1 first peer
 834  * @param p2 second peer
 835  * @param co option to change
 836  * @param ap option-specific values
 837  * @return handle to the operation, NULL if configuring the link at this
 838  *         time is not allowed
 839  */
 840 struct GNUNET_TESTBED_Operation *
 841 GNUNET_TESTBED_underlay_configure_link_va (void *op_cls,
 842                                            struct GNUNET_TESTBED_Peer *p1,
 843                                            struct GNUNET_TESTBED_Peer *p2,
 844                                            enum GNUNET_TESTBED_ConnectOption co,
 845                                            va_list ap);
 846
 847
 848 /**
 849  * Manipulate the P2P underlay topology by configuring a link
 850  * between two peers.
 851  *
 852  * @param op_cls closure argument to give with the operation event
 853  * @param p1 first peer
 854  * @param p2 second peer
 855  * @param co option to change
 856  * @param ... option-specific values
 857  * @return handle to the operation, NULL if configuring the link at this
 858  *         time is not allowed
 859  */
 860 struct GNUNET_TESTBED_Operation *
 861 GNUNET_TESTBED_underlay_configure_link (void *op_cls,
 862                                         struct GNUNET_TESTBED_Peer *p1,
 863                                         struct GNUNET_TESTBED_Peer *p2,
 864                                         enum GNUNET_TESTBED_ConnectOption co, ...);
 865
 866
 867
 868 /**
 869  * Topologies supported for testbeds.
 870  */
 871 enum GNUNET_TESTBED_TopologyOption
 872 {
 873   /**
 874    * A clique (everyone connected to everyone else).  No options.
 875    */
 876   GNUNET_TESTBED_TOPOLOGY_CLIQUE,
 877
 878   /**
 879    * Small-world network (2d torus plus random links).  Followed
 880    * by the number of random links to add (unsigned int).
 881    */
 882   GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD,
 883
 884   /**
 885    * Small-world network (ring plus random links).  Followed
 886    * by the number of random links to add (unsigned int).
 887    */
 888   GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING,
 889
 890   /**
 891    * Ring topology.  No options.
 892    */
 893   GNUNET_TESTBED_TOPOLOGY_RING,
 894
 895   /**
 896    * 2-d torus.  No options.
 897    */
 898   GNUNET_TESTBED_TOPOLOGY_2D_TORUS,
 899
 900   /**
 901    * Random graph.  Followed by the link density, that is the
 902    * percentage of links present in relation to a clique
 903    * (float).
 904    */
 905   GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI,
 906
 907   /**
 908    * Certain percentage of peers are unable to communicate directly
 909    * replicating NAT conditions.  Followed by the fraction of
 910    * NAT'ed peers (float).
 911    */
 912   GNUNET_TESTBED_TOPOLOGY_INTERNAT,
 913
 914   /**
 915    * Scale free topology.   FIXME: options?
 916    */
 917   GNUNET_TESTBED_TOPOLOGY_SCALE_FREE,
 918
 919   /**
 920    * Straight line topology.  No options.
 921    */
 922   GNUNET_TESTBED_TOPOLOGY_LINE,
 923
 924   /**
 925    * All peers are disconnected.  No options.
 926    */
 927   GNUNET_TESTBED_TOPOLOGY_NONE,
 928
 929   /**
 930    * Read a topology from a given file.  Followed by the name of the file (const char *).
 931    */
 932   GNUNET_TESTBED_TOPOLOGY_FROM_FILE
 933 };
 934
 935
 936 /**
 937  * Configure overall network topology to have a particular shape.
 938  *
 939  * @param op_cls closure argument to give with the operation event
 940  * @param num_peers number of peers in 'peers'
 941  * @param peers array of 'num_peers' with the peers to configure
 942  * @param topo desired underlay topology to use
 943  * @param ap topology-specific options
 944  * @return handle to the operation, NULL if configuring the topology
 945  *         is not allowed at this time
 946  */
 947 struct GNUNET_TESTBED_Operation *
 948 GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls,
 949                                                unsigned int num_peers,
 950                                                struct GNUNET_TESTBED_Peer **peers,
 951                                                enum GNUNET_TESTBED_TopologyOption topo,
 952                                                va_list ap);
 953
 954
 955 /**
 956  * Configure overall network topology to have a particular shape.
 957  *
 958  * @param op_cls closure argument to give with the operation event
 959  * @param num_peers number of peers in 'peers'
 960  * @param peers array of 'num_peers' with the peers to configure
 961  * @param topo desired underlay topology to use
 962  * @param ... topology-specific options
 963  * @return handle to the operation, NULL if configuring the topology
 964  *         is not allowed at this time
 965  */
 966 struct GNUNET_TESTBED_Operation *
 967 GNUNET_TESTBED_underlay_configure_topology (void *op_cls,
 968                                             unsigned int num_peers,
 969                                             struct GNUNET_TESTBED_Peer **peers,
 970                                             enum GNUNET_TESTBED_TopologyOption topo,
 971                                             ...);
 972
 973
 974 /**
 975  * Both peers must have been started before calling this function.
 976  * This function then obtains a HELLO from 'p1', gives it to 'p2'
 977  * and asks 'p2' to connect to 'p1'.
 978  *
 979  * @param op_cls closure argument to give with the operation event
 980  * @param cb the callback to call when this operation has finished
 981  * @param cb_cls the closure for the above callback
 982  * @param p1 first peer
 983  * @param p2 second peer
 984  * @return handle to the operation, NULL if connecting these two
 985  *         peers is fundamentally not possible at this time (peers
 986  *         not running or underlay disallows)
 987  */
 988 struct GNUNET_TESTBED_Operation *
 989 GNUNET_TESTBED_overlay_connect (void *op_cls,
 990                                 GNUNET_TESTBED_OperationCompletionCallback cb,
 991                                 void *cb_cls,
 992                                 struct GNUNET_TESTBED_Peer *p1,
 993                                 struct GNUNET_TESTBED_Peer *p2);
 994
 995
 996 /**
 997  * All peers must have been started before calling this function.
 998  * This function then connects the given peers in the P2P overlay
 999  * using the given topology.
1000  *
1001  * @param op_cls closure argument to give with the operation event
1002  * @param num_peers number of peers in 'peers'
1003  * @param peers array of 'num_peers' with the peers to configure
1004  * @param topo desired underlay topology to use
1005  * @param va topology-specific options
1006  * @return handle to the operation, NULL if connecting these
1007  *         peers is fundamentally not possible at this time (peers
1008  *         not running or underlay disallows) or if num_peers is less than 2
1009  */
1010 struct GNUNET_TESTBED_Operation *
1011 GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls,
1012                                               unsigned int num_peers,
1013                                               struct GNUNET_TESTBED_Peer **peers,
1014                                               enum GNUNET_TESTBED_TopologyOption topo,
1015                                               va_list va);
1016
1017
1018 /**
1019  * All peers must have been started before calling this function.
1020  * This function then connects the given peers in the P2P overlay
1021  * using the given topology.
1022  *
1023  * @param op_cls closure argument to give with the operation event
1024  * @param num_peers number of peers in 'peers'
1025  * @param peers array of 'num_peers' with the peers to configure
1026  * @param topo desired underlay topology to use
1027  * @param ... topology-specific options
1028  * @return handle to the operation, NULL if connecting these
1029  *         peers is fundamentally not possible at this time (peers
1030  *         not running or underlay disallows) or if num_peers is less than 2
1031  */
1032 struct GNUNET_TESTBED_Operation *
1033 GNUNET_TESTBED_overlay_configure_topology (void *op_cls,
1034                                            unsigned int num_peers,
1035                                            struct GNUNET_TESTBED_Peer **peers,
1036                                            enum GNUNET_TESTBED_TopologyOption topo,
1037                                            ...);
1038
1039
1040 /**
1041  * Ask the testbed controller to write the current overlay topology to
1042  * a file.  Naturally, the file will only contain a snapshot as the
1043  * topology may evolve all the time.
1044  * FIXME: needs continuation!?
1045  *
1046  * @param controller overlay controller to inspect
1047  * @param filename name of the file the topology should
1048  *        be written to.
1049  */
1050 void
1051 GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller *controller,
1052                                                const char *filename);
1053
1054
1055 /**
1056  * Adapter function called to establish a connection to
1057  * a service.
1058  *
1059  * @param cls closure
1060  * @param cfg configuration of the peer to connect to; will be available until
1061  *          GNUNET_TESTBED_operation_done() is called on the operation returned
1062  *          from GNUNET_TESTBED_service_connect()
1063  * @return service handle to return in 'op_result', NULL on error
1064  */
1065 typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls,
1066                                                 const struct GNUNET_CONFIGURATION_Handle *cfg);
1067
1068
1069 /**
1070  * Adapter function called to destroy a connection to
1071  * a service.
1072  *
1073  * @param cls closure
1074  * @param op_result service handle returned from the connect adapter
1075  */
1076 typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls,
1077                                                  void *op_result);
1078
1079
1080 /**
1081  * Callback to be called when a service connect operation is completed
1082  *
1083  * @param cls the callback closure from functions generating an operation
1084  * @param op the operation that has been finished
1085  * @param ca_result the service handle returned from GNUNET_TESTBED_ConnectAdapter()
1086  * @param emsg error message in case the operation has failed; will be NULL if
1087  *          operation has executed successfully.
1088  */
1089 typedef void (*GNUNET_TESTBED_ServiceConnectCompletionCallback) (void *cls,
1090                                                                  struct
1091                                                                  GNUNET_TESTBED_Operation
1092                                                                  *op,
1093                                                                  void
1094                                                                  *ca_result,
1095                                                                  const char
1096                                                                  *emsg );
1097
1098
1099 /**
1100  * Connect to a service offered by the given peer.  Will ensure that
1101  * the request is queued to not overwhelm our ability to create and
1102  * maintain connections with other systems.  The actual service
1103  * handle is then returned via the 'op_result' member in the event
1104  * callback.  The 'ca' callback is used to create the connection
1105  * when the time is right; the 'da' callback will be used to
1106  * destroy the connection (upon 'GNUNET_TESTBED_operation_done').
1107  * 'GNUNET_TESTBED_operation_cancel' can be used to abort this
1108  * operation until the event callback has been called.
1109  *
1110  * @param op_cls closure to pass in operation event
1111  * @param peer peer that runs the service
1112  * @param service_name name of the service to connect to
1113  * @param cb the callback to call when this operation finishes
1114  * @param cb_cls closure for the above callback
1115  * @param ca helper function to establish the connection
1116  * @param da helper function to close the connection
1117  * @param cada_cls closure for ca and da
1118  * @return handle for the operation
1119  */
1120 struct GNUNET_TESTBED_Operation *
1121 GNUNET_TESTBED_service_connect (void *op_cls,
1122                                 struct GNUNET_TESTBED_Peer *peer,
1123                                 const char *service_name,
1124                                 GNUNET_TESTBED_ServiceConnectCompletionCallback cb,
1125                                 void *cb_cls,
1126                                 GNUNET_TESTBED_ConnectAdapter ca,
1127                                 GNUNET_TESTBED_DisconnectAdapter da,
1128                                 void *cada_cls);
1129
1130
1131 /**
1132  * Cancel a pending operation.  Releases all resources
1133  * of the operation and will ensure that no event
1134  * is generated for the operation.  Does NOT guarantee
1135  * that the operation will be fully undone (or that
1136  * nothing ever happened).
1137  *
1138  * @param operation operation to cancel
1139  */
1140 void
1141 GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation);
1142
1143
1144 /**
1145  * Signal that the information from an operation has been fully
1146  * processed.  This function MUST be called for each event
1147  * of type 'operation_finished' to fully remove the operation
1148  * from the operation queue.  After calling this function, the
1149  * 'op_result' becomes invalid (!).
1150  *
1151  * @param operation operation to signal completion for
1152  */
1153 void
1154 GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation);
1155
1156
1157 /**
1158  * Configure and run a testbed using the given
1159  * master controller on 'num_hosts' starting
1160  * 'num_peers' using the given peer configuration.
1161  *
1162  * @param controller master controller for the testbed
1163  *                   (must not be destroyed until after the
1164  *                    testbed is destroyed).
1165  * @param num_hosts number of hosts in 'hosts', 0 to only
1166  *        use 'localhost'
1167  * @param hosts list of hosts to use for the testbed
1168  * @param num_peers number of peers to start
1169  * @param peer_cfg peer configuration template to use
1170  * @param underlay_topology underlay topology to create
1171  * @param va topology-specific options
1172  * @return handle to the testbed
1173  */
1174 struct GNUNET_TESTBED_Testbed *
1175 GNUNET_TESTBED_create_va (struct GNUNET_TESTBED_Controller *controller,
1176                           unsigned int num_hosts,
1177                           struct GNUNET_TESTBED_Host **hosts,
1178                           unsigned int num_peers,
1179                           const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
1180                           enum GNUNET_TESTBED_TopologyOption underlay_topology,
1181                           va_list va);
1182
1183
1184 /**
1185  * Configure and run a testbed using the given
1186  * master controller on 'num_hosts' starting
1187  * 'num_peers' using the given peer configuration.
1188  *
1189  * @param controller master controller for the testbed
1190  *                   (must not be destroyed until after the
1191  *                    testbed is destroyed).
1192  * @param num_hosts number of hosts in 'hosts', 0 to only
1193  *        use 'localhost'
1194  * @param hosts list of hosts to use for the testbed
1195  * @param num_peers number of peers to start
1196  * @param peer_cfg peer configuration template to use
1197  * @param underlay_topology underlay topology to create
1198  * @param ... topology-specific options
1199  */
1200 struct GNUNET_TESTBED_Testbed *
1201 GNUNET_TESTBED_create (struct GNUNET_TESTBED_Controller *controller,
1202                        unsigned int num_hosts,
1203                        struct GNUNET_TESTBED_Host **hosts,
1204                        unsigned int num_peers,
1205                        const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
1206                        enum GNUNET_TESTBED_TopologyOption underlay_topology,
1207                        ...);
1208
1209
1210 /**
1211  * Destroy a testbed.  Stops all running peers and then
1212  * destroys all peers.  Does NOT destroy the master controller.
1213  *
1214  * @param testbed testbed to destroy
1215  */
1216 void
1217 GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed);
1218
1219
1220 /**
1221  * Callback function to process statistic values from all peers.
1222  *
1223  * @param cls closure
1224  * @param peer the peer the statistic belong to
1225  * @param subsystem name of subsystem that created the statistic
1226  * @param name the name of the datum
1227  * @param value the current value
1228  * @param is_persistent GNUNET_YES if the value is persistent, GNUNET_NO if not
1229  * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration
1230  */
1231 typedef int (*GNUNET_TESTBED_StatisticsIterator) (void *cls,
1232                                                   const struct GNUNET_TESTBED_Peer *peer,
1233                                                   const char *subsystem,
1234                                                   const char *name,
1235                                                   uint64_t value,
1236                                                   int is_persistent);
1237
1238
1239 /**
1240  * Convenience method that iterates over all (running) peers
1241  * and retrieves all statistics from each peer.
1242  *
1243  * @param num_peers number of peers to iterate over
1244  * @param peers array of peers to iterate over
1245  * @param proc processing function for each statistic retrieved
1246  * @param cont continuation to call once call is completed(?)
1247  * @param cls closure to pass to proc and cont
1248  * @return operation handle to cancel the operation
1249  */
1250 struct GNUNET_TESTBED_Operation *
1251 GNUNET_TESTBED_get_statistics (unsigned int num_peers,
1252                                struct GNUNET_TESTBED_Peer **peers,
1253                                GNUNET_TESTBED_StatisticsIterator proc,
1254                                GNUNET_TESTBED_OperationCompletionCallback cont,
1255                                void *cls);
1256
1257
1258 /**
1259  * Convenience method for running a testbed with
1260  * a single call.  Underlay and overlay topology
1261  * are configured using the "UNDERLAY" and "OVERLAY"
1262  * options in the "[testbed]" section of the configuration\
1263  * (with possible options given in "UNDERLAY_XXX" and/or
1264  * "OVERLAY_XXX").
1265  *
1266  * The testbed is to be terminated using a call to
1267  * "GNUNET_SCHEDULER_shutdown".
1268  *
1269  * @param host_filename name of the file with the 'hosts', NULL
1270  *        to run everything on 'localhost'
1271  * @param cfg configuration to use (for testbed, controller and peers)
1272  * @param num_peers number of peers to start; FIXME: maybe put that ALSO into
1273  *        cfg?; should be greater than 0
1274  * @param event_mask bit mask with set of events to call 'cc' for;
1275  *                   or-ed values of "1LL" shifted by the
1276  *                   respective 'enum GNUNET_TESTBED_EventType'
1277  *                   (i.e.  "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...")
1278  * @param cc controller callback to invoke on events; This callback is called
1279  *        for all peer start events even if GNUNET_TESTBED_ET_PEER_START isn't
1280  *        set in the event_mask as this is the only way get access to the
1281  *        handle of each peer
1282  * @param cc_cls closure for cc
1283  * @param master task to run once the testbed is ready
1284  * @param master_cls closure for 'task'.
1285  */
1286 void
1287 GNUNET_TESTBED_run (const char *host_filename,
1288                     const struct GNUNET_CONFIGURATION_Handle *cfg,
1289                     unsigned int num_peers,
1290                     uint64_t event_mask,
1291                     GNUNET_TESTBED_ControllerCallback cc,
1292                     void *cc_cls,
1293                     GNUNET_SCHEDULER_Task master,
1294                     void *master_cls);
1295
1296
1297 /**
1298  * Signature of a main function for a testcase.
1299  *
1300  * @param cls closure
1301  * @param num_peers number of peers in 'peers'
1302  * @param peers handle to peers run in the testbed
1303  */
1304 typedef void (*GNUNET_TESTBED_TestMaster)(void *cls,
1305                                           unsigned int num_peers,
1306                                           struct GNUNET_TESTBED_Peer **peers);
1307
1308
1309 /**
1310  * Convenience method for running a "simple" test on the local system
1311  * with a single call from 'main'.  Underlay and overlay topology are
1312  * configured using the "UNDERLAY" and "OVERLAY" options in the
1313  * "[testbed]" section of the configuration (with possible options
1314  * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX").
1315  *
1316  * The test is to be terminated using a call to
1317  * "GNUNET_SCHEDULER_shutdown".  If starting the test fails,
1318  * the program is stopped without 'master' ever being run.
1319  *
1320  * NOTE: this function should be called from 'main', NOT from
1321  * within a GNUNET_SCHEDULER-loop.  This function will initialze
1322  * the scheduler loop, the testbed and then pass control to
1323  * 'master'.
1324  *
1325  * @param testname name of the testcase (to configure logging, etc.)
1326  * @param cfg_filename configuration filename to use
1327  *              (for testbed, controller and peers)
1328  * @param num_peers number of peers to start; should be greter than 0
1329  * @param event_mask bit mask with set of events to call 'cc' for;
1330  *                   or-ed values of "1LL" shifted by the
1331  *                   respective 'enum GNUNET_TESTBED_EventType'
1332  *                   (i.e.  "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...")
1333  * @param cc controller callback to invoke on events; This callback is called
1334  *        for all peer start events even if GNUNET_TESTBED_ET_PEER_START isn't
1335  *        set in the event_mask as this is the only way get access to the
1336  *        handle of each peer
1337  * @param cc_cls closure for cc
1338  * @param test_master task to run once the test is ready
1339  * @param test_master_cls closure for 'task'.
1340  */
1341 void
1342 GNUNET_TESTBED_test_run (const char *testname,
1343                          const char *cfg_filename,
1344                          unsigned int num_peers,
1345                          uint64_t event_mask,
1346                          GNUNET_TESTBED_ControllerCallback cc,
1347                          void *cc_cls,
1348                          GNUNET_TESTBED_TestMaster test_master,
1349                          void *test_master_cls);
1350
1351
1352 #if 0                           /* keep Emacsens' auto-indent happy */
1353 {
1354 #endif
1355
1356
1357 #ifdef __cplusplus
1358 }
1359 #endif
1360
1361 #endif