/*
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
* 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);
/**
/**
* 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.
*/
* 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 );
/**
* @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);
/**
struct GNUNET_TESTBED_Controller *
GNUNET_TESTBED_run_get_controller_handle (struct GNUNET_TESTBED_RunHandle *h);
+
/**
* Opaque handle for 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
+ * @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);
/**
* 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);
/**
#endif
#endif
+
+/** @} */ /* end of group */
projects / oweals / gnunet.git / blobdiff