/*
This file is part of GNUnet
- (C) 2008--2013 Christian Grothoff (and other contributing authors)
+ Copyright (C) 2008--2013 GNUnet e.V.
- GNUnet is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published
- by the Free Software Foundation; either version 3, or (at your
- option) any later version.
+ GNUnet is free software: you can redistribute it and/or modify it
+ under the terms of the GNU Affero General Public License as published
+ by the Free Software Foundation, either version 3 of the License,
+ or (at your option) any later version.
GNUnet is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
+ Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
- You should have received a copy of the GNU General Public License
- along with GNUnet; see the file COPYING. If not, write to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ SPDX-License-Identifier: AGPL3.0-or-later
*/
/**
- * @file include/gnunet_testbed_service.h
- * @brief API for writing tests and creating large-scale
- * emulation testbeds for GNUnet.
* @author Christian Grothoff
+ *
+ * @file
+ * API for writing tests and creating large-scale emulation testbeds for GNUnet.
+ *
+ * @defgroup testbed Testbed service
+ * Writing tests and creating large-scale emulation testbeds for GNUnet.
+ *
+ * @see [Documentation](https://gnunet.org/gnunet-testbed-subsystem)
+ *
+ * @{
*/
#ifndef GNUNET_TESTBED_SERVICE_H
/**
- * 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
* given to GNUNET_TESTBED_is_host_habitable() is NULL
* @param status GNUNET_YES if it is habitable; GNUNET_NO if not
*/
-typedef void (*GNUNET_TESTBED_HostHabitableCallback) (void *cls,
- const struct
- GNUNET_TESTBED_Host
- *host,
- int status);
+typedef void
+(*GNUNET_TESTBED_HostHabitableCallback) (void *cls,
+ const struct GNUNET_TESTBED_Host *host,
+ int status);
/**
* @param cls closure
* @param event information about the event
*/
-typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls,
- const struct GNUNET_TESTBED_EventInformation *event);
+typedef void
+(*GNUNET_TESTBED_ControllerCallback)(void *cls,
+ const struct GNUNET_TESTBED_EventInformation *event);
/**
*
* @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,
+ * 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);
+typedef void
+(*GNUNET_TESTBED_ControllerStatusCallback) (void *cls,
+ const struct GNUNET_CONFIGURATION_Handle *cfg,
+ int status);
/**
- * Starts a controller process at the given host. The given host's configration
+ * Starts a controller process at the given host. The given host's configuration
* is used as a 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
/**
* Connect to a controller process. The configuration to use for the connection
- * is retreived from the given host where a controller is started using
+ * is retrieved from the given host where a controller is started using
* GNUNET_TESTBED_controller_start().
*
* @param host host to run the controller on; This should be the same host if
* @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);
+typedef void
+(* GNUNET_TESTBED_HostRegistrationCompletion) (void *cls,
+ const char *emsg);
/**
* @param emsg error message in case the operation has failed; will be NULL if
* operation has executed successfully.
*/
-typedef void (*GNUNET_TESTBED_OperationCompletionCallback) (void *cls,
- struct
- GNUNET_TESTBED_Operation
- *op,
- const char *emsg);
+typedef void
+(*GNUNET_TESTBED_OperationCompletionCallback) (void *cls,
+ struct GNUNET_TESTBED_Operation *op,
+ const char *emsg);
/**
* 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);
+typedef void
+(*GNUNET_TESTBED_PeerCreateCallback) (void *cls,
+ struct GNUNET_TESTBED_Peer *peer,
+ const char *emsg);
/**
* @param cls the closure from GNUNET_TESTBED_peer_start/stop()
* @param emsg NULL on success; otherwise an error description
*/
-typedef void (*GNUNET_TESTBED_PeerChurnCallback) (void *cls,
- const char *emsg);
+typedef void
+(*GNUNET_TESTBED_PeerChurnCallback) (void *cls,
+ const char *emsg);
/**
* @param emsg error message if the operation has failed; will be NULL if the
* operation is successfull
*/
-typedef void (*GNUNET_TESTBED_PeerInfoCallback) (void *cb_cls,
- struct GNUNET_TESTBED_Operation
- *op,
- const struct
- GNUNET_TESTBED_PeerInformation
- *pinfo,
- const char *emsg);
+typedef void
+(*GNUNET_TESTBED_PeerInfoCallback) (void *cb_cls,
+ struct GNUNET_TESTBED_Operation *op,
+ const struct GNUNET_TESTBED_PeerInformation *pinfo,
+ const char *emsg);
/**
/**
- * 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 *
/**
* Topologies and topology options supported for testbeds. Options should always
- * end with GNUNET_TESTBED_TOPOLOGY_OPTION_END
+ * end with #GNUNET_TESTBED_TOPOLOGY_OPTION_END
*/
enum GNUNET_TESTBED_TopologyOption
{
*/
GNUNET_TESTBED_TOPOLOGY_RING,
+ /**
+ * Star topology. No options.
+ */
+ GNUNET_TESTBED_TOPOLOGY_STAR,
+
/**
* 2-d torus. No options.
*/
* @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);
* from GNUNET_TESTBED_service_connect()
* @return service handle to return in 'op_result', NULL on error
*/
-typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls,
- const struct GNUNET_CONFIGURATION_Handle *cfg);
+typedef void *
+(*GNUNET_TESTBED_ConnectAdapter)(void *cls,
+ const struct GNUNET_CONFIGURATION_Handle *cfg);
/**
* @param cls closure
* @param op_result service handle returned from the connect adapter
*/
-typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls,
- void *op_result);
+typedef void
+(*GNUNET_TESTBED_DisconnectAdapter)(void *cls,
+ void *op_result);
/**
* @param emsg error message in case the operation has failed; will be NULL if
* operation has executed successfully.
*/
-typedef void (*GNUNET_TESTBED_ServiceConnectCompletionCallback) (void *cls,
- struct
- GNUNET_TESTBED_Operation
- *op,
- void
- *ca_result,
- const char
- *emsg );
+typedef void
+(*GNUNET_TESTBED_ServiceConnectCompletionCallback) (void *cls,
+ struct GNUNET_TESTBED_Operation *op,
+ void *ca_result,
+ const char *emsg );
/**
* 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
* @param subsystem name of subsystem that created the statistic
* @param name the name of the datum
* @param value the current value
- * @param is_persistent GNUNET_YES if the value is persistent, GNUNET_NO if not
- * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration
+ * @param is_persistent #GNUNET_YES if the value is persistent, #GNUNET_NO if not
+ * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
*/
-typedef int (*GNUNET_TESTBED_StatisticsIterator) (void *cls,
- const struct GNUNET_TESTBED_Peer *peer,
- const char *subsystem,
- const char *name,
- uint64_t value,
- int is_persistent);
+typedef int
+(*GNUNET_TESTBED_StatisticsIterator) (void *cls,
+ const struct GNUNET_TESTBED_Peer *peer,
+ const char *subsystem,
+ const char *name,
+ uint64_t value,
+ int is_persistent);
/**
GNUNET_TESTBED_OperationCompletionCallback cont,
void *cls);
+
+/**
+ * Return the index of the peer inside of the total peer array,
+ * aka. the peer's "unique ID".
+ *
+ * @param peer Peer handle.
+ *
+ * @return The peer's unique ID.
+ */
+uint32_t
+GNUNET_TESTBED_get_index (const struct GNUNET_TESTBED_Peer *peer);
+
+
/**
* Handle for testbed run helper funtions
*/
struct GNUNET_TESTBED_RunHandle;
+
/**
* Signature of a main function for a testcase.
*
* 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,
- unsigned int links_failed);
+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,
+ unsigned int links_failed);
/**
* respective 'enum GNUNET_TESTBED_EventType'
* (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...")
* @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
+ * 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,
struct GNUNET_TESTBED_Controller *
GNUNET_TESTBED_run_get_controller_handle (struct GNUNET_TESTBED_RunHandle *h);
+
/**
* Opaque handle for barrier
*/
/**
* Barrier initialised successfully
*/
- BARRIER_STATUS_INITIALISED = 1,
+ GNUNET_TESTBED_BARRIERSTATUS_INITIALISED = 1,
/**
* Barrier is crossed
*/
- BARRIER_STATUS_CROSSED,
+ GNUNET_TESTBED_BARRIERSTATUS_CROSSED,
/**
* Error status
*/
- BARRIER_STATUS_ERROR,
-
+ GNUNET_TESTBED_BARRIERSTATUS_ERROR,
+
};
* @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
+ * @param status status of the barrier. The barrier is removed once it has been
+ * crossed or an error occurs while processing it. Therefore it is
+ * invalid to call GNUNET_TESTBED_barrier_cancel() on a crossed or
+ * errored barrier.
+ * @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);
+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.
+ * of peers (quorum) reach the barrier.
*
* @param controller the handle to the controller
* @param name identification name of the barrier
* 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
+ * @param cb_cls closure for @a cb
* @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);
+ GNUNET_TESTBED_barrier_status_cb cb,
+ void *cb_cls);
/**
*
* @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
+ * @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);
+typedef void
+(*GNUNET_TESTBED_barrier_wait_cb) (void *cls,
+ const char *name,
+ int status);
/**
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
#endif
#endif
+
+/** @} */ /* end of group */
projects / oweals / gnunet.git / blobdiff