/**
- * Load a set of hosts from a configuration file.
+ * Load a set of hosts from a configuration file. The hostfile format is
+ * specified at https://gnunet.org/content/hosts-file-format
*
* @param filename file with the host specification
* @param cfg the configuration to use as a template while starting a controller
* controller connects to it as a non master controller. The success or failure
* of this operation will be signalled through the
* GNUNET_TESTBED_ControllerCallback() with an event of type
- * GNUNET_TESTBED_ET_OPERATION_FINISHED
+ * #GNUNET_TESTBED_ET_OPERATION_FINISHED
*
* @param op_cls the operation closure for the event which is generated to
* signal success or failure of this operation
* @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 is_subordinate GNUNET_YES if the controller at delegated_host should
- * be started by the slave controller; GNUNET_NO if the slave
+ * @param is_subordinate #GNUNET_YES if the controller at delegated_host should
+ * be started by the slave controller; #GNUNET_NO if the slave
* controller has to connect to the already started delegated
* controller via TCP/IP
* @return the operation handle
int is_subordinate);
-/**
- * Same as the GNUNET_TESTBED_controller_link, however expects configuration in
- * serialized and compressed
- *
- * @param op_cls the operation closure for the event which is generated to
- * signal success or failure of this operation
- * @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 sxcfg
- * @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 slave controller; GNUNET_NO if the slave
- * controller has to connect to the already started delegated
- * controller via TCP/IP
- * @return the operation handle
- */
-struct GNUNET_TESTBED_Operation *
-GNUNET_TESTBED_controller_link_2 (void *op_cls,
- 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);
-
-
/**
* Function to acquire the configuration of a running slave controller. The
* completion of the operation is signalled through the controller_cb from
* GNUNET_TESTBED_controller_connect(). If the operation is successful the
* handle to the configuration is available in the generic pointer of
- * operation_finished field of struct GNUNET_TESTBED_EventInformation.
+ * operation_finished field of `struct GNUNET_TESTBED_EventInformation`.
*
* @param op_cls the closure for the operation
* @param master the handle to master controller
* to the remote host is stopped.
*
* Creating the peer only creates the handle to manipulate and further
- * configure the peer; use "GNUNET_TESTBED_peer_start" and
- * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's
+ * configure the peer; use #GNUNET_TESTBED_peer_start and
+ * #GNUNET_TESTBED_peer_stop to actually start/stop the peer's
* processes.
*
* Note that the given configuration will be adjusted by the
* controller to avoid port/path conflicts with other peers.
* The "final" configuration can be obtained using
- * 'GNUNET_TESTBED_peer_get_information'.
+ * #GNUNET_TESTBED_peer_get_information.
*
* @param controller controller process to use
* @param host host to run the peer on; cannot be NULL
/**
* Stop the given peer. The handle remains valid (use
- * "GNUNET_TESTBED_peer_destroy" to fully clean up the
+ * #GNUNET_TESTBED_peer_destroy to fully clean up the
* state of the peer).
*
* @param op_cls the closure for this operation; will be set in the event
/**
* Callback to be called when the requested peer information is available
+ * The peer information in the callback is valid until the operation 'op' is canceled.
*
* @param cb_cls the closure from GNUNET_TETSBED_peer_get_information()
* @param op the operation this callback corresponds to
/**
* Request information about a peer. The controller callback will not be called
- * with event type GNUNET_TESTBED_ET_OPERATION_FINISHED when result for this
+ * with event type #GNUNET_TESTBED_ET_OPERATION_FINISHED when result for this
* operation is available. Instead, the GNUNET_TESTBED_PeerInfoCallback() will
* be called.
+ * The peer information in the callback is valid until the operation is canceled.
*
* @param peer peer to request information about
* @param pit desired information
* @param cb the convenience callback to be called when results for this
* operation are available
- * @param cb_cls the closure for the above callback
+ * @param cb_cls the closure for @a cb
* @return handle to the operation
*/
struct GNUNET_TESTBED_Operation *
/**
- * Change peer configuration. Must only be called while the
- * peer is stopped. Ports and paths cannot be changed this
+ * Change @a peer configuration. Ports and paths cannot be changed this
* way.
*
* @param peer peer to change configuration for
- * @param cfg new configuration (differences to existing
- * configuration only)
+ * @param cfg new configuration
* @return handle to the operation
*/
struct GNUNET_TESTBED_Operation *
* @param peer the peer whose service is to be started/stopped
* @param service_name the name of the service
* @param cb the operation completion callback
- * @param cb_cls the closure for the operation completion callback
+ * @param cb_cls the closure for @a cb
* @param start 1 to start the service; 0 to stop the service
* @return an operation handle; NULL upon error (peer not running)
*/
/**
* Allow or disallow a connection between the specified peers.
- * Followed by GNUNET_NO (int) if a connection is disallowed
- * or GNUNET_YES if a connection is allowed. Note that the
+ * Followed by #GNUNET_NO (int) if a connection is disallowed
+ * or #GNUNET_YES if a connection is allowed. Note that the
* default (all connections allowed or disallowed) is
* specified in the configuration of the controller.
*/
GNUNET_TESTBED_TOPOLOGY_INTERNAT,
/**
- * Scale free topology. No options.
+ * Scale free topology. It is generated according to the method described in
+ * "Emergence of Scaling in Random Networks." Science 286, 509-512, 1999.
+ *
+ * This options takes two arguments in the following order: an uint16_t to
+ * determine the maximum number of edges a peer is permitted to have while
+ * generating scale free topology, a good value for this argument is 70; and
+ * an uint8_t to determine the number of edges to be established when adding a
+ * new node to the scale free network, a good value for this argument is 4.
*/
GNUNET_TESTBED_TOPOLOGY_SCALE_FREE,
/**
* Both peers must have been started before calling this function.
- * This function then obtains a HELLO from 'p1', gives it to 'p2'
- * and asks 'p2' to connect to 'p1'.
+ * This function then obtains a HELLO from @a p1, gives it to @a p2
+ * and asks @a p2 to connect to @a p1.
*
* @param op_cls closure argument to give with the operation event
* @param cb the callback to call when this operation has finished
- * @param cb_cls the closure for the above callback
+ * @param cb_cls the closure for @a cb
* @param p1 first peer
* @param p2 second peer
* @return handle to the operation, NULL if connecting these two
* @param nsuccess the number of successful overlay connects
* @param nfailures the number of overlay connects which failed
*/
-typedef void (*GNUNET_TESTBED_TopologyCompletionCallback) (void *cls,
+typedef void (*GNUNET_TESTBED_TopologyCompletionCallback) (void *cls,
unsigned int nsuccess,
unsigned int nfailures);
* be made to achieve the given topology
* @param comp_cb the completion callback to call when the topology generation
* is completed
- * @param comp_cb_cls closure for the above completion callback
+ * @param comp_cb_cls closure for the @a comp_cb
* @param topo desired underlay topology to use
* @param va topology-specific options
* @return handle to the operation, NULL if connecting these
* the request is queued to not overwhelm our ability to create and
* maintain connections with other systems. The actual service
* handle is then returned via the 'op_result' member in the event
- * callback. The 'ca' callback is used to create the connection
- * when the time is right; the 'da' callback will be used to
- * destroy the connection (upon 'GNUNET_TESTBED_operation_done').
- * 'GNUNET_TESTBED_operation_cancel' can be used to abort this
+ * callback. The @a ca callback is used to create the connection
+ * when the time is right; the @a da callback will be used to
+ * destroy the connection (upon #GNUNET_TESTBED_operation_done).
+ * #GNUNET_TESTBED_operation_done can be used to abort this
* operation until the event callback has been called.
*
* @param op_cls closure to pass in operation event // FIXME: didn't we say we'd no longer use the global callback for these? -CG
* @param peer peer that runs the service
* @param service_name name of the service to connect to
- * @param cb the callback to call when this operation finishes
- * @param cb_cls closure for the above callback
+ * @param cb the callback to call when this operation is ready (that is,
+ * right after the connect adapter returns)
+ * @param cb_cls closure for @a cb
* @param ca helper function to establish the connection
* @param da helper function to close the connection
- * @param cada_cls closure for ca and da
+ * @param cada_cls closure for @a ca and @a da
* @return handle for the operation
*/
struct GNUNET_TESTBED_Operation *
* cancels the operation, frees its resources and ensures the no event is
* generated with respect to this operation. Note that however cancelling an
* operation does NOT guarantee that the operation will be fully undone (or that
- * nothing ever happened).
+ * nothing ever happened).
*
* This function MUST be called for every operation to fully remove the
* operation from the operation queue. After calling this function, if
GNUNET_TESTBED_OperationCompletionCallback cont,
void *cls);
+/**
+ * Handle for testbed run helper funtions
+ */
+struct GNUNET_TESTBED_RunHandle;
/**
* Signature of a main function for a testcase.
*
* @param cls closure
+ * @param h the run handle
* @param num_peers number of peers in 'peers'
* @param peers handle to peers run in the testbed. NULL upon timeout (see
* GNUNET_TESTBED_test_run()).
* succeeded
* @param links_failed the number of overlay link connection attempts that
* failed
+ * @see GNUNET_TESTBED_test_run()
*/
typedef void (*GNUNET_TESTBED_TestMaster)(void *cls,
+ struct GNUNET_TESTBED_RunHandle *h,
unsigned int num_peers,
struct GNUNET_TESTBED_Peer **peers,
unsigned int links_succeeded,
* 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 cc_cls closure for @a cc
* @param test_master this callback will be called once the test is ready or
* upon timeout
- * @param test_master_cls closure for 'test_master'.
- * @return GNUNET_SYSERR on error, GNUNET_OK on success
+ * @param test_master_cls closure for @a test_master.
+ * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
*/
int
GNUNET_TESTBED_test_run (const char *testname,
void *test_master_cls);
+/**
+ * Obtain handle to the master controller from a testbed run. The handle
+ * returned should not be disconnected.
+ *
+ * @param h the testbed run handle
+ * @return handle to the master controller
+ */
+struct GNUNET_TESTBED_Controller *
+GNUNET_TESTBED_run_get_controller_handle (struct GNUNET_TESTBED_RunHandle *h);
+
+/**
+ * Opaque handle for barrier
+ */
+struct GNUNET_TESTBED_Barrier;
+
+
+/**
+ * Status of a barrier
+ */
+enum GNUNET_TESTBED_BarrierStatus
+{
+ /**
+ * Barrier initialised successfully
+ */
+ GNUNET_TESTBED_BARRIERSTATUS_INITIALISED = 1,
+
+ /**
+ * Barrier is crossed
+ */
+ GNUNET_TESTBED_BARRIERSTATUS_CROSSED,
+
+ /**
+ * Error status
+ */
+ GNUNET_TESTBED_BARRIERSTATUS_ERROR,
+
+};
+
+
+/**
+ * Functions of this type are to be given as callback argument to
+ * GNUNET_TESTBED_barrier_init(). The callback will be called when status
+ * information is available for the barrier.
+ *
+ * @param cls the closure given to GNUNET_TESTBED_barrier_init()
+ * @param name the name of the barrier
+ * @param barrier the barrier handle
+ * @param status status of the barrier; GNUNET_OK if the barrier is crossed;
+ * GNUNET_SYSERR upon error
+ * @param emsg if the status were to be GNUNET_SYSERR, this parameter has the
+ * error messsage
+ */
+typedef void (*GNUNET_TESTBED_barrier_status_cb) (void *cls,
+ const char *name,
+ struct GNUNET_TESTBED_Barrier
+ *barrier,
+ enum GNUNET_TESTBED_BarrierStatus status,
+ const char *emsg);
+
+
+/**
+ * Initialise a barrier and call the given callback when the required percentage
+ * of peers (quorum) reach the barrier.
+ *
+ * @param controller the handle to the controller
+ * @param name identification name of the barrier
+ * @param quorum the percentage of peers that is required to reach the barrier.
+ * Peers signal reaching a barrier by calling
+ * GNUNET_TESTBED_barrier_reached().
+ * @param cb the callback to call when the barrier is reached or upon error.
+ * Cannot be NULL.
+ * @param cls closure for the above callback
+ * @return barrier handle
+ */
+struct GNUNET_TESTBED_Barrier *
+GNUNET_TESTBED_barrier_init (struct GNUNET_TESTBED_Controller *controller,
+ const char *name,
+ unsigned int quorum,
+ GNUNET_TESTBED_barrier_status_cb cb, void *cls);
+
+
+/**
+ * Cancel a barrier.
+ *
+ * @param barrier the barrier handle
+ */
+void
+GNUNET_TESTBED_barrier_cancel (struct GNUNET_TESTBED_Barrier *barrier);
+
+
+/**
+ * Opaque handle for barrier wait
+ */
+struct GNUNET_TESTBED_BarrierWaitHandle;
+
+
+/**
+ * Functions of this type are to be given as acallback argumetn to
+ * GNUNET_TESTBED_barrier_wait(). The callback will be called when the barrier
+ * corresponding given in GNUNET_TESTBED_barrier_wait() is crossed or cancelled.
+ *
+ * @param cls closure pointer given to GNUNET_TESTBED_barrier_wait()
+ * @param name the barrier name
+ * @param status GNUNET_SYSERR in case of error while waiting for the barrier;
+ * GNUNET_OK if the barrier is crossed
+ */
+typedef void (*GNUNET_TESTBED_barrier_wait_cb) (void *cls,
+ const char *name,
+ int status);
+
+
+/**
+ * Wait for a barrier to be crossed. This function should be called by the
+ * peers which have been started by the testbed. If the peer is not started by
+ * testbed this function may return error
+ *
+ * @param name the name of the barrier
+ * @param cb the barrier wait callback
+ * @param cls the closure for the above callback
+ * @return barrier wait handle which can be used to cancel the waiting at
+ * anytime before the callback is called. NULL upon error.
+ */
+struct GNUNET_TESTBED_BarrierWaitHandle *
+GNUNET_TESTBED_barrier_wait (const char *name,
+ GNUNET_TESTBED_barrier_wait_cb cb,
+ void *cls);
+
+
+/**
+ * Cancel a barrier wait handle. Should not be called in or after the callback
+ * given to GNUNET_TESTBED_barrier_wait() has been called.
+ *
+ * @param h the barrier wait handle
+ */
+void
+GNUNET_TESTBED_barrier_wait_cancel (struct GNUNET_TESTBED_BarrierWaitHandle *h);
+
+
+/**
+ * Model for configuring underlay links of a peer
+ * @ingroup underlay
+ */
+struct GNUNET_TESTBED_UnderlayLinkModel;
+
+
+/**
+ * The type of GNUNET_TESTBED_UnderlayLinkModel
+ * @ingroup underlay
+ */
+enum GNUNET_TESTBED_UnderlayLinkModelType
+{
+ /**
+ * The model is based on white listing of peers to which underlay connections
+ * are permitted. Underlay connections to all other peers will not be
+ * permitted.
+ */
+ GNUNET_TESTBED_UNDERLAYLINKMODELTYPE_BLACKLIST,
+
+ /**
+ * The model is based on black listing of peers to which underlay connections
+ * are not permitted. Underlay connections to all other peers will be
+ * permitted
+ */
+ GNUNET_TESTBED_UNDERLAYLINKMODELTYPE_WHITELIST
+};
+
+
+/**
+ * Create a GNUNET_TESTBED_UnderlayLinkModel for the given peer. A peer can
+ * have ONLY ONE model and it can be either a blacklist or whitelist based one.
+ *
+ * @ingroup underlay
+ * @param peer the peer for which the model has to be created
+ * @param type the type of the model
+ * @return the model
+ */
+struct GNUNET_TESTBED_UnderlayLinkModel *
+GNUNET_TESTBED_underlaylinkmodel_create (struct GNUNET_TESTBED_Peer *peer,
+ enum GNUNET_TESTBED_UnderlayLinkModelType type);
+
+
+/**
+ * Add a peer to the given model. Underlay connections to the given peer will
+ * be permitted if the model is whitelist based; otherwise they will not be
+ * permitted.
+ *
+ * @ingroup underlay
+ * @param model the model
+ * @param peer the peer to add
+ */
+void
+GNUNET_TESTBED_underlaylinkmodel_add_peer (struct GNUNET_TESTBED_UnderlayLinkModel *model,
+ struct GNUNET_TESTBED_Peer *peer);
+
+
+/**
+ * Set the metrics for a link to the given peer in the underlay model. The link
+ * SHOULD be permittable according to the given model.
+ *
+ * @ingroup underlay
+ * @param model the model
+ * @param peer the other end peer of the link
+ * @param latency latency of the link in microseconds
+ * @param loss data loss of the link expressed as a percentage
+ * @param bandwidth bandwidth of the link in kilobytes per second [kB/s]
+ */
+void
+GNUNET_TESTBED_underlaylinkmodel_set_link (struct GNUNET_TESTBED_UnderlayLinkModel *model,
+ struct GNUNET_TESTBED_Peer *peer,
+ uint32_t latency,
+ uint32_t loss,
+ uint32_t bandwidth);
+
+
+/**
+ * Commit the model. The model is freed in this function(!).
+ *
+ * @ingroup underlay
+ * @param model the model to commit
+ */
+void
+GNUNET_TESTBED_underlaylinkmodel_commit (struct GNUNET_TESTBED_UnderlayLinkModel *model);
+
+
+/**
+ * Free the resources of the model. Use this function only if the model has not
+ * be committed and has to be unallocated. The peer can then have another model
+ * created.
+ *
+ * @ingroup underlay
+ * @param model the model to unallocate
+ */
+void
+GNUNET_TESTBED_underlaylinkmodel_free (struct GNUNET_TESTBED_UnderlayLinkModel *model);
+
+
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
projects / oweals / gnunet.git / blobdiff