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