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