GNUNET_TESTBED_run to return a handle which can be used for clean shutdown

[oweals/gnunet.git] / src / include / gnunet_testbed_service.h

diff --git a/src/include/gnunet_testbed_service.h b/src/include/gnunet_testbed_service.h
index 19928623fb1b4c92a337ea105a9a79c30a8cbfed..37ffcb75054be94ba14f6974449f7da73dd3a05e 100644 (file)
--- a/src/include/gnunet_testbed_service.h
+++ b/src/include/gnunet_testbed_service.h
@@ -184,13 +184,6 @@ enum GNUNET_TESTBED_PeerInformationType
    */
   GNUNET_TESTBED_PIT_GENERIC = 0,
 
-  /**
-   * What host is the peer running on?  Returns a 'const struct
-   * GNUNET_TESTBED_Host *'.  Valid until
-   * 'GNUNET_TESTBED_operation_done' is called.
-   */
-  GNUNET_TESTBED_PIT_HOST,
-
   /**
    * What configuration is the peer using?  Returns a 'const struct
    * GNUNET_CONFIGURATION_Handle *'.  Valid until
@@ -581,8 +574,9 @@ GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle
  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
  *          be started by the master controller; GNUNET_NO if we are just
  *          allowed to use the slave via TCP/IP
+ * @return the operation handle
  */
-void
+struct GNUNET_TESTBED_Operation *
 GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master,
                                struct GNUNET_TESTBED_Host *delegated_host,
                                struct GNUNET_TESTBED_Host *slave_host,
@@ -604,8 +598,9 @@ GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master,
  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
  *          be started by the master controller; GNUNET_NO if we are just
  *          allowed to use the slave via TCP/IP
+ * @return the operation handle
  */
-void
+struct GNUNET_TESTBED_Operation *
 GNUNET_TESTBED_controller_link_2 (struct GNUNET_TESTBED_Controller *master,
                                  struct GNUNET_TESTBED_Host *delegated_host,
                                  struct GNUNET_TESTBED_Host *slave_host,
@@ -652,7 +647,8 @@ typedef void (*GNUNET_TESTBED_PeerCreateCallback) (void *cls,
  *
  * @param controller controller process to use
  * @param host host to run the peer on
- * @param cfg configuration to use for the peer
+ * @param cfg Template configuration to use for the peer. Should exist until
+ *          operation is cancelled or GNUNET_TESTBED_operation_done() is called
  * @param cb the callback to call when the peer has been created
  * @param cls the closure to the above callback
  * @return the operation handle
@@ -980,7 +976,9 @@ GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller
  * a service.
  * 
  * @param cls closure
- * @param cfg configuration of the peer to connect to
+ * @param cfg configuration of the peer to connect to; will be available until
+ *          GNUNET_TESTBED_operation_done() is called on the operation returned
+ *          from GNUNET_TESTBED_service_connect()
  * @return service handle to return in 'op_result', NULL on error
  */
 typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls,
@@ -1115,6 +1113,12 @@ void
 GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed);
 
 
+/**
+ * Opaque handle to testbed run
+ */
+struct GNUNET_TESTBED_RunHandle;
+
+
 /**
  * Convenience method for running a testbed with
  * a single call.  Underlay and overlay topology
@@ -1123,8 +1127,7 @@ GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed);
  * (with possible options given in "UNDERLAY_XXX" and/or
  * "OVERLAY_XXX").
  *
- * The testbed is to be terminated using a call to
- * "GNUNET_SCHEDULER_shutdown".
+ * The testbed is to be terminated using a calling GNUNET_TESTBED_shutdown_run()
  *
  * @param host_filename name of the file with the 'hosts', NULL
  *        to run everything on 'localhost'
@@ -1134,12 +1137,16 @@ GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed);
  *                   or-ed values of "1LL" shifted by the
  *                   respective 'enum GNUNET_TESTBED_EventType'
  *                   (i.e.  "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...")
- * @param cc controller callback to invoke on events
+ * @param cc controller callback to invoke on events; This callback is called
+ *        for all peer start events even if GNUNET_TESTBED_ET_PEER_START isn't
+ *        set in the event_mask as this is the only way get access to the
+ *        handle of each peer
  * @param cc_cls closure for cc
  * @param master task to run once the testbed is ready
  * @param master_cls closure for 'task'.
+ * @return the handle for this testbed run
  */
-void
+struct GNUNET_TESTBED_RunHandle *
 GNUNET_TESTBED_run (const char *host_filename,
                    const struct GNUNET_CONFIGURATION_Handle *cfg,
                    unsigned int num_peers,
@@ -1150,6 +1157,15 @@ GNUNET_TESTBED_run (const char *host_filename,
                    void *master_cls);
 
 
+/**
+ * Stops the testbed run and releases any used resources
+ *
+ * @param rh the tesbed run handle
+ */
+void
+GNUNET_TESTBED_shutdown_run (struct GNUNET_TESTBED_RunHandle *rh);
+
+
 /**
  * Signature of a main function for a testcase.
  * 
@@ -1169,9 +1185,9 @@ typedef void (*GNUNET_TESTBED_TestMaster)(void *cls,
  * "[testbed]" section of the configuration (with possible options
  * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX").
  *
- * The test is to be terminated using a call to
- * "GNUNET_SCHEDULER_shutdown".  If starting the test fails,
- * the program is stopped without 'master' ever being run.
+ * The test is to be terminated by calling GNUNET_TESTBED_shutdown_run()
+ * If starting the test fails, the program is stopped without 'master' ever
+ * being run
  *
  * NOTE: this function should be called from 'main', NOT from
  * within a GNUNET_SCHEDULER-loop.  This function will initialze