#define GNUNET_TESTBED_SERVICE_H
#include "gnunet_util_lib.h"
+#include "gnunet_testing_lib-new.h"
#ifdef __cplusplus
extern "C"
struct GNUNET_TESTBED_Operation;
/**
- * Handle to interact with a GNUnet testbed controller. Each controller has at
- * least one master handle which is created when the controller is created; this
- * master handle interacts with the controller via stdin/stdout of the controller
- * process. Additionally, controllers can interact with each other (in a P2P
- * fashion); those links are established via TCP/IP on the controller's service
- * port.
+ * Handle to interact with a GNUnet testbed controller. Each
+ * controller has at least one master handle which is created when the
+ * controller is created; this master handle interacts with the
+ * controller process, destroying it destroys the controller (by
+ * closing stdin of the controller process). Additionally,
+ * controllers can interact with each other (in a P2P fashion); those
+ * links are established via TCP/IP on the controller's service port.
*/
struct GNUNET_TESTBED_Controller;
uint16_t port);
+
+/**
+ * Create a host to run peers and controllers on. This function is used
+ * if a peer learns about a host via IPC between controllers (and thus
+ * some higher-level controller has already determined the unique IDs).
+ *
+ * @param id global host ID assigned to the host; 0 is
+ * reserved to always mean 'localhost'
+ * @param hostname name of the host, use "NULL" for localhost
+ * @param username username to use for the login; may be NULL
+ * @param port port number to use for ssh; use 0 to let ssh decide
+ * @return handle to the host, NULL on error
+ */
+struct GNUNET_TESTBED_Host *
+GNUNET_TESTBED_host_create_with_id (uint32_t id,
+ const char *hostname,
+ const char *username,
+ uint16_t port);
+
+
/**
* Load a set of hosts from a configuration file.
*
*/
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
* @param event information about the event
*/
typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls,
- const struct GNUNET_TESTBED_EventInformation *event);
+ const struct GNUNET_TESTBED_EventInformation *event);
+
+
+/**
+ * Opaque Handle for Controller process
+ */
+struct GNUNET_TESTBED_ControllerProc;
+
+
+/**
+ * Callback to signal successfull startup of the controller process
+ *
+ * @param cls the closure from GNUNET_TESTBED_controller_start()
+ * @param cfg the configuration with which the controller has been started;
+ * NULL if status is not GNUNET_OK
+ * @param status GNUNET_OK if the startup is successfull; GNUNET_SYSERR if not,
+ * GNUNET_TESTBED_controller_stop() shouldn't be called in this case
+ */
+typedef void (*GNUNET_TESTBED_ControllerStatusCallback) (void *cls,
+ const struct GNUNET_CONFIGURATION_Handle *cfg,
+ int status);
/**
- * Start a controller process using the given configuration at the
+ * Starts a controller process at the host. FIXME: add controller start callback
+ * with the configuration with which the controller is started
+ *
+ * @param controller_ip the ip address of the controller. Will be set as TRUSTED
+ * host when starting testbed controller at host
+ * @param host the host where the controller has to be started; NULL for
+ * localhost
+ * @param cfg template configuration to use for the remote controller; the
+ * remote controller will be started with a slightly modified
+ * configuration (port numbers, unix domain sockets and service home
+ * values are changed as per TESTING library on the remote host)
+ * @param cb function called when the controller is successfully started or
+ * dies unexpectedly; GNUNET_TESTBED_controller_stop shouldn't be
+ * called if cb is called with GNUNET_SYSERR as status. Will never be
+ * called in the same task as 'GNUNET_TESTBED_controller_start'
+ * (synchronous errors will be signalled by returning NULL). This
+ * parameter cannot be NULL.
+ * @param cls closure for above callbacks
+ * @return the controller process handle, NULL on errors
+ */
+struct GNUNET_TESTBED_ControllerProc *
+GNUNET_TESTBED_controller_start (const char *controller_ip,
+ struct GNUNET_TESTBED_Host *host,
+ const struct GNUNET_CONFIGURATION_Handle *cfg,
+ GNUNET_TESTBED_ControllerStatusCallback cb,
+ void *cls);
+
+
+/**
+ * Stop the controller process (also will terminate all peers and controllers
+ * dependent on this controller). This function blocks until the testbed has
+ * been fully terminated (!).
+ *
+ * @param cproc the controller process handle
+ */
+void
+GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_ControllerProc *cproc);
+
+
+/**
+ * Connect to a controller process using the given configuration at the
* given host.
*
* @param cfg configuration to use
- * @param host host to run the controller on, NULL for 'localhost'
+ * @param host host to run the controller on; This should be the same host if
+ * the controller was previously started with
+ * GNUNET_TESTBED_controller_start; NULL for localhost
+ * @param host host where this controller is being run;
* @param event_mask bit mask with set of events to call 'cc' for;
* or-ed values of "1LL" shifted by the
* respective 'enum GNUNET_TESTBED_EventType'
* @return handle to the controller
*/
struct GNUNET_TESTBED_Controller *
-GNUNET_TESTBED_controller_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
- struct GNUNET_TESTBED_Host *host,
- uint64_t event_mask,
- GNUNET_TESTBED_ControllerCallback cc,
- void *cc_cls);
+GNUNET_TESTBED_controller_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ struct GNUNET_TESTBED_Host *host,
+ uint64_t event_mask,
+ GNUNET_TESTBED_ControllerCallback cc,
+ void *cc_cls);
/**
* @param controller handle to controller to stop
*/
void
-GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_Controller *controller);
+GNUNET_TESTBED_controller_disconnect (struct GNUNET_TESTBED_Controller *controller);
+
+
+/**
+ * Opaque handle for host registration
+ */
+struct GNUNET_TESTBED_HostRegistrationHandle;
+
+
+/**
+ * Callback which will be called to after a host registration succeeded or failed
+ *
+ * @param cls the closure
+ * @param emsg the error message; NULL if host registration is successful
+ */
+typedef void (* GNUNET_TESTBED_HostRegistrationCompletion) (void *cls,
+ const char *emsg);
+
+
+/**
+ * Register a host with the controller
+ *
+ * @param controller the controller handle
+ * @param host the host to register
+ * @param cc the completion callback to call to inform the status of
+ * registration. After calling this callback the registration handle
+ * will be invalid. Cannot be NULL
+ * @param cc_cls the closure for the cc
+ * @return handle to the host registration which can be used to cancel the
+ * registration; NULL if another registration handle is present and
+ * is not cancelled
+ */
+struct GNUNET_TESTBED_HostRegistrationHandle *
+GNUNET_TESTBED_register_host (struct GNUNET_TESTBED_Controller *controller,
+ struct GNUNET_TESTBED_Host *host,
+ GNUNET_TESTBED_HostRegistrationCompletion cc,
+ void *cc_cls);
+
+
+/**
+ * Cancel the pending registration. Note that the registration message will
+ * already be queued to be sent to the service, cancellation has only the
+ * effect that the registration completion callback for the registration is
+ * never called and from our perspective the host is not registered until the
+ * completion callback is called.
+ *
+ * @param handle the registration handle to cancel
+ */
+void
+GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle
+ *handle);
/**
- * Create a link from a 'master' controller to a slave controller.
- * Whenever the master controller is asked to start a peer at the
- * given 'delegated_host', it will delegate the request to the
- * specified slave controller. Note that the slave controller runs at
- * the 'slave_host', which may or may not be the same host as the
- * 'delegated_host' (for hierarchical delegations). The configuration
- * of the slave controller is given and to be used to either create
- * the slave controller or to connect to an existing slave controller
- * process. 'is_subordinate' specifies if the given slave controller
- * should be started and managed by the master controller, or if the
- * slave already has a master and this is just a secondary master that
- * is also allowed to use the existing slave.
+ * Create a link from slave controller to delegated controller. Whenever the
+ * master controller is asked to start a peer at the delegated controller the
+ * request will be routed towards slave controller (if a route exists). The
+ * slave controller will then route it to the delegated controller. The
+ * configuration of the slave controller is given and to be used to either
+ * create the slave controller or to connect to an existing slave controller
+ * process. 'is_subordinate' specifies if the given slave controller should be
+ * started and managed by the master controller, or if the slave already has a
+ * master and this is just a secondary master that is also allowed to use the
+ * existing slave.
*
* @param master handle to the master controller who creates the association
- * @param delegated_host requests to which host should be delegated
- * @param slave_host which host is used to run the slave controller
+ * @param delegated_host requests to which host should be delegated; cannot be NULL
+ * @param slave_host which host is used to run the slave controller; use NULL to
+ * make the master controller connect to the delegated host
* @param slave_cfg configuration to use for the slave controller
- * @param is_subordinate GNUNET_YES if the slave should be started (and stopped)
- * by the master controller; GNUNET_NO if we are just
- * allowed to use the slave via TCP/IP
+ * @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,
int is_subordinate);
+/**
+ * Same as the GNUNET_TESTBED_controller_link, however expects configuration in
+ * serialized and compressed
+ *
+ * @param master handle to the master controller who creates the association
+ * @param delegated_host requests to which host should be delegated; cannot be NULL
+ * @param slave_host which host is used to run the slave controller; use NULL to
+ * make the master controller connect to the delegated host
+ * @param sxcfg serialized and compressed configuration
+ * @param sxcfg_size the size scfg
+ * @param scfg_size the size of uncompressed serialized configuration
+ * @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
+ */
+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,
+ const char *sxcfg,
+ size_t sxcfg_size,
+ size_t scfg_size,
+ int is_subordinate);
+
+
+/**
+ * Functions of this signature are called when a peer has been successfully
+ * created
+ *
+ * @param cls the closure from GNUNET_TESTBED_peer_create()
+ * @param peer the handle for the created peer; NULL on any error during
+ * creation
+ * @param emsg NULL if peer is not NULL; else MAY contain the error description
+ */
+typedef void (*GNUNET_TESTBED_PeerCreateCallback) (void *cls,
+ struct GNUNET_TESTBED_Peer *peer,
+ const char *emsg);
+
+
/**
* Create the given peer at the specified host using the given
* controller. If the given controller is not running on the target
*
* @param controller controller process to use
* @param host host to run the peer on
- * @param cfg configuration to use for the peer
- * @return handle to the peer (actual startup will happen asynchronously)
+ * @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
*/
-struct GNUNET_TESTBED_Peer *
+struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller,
struct GNUNET_TESTBED_Host *host,
- const struct GNUNET_CONFIGURATION_Handle *cfg);
+ const struct GNUNET_CONFIGURATION_Handle *cfg,
+ GNUNET_TESTBED_PeerCreateCallback cb,
+ void *cls);
/**
...);
-
/**
* Ask the testbed controller to write the current overlay topology to
* a file. Naturally, the file will only contain a snapshot as the
* 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,
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
* (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'
* 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,
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.
*
* "[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
projects / oweals / gnunet.git / blobdiff