2 This file is part of GNUnet
3 (C) 2008, 2009, 2012 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_testing_service.h
23 * @brief API for writing tests and creating large-scale
24 * emulation testbeds for GNUnet.
25 * @author Christian Grothoff
28 #ifndef GNUNET_TESTING_SERVICE_H
29 #define GNUNET_TESTING_SERVICE_H
31 #include "gnunet_util_lib.h"
36 #if 0 /* keep Emacsens' auto-indent happy */
43 * Opaque handle to a host running experiments managed by the testing framework.
44 * The master process must be able to SSH to this host without password (via
47 struct GNUNET_TESTING_Host;
50 * Opaque handle to a peer controlled by the testing framework. A peer runs
51 * at a particular host.
53 struct GNUNET_TESTING_Peer;
56 * Opaque handle to an abstract operation to be executed by the testing framework.
58 struct GNUNET_TESTING_Operation;
61 * Handle to interact with a GNUnet testing controller. Each controller has at
62 * least one master handle which is created when the controller is created; this
63 * master handle interacts with the controller via stdin/stdout of the controller
64 * process. Additionally, controllers can interact with each other (in a P2P
65 * fashion); those links are established via TCP/IP on the controller's service
68 struct GNUNET_TESTING_Controller;
71 * Handle to a large-scale testbed that is managed at a high level.
73 struct GNUNET_TESTING_Testbed;
77 * Create a host to run peers and controllers on.
79 * @param hostname name of the host, use "NULL" for localhost
80 * @param username username to use for the login; may be NULL
81 * @param port port number to use for ssh; use 0 to let ssh decide
82 * @return handle to the host, NULL on error
84 struct GNUNET_TESTING_Host *
85 GNUNET_TESTING_host_create (const char *hostname,
91 * Load a set of hosts from a configuration file.
93 * @param filename file with the host specification
94 * @param hosts set to the hosts found in the file
95 * @return number of hosts returned in 'hosts', 0 on error
98 GNUNET_TESTING_hosts_load_from_file (const char *filename,
99 struct GNUNET_TESTING_Host **hosts);
103 * Configure shared services at a peer. Using this function,
104 * you can specify that certain services (such as "resolver")
105 * should not be run for each peer but instead be shared
106 * across N peers on the specified host. This function
107 * must be called before any peers are created at the host.
109 * @param host host to configure
110 * @param service_name name of the service to share
111 * @param num_peers number of peers that should share one instance
112 * of the specified service (1 for no sharing is the default),
113 * use 0 to disable the service
116 GNUNET_TESTING_host_configure (struct GNUNET_TESTING_Host *host,
117 const char *service_name,
119 // FIXME: make this controller-configure?
123 * Destroy a host handle. Must only be called once everything
124 * running on that host has been stopped.
126 * @param host handle to destroy
129 GNUNET_TESTING_host_destroy (struct GNUNET_TESTING_Host *host);
133 * Enumeration with (at most 64) possible event types that
134 * can be monitored using the testing framework.
136 enum GNUNET_TESTING_EventType
139 * A peer has been started.
141 GNUNET_TESTING_ET_PEER_START = 0,
144 * A peer has been stopped.
146 GNUNET_TESTING_ET_PEER_STOP = 1,
149 * A connection between two peers was established.
151 GNUNET_TESTING_ET_CONNECT = 2,
154 * A connection between two peers was torn down.
156 GNUNET_TESTING_ET_DISCONNECT = 3,
159 * A requested testing operation has been completed.
161 GNUNET_TESTING_ET_OPERATION_FINISHED = 4,
164 * The 'GNUNET_TESTING_run' operation has been completed
166 GNUNET_TESTING_ET_TESTBED_ONLINE = 5
172 * Argument to GNUNET_TESTING_ControllerCallback with details about
175 struct GNUNET_TESTING_EventInformation
181 enum GNUNET_TESTING_EventType type;
184 * Details about the event.
190 * Details about peer start event.
195 * Handle for the host where the peer
198 struct GNUNET_TESTING_Host *host;
201 * Handle for the peer that was started.
203 struct GNUNET_TESTING_Peer *peer;
208 * Details about peer stop event.
214 * Handle for the peer that was started.
216 struct GNUNET_TESTING_Peer *peer;
221 * Details about connect event.
226 * Handle for one of the connected peers.
228 struct GNUNET_TESTING_Peer *peer1;
231 * Handle for one of the connected peers.
233 struct GNUNET_TESTING_Peer *peer2;
238 * Details about disconnect event.
243 * Handle for one of the disconnected peers.
245 struct GNUNET_TESTING_Peer *peer1;
248 * Handle for one of the disconnected peers.
250 struct GNUNET_TESTING_Peer *peer2;
255 * Details about an operation finished event.
261 * Handle for the operation that was finished.
263 struct GNUNET_TESTING_Operation *operation;
266 * Closure that was passed in when the event was
272 * Error message for the operation, NULL on success.
277 * Peer information type; captures which of the types
278 * in the 'op_result' is actually in use.
280 enum GNUNET_TESTING_PeerInformationType pit;
283 * Pointer to an operation-specific return value; NULL on error;
284 * can be NULL for certain operations. Valid until
285 * 'GNUNET_TESTING_operation_done' is called.
290 * No result (NULL pointer) or generic result
291 * (whatever the GNUNET_TESTING_ConnectAdapter returned).
296 * Identity of host running the peer.
298 struct GNUNET_TESTING_Host *host;
301 * Identity of the peer.
303 const struct GNUNET_PeerIdentity *pid;
306 * Configuration of the peer.
308 const struct GNUNET_CONFIGURATION_Handle *cfg;
312 } operation_finished;
316 * Details about an testbed run completed event.
322 * Error message for the operation, NULL on success.
327 * Array of peers now running (valid until
328 * 'GNUNET_TESTING_testbed_stop' is called). Note that it is
329 * not allowed to call 'GNUNET_TESTING_peer_destroy' on peers
332 struct GNUNET_TESTING_Peer **peers;
335 * Size of the 'peers' array.
337 unsigned int num_peers;
339 } testbed_run_finished;
347 * Signature of the event handler function called by the
348 * respective event controller.
351 * @param event information about the event
353 typedef void (*GNUNET_TESTING_ControllerCallback)(void *cls,
354 const struct GNUNET_TESTING_EventInformation *event);
358 * Start a controller process using the given configuration at the
361 * @param cfg configuration to use
362 * @param host host to run the controller on, NULL for 'localhost'
363 * @param event_mask bit mask with set of events to call 'cc' for;
364 * or-ed values of "1LL" shifted by the
365 * respective 'enum GNUNET_TESTING_EventType'
366 * (i.e. "(1LL << GNUNET_TESTING_ET_CONNECT) | ...")
367 * @param cc controller callback to invoke on events
368 * @param cc_cls closure for cc
369 * @return handle to the controller
371 struct GNUNET_TESTING_Controller *
372 GNUNET_TESTING_controller_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
373 struct GNUNET_TESTING_Host *host,
375 GNUNET_TESTING_ControllerCallback cc,
381 * Stop the given controller (also will terminate all peers and
382 * controllers dependent on this controller). This function
383 * blocks until the testbed has been fully terminated (!).
385 * @param controller handle to controller to stop
388 GNUNET_TESTING_controller_stop (struct GNUNET_TESTING_Controller *controller);
392 * Create a link from a 'master' controller to a slave controller.
393 * Whenever the master controller is asked to start a peer at the
394 * given 'delegated_host', it will delegate the request to the
395 * specified slave controller. Note that the slave controller runs at
396 * the 'slave_host', which may or may not be the same host as the
397 * 'delegated_host' (for hierarchical delegations). The configuration
398 * of the slave controller is given and to be used to either create
399 * the slave controller or to connect to an existing slave controller
400 * process. 'is_subordinate' specifies if the given slave controller
401 * should be started and managed by the master controller, or if the
402 * slave already has a master and this is just a secondary master that
403 * is also allowed to use the existing slave.
405 * @param master handle to the master controller who creates the association
406 * @param delegated_host requests to which host should be delegated
407 * @param slave_host which host is used to run the slave controller
408 * @param slave_cfg configuration to use for the slave controller
409 * @param is_subordinate GNUNET_YES if the slave should be started (and stopped)
410 * by the master controller; GNUNET_NO if we are just
411 * allowed to use the slave via TCP/IP
414 GNUNET_TESTING_controller_link (struct GNUNET_TESTING_Controller *master,
415 struct GNUNET_TESTING_Host *delegated_host,
416 struct GNUNET_TESTING_Host *slave_host,
417 const struct GNUNET_CONFIGURATION_Handle *slave_cfg,
422 * Create the given peer at the specified host using the given
423 * controller. If the given controller is not running on the target
424 * host, it should find or create a controller at the target host and
425 * delegate creating the peer. Explicit delegation paths can be setup
426 * using 'GNUNET_TESTING_controller_link'. If no explicit delegation
427 * path exists, a direct link with a subordinate controller is setup
428 * for the first delegated peer to a particular host; the subordinate
429 * controller is then destroyed once the last peer that was delegated
430 * to the remote host is stopped.
432 * Creating the peer only creates the handle to manipulate and further
433 * configure the peer; use "GNUNET_TESTING_peer_start" and
434 * "GNUNET_TESTING_peer_stop" to actually start/stop the peer's
437 * Note that the given configuration will be adjusted by the
438 * controller to avoid port/path conflicts with other peers.
439 * The "final" configuration can be obtained using
440 * 'GNUNET_TESTING_peer_get_information'.
442 * @param controller controller process to use
443 * @param host host to run the peer on
444 * @param cfg configuration to use for the peer
445 * @return handle to the peer (actual startup will happen asynchronously)
447 struct GNUNET_TESTING_Peer *
448 GNUNET_TESTING_peer_create (struct GNUNET_TESTING_Controller *controller,
449 struct GNUNET_TESTING_Host *host,
450 const struct GNUNET_CONFIGURATION_Handle *cfg);
454 * Start the given peer.
456 * @param peer peer to start
457 * @return handle to the operation
459 struct GNUNET_TESTING_Operation *
460 GNUNET_TESTING_peer_start (struct GNUNET_TESTING_Peer *peer);
464 * Stop the given peer. The handle remains valid (use
465 * "GNUNET_TESTING_peer_destroy" to fully clean up the
466 * state of the peer).
468 * @param peer peer to stop
469 * @return handle to the operation
471 struct GNUNET_TESTING_Operation *
472 GNUNET_TESTING_peer_stop (struct GNUNET_TESTING_Peer *peer);
476 * Types of information that can be requested about a peer.
478 enum GNUNET_TESTING_PeerInformationType
482 * Special value (not valid for requesting information)
483 * that is used in the event struct if a 'generic' pointer
484 * is returned (for other operations not related to this
487 GNUNET_TESTING_PIT_GENERIC = 0,
490 * What host is the peer running on? Returns a 'const struct
491 * GNUNET_TESTING_Host *'. Valid until
492 * 'GNUNET_TESTING_operation_done' is called.
494 GNUNET_TESTING_PIT_HOST,
497 * What configuration is the peer using? Returns a 'const struct
498 * GNUNET_CONFIGURATION_Handle *'. Valid until
499 * 'GNUNET_TESTNIG_operation_done' is called. However, the
500 * values may be inaccurate if the peer is reconfigured in
503 GNUNET_TESTING_PIT_CONFIGURATION,
506 * What is the identity of the peer? Returns a
507 * 'const struct GNUNET_PeerIdentity *'. Valid until
508 * 'GNUNET_TESTNIG_operation_done' is called.
510 GNUNET_TESTING_PIT_IDENTITY
516 * Request information about a peer.
518 * @param peer peer to request information about
519 * @param pit desired information
520 * @return handle to the operation
522 struct GNUNET_TESTING_Operation *
523 GNUNET_TESTING_peer_get_information (struct GNUNET_TESTING_Peer *peer,
524 enum GNUNET_TESTING_PeerInformationType pit);
528 * Change peer configuration. Must only be called while the
529 * peer is stopped. Ports and paths cannot be changed this
532 * @param peer peer to change configuration for
533 * @param cfg new configuration (differences to existing
534 * configuration only)
535 * @return handle to the operation
537 struct GNUNET_TESTING_Operation *
538 GNUNET_TESTING_peer_update_configuration (struct GNUNET_TESTING_Peer *peer,
539 const struct GNUNET_CONFIGURATION_Handle *handle);
543 * Destroy the given peer; the peer should have been
544 * stopped first (if it was started).
546 * @param peer peer to stop
547 * @return handle to the operation
549 struct GNUNET_TESTING_Operation *
550 GNUNET_TESTING_peer_destroy (struct GNUNET_TESTING_Peer *peer);
554 * Options for peer connections.
556 enum GNUNET_TESTING_ConnectOption
559 * No option (not valid as an argument).
561 GNUNET_TESTING_CO_NONE = 0,
564 * Allow or disallow a connection between the specified peers.
565 * Followed by GNUNET_NO (int) if a connection is disallowed
566 * or GNUNET_YES if a connection is allowed. Note that the
567 * default (all connections allowed or disallowed) is
568 * specified in the configuration of the controller.
570 GNUNET_TESTING_CO_ALLOW = 1,
573 * FIXME: add (and implement) options to limit connection to
574 * particular transports, force simulation of particular latencies
575 * or message loss rates, or set bandwidth limitations.
582 * Manipulate the P2P underlay topology by configuring a link
585 * @param op_cls closure argument to give with the operation event
586 * @param p1 first peer
587 * @param p2 second peer
588 * @param co option to change
589 * @param ... option-specific values
590 * @return handle to the operation, NULL if configuring the link at this
591 * time is not allowed
593 struct GNUNET_TESTING_Operation *
594 GNUNET_TESTING_underlay_configure_link (void *op_cls,
595 struct GNUNET_TESTING_Peer *p1,
596 struct GNUNET_TESTING_Peer *p2,
597 enum GNUNET_TESTING_ConnectOption co, ...);
602 * Topologies supported for testbeds.
604 enum GNUNET_TESTING_Topology
607 * A clique (everyone connected to everyone else). No options.
609 GNUNET_TESTING_TOPOLOGY_CLIQUE,
612 * Small-world network (2d torus plus random links). Followed
613 * by the number of random links to add (unsigned int).
615 GNUNET_TESTING_TOPOLOGY_SMALL_WORLD,
618 * Small-world network (ring plus random links). Followed
619 * by the number of random links to add (unsigned int).
621 GNUNET_TESTING_TOPOLOGY_SMALL_WORLD_RING,
624 * Ring topology. No options.
626 GNUNET_TESTING_TOPOLOGY_RING,
629 * 2-d torus. No options.
631 GNUNET_TESTING_TOPOLOGY_2D_TORUS,
634 * Random graph. Followed by the link density, that is the
635 * percentage of links present in relation to a clique
638 GNUNET_TESTING_TOPOLOGY_ERDOS_RENYI,
641 * Certain percentage of peers are unable to communicate directly
642 * replicating NAT conditions. Followed by the fraction of
643 * NAT'ed peers (float).
645 GNUNET_TESTING_TOPOLOGY_INTERNAT,
648 * Scale free topology. FIXME: options?
650 GNUNET_TESTING_TOPOLOGY_SCALE_FREE,
653 * Straight line topology. No options.
655 GNUNET_TESTING_TOPOLOGY_LINE,
658 * All peers are disconnected. No options.
660 GNUNET_TESTING_TOPOLOGY_NONE,
663 * Read a topology from a given file. Followed by the name of the file (const char *).
665 GNUNET_TESTING_TOPOLOGY_FROM_FILE
670 * Configure overall network topology to have a particular shape.
672 * @param op_cls closure argument to give with the operation event
673 * @param num_peers number of peers in 'peers'
674 * @param peers array of 'num_peers' with the peers to configure
675 * @param topo desired underlay topology to use
676 * @param ap topology-specific options
677 * @return handle to the operation, NULL if configuring the topology
678 * is not allowed at this time
680 struct GNUNET_TESTING_Operation *
681 GNUNET_TESTING_underlay_configure_topology_va (void *op_cls,
682 unsigned int num_peers,
683 struct GNUNET_TESTING_Peer **peers,
684 enum GNUNET_TESTING_TopologyOption topo,
689 * Configure overall network topology to have a particular shape.
691 * @param op_cls closure argument to give with the operation event
692 * @param num_peers number of peers in 'peers'
693 * @param peers array of 'num_peers' with the peers to configure
694 * @param topo desired underlay topology to use
695 * @param ... topology-specific options
696 * @return handle to the operation, NULL if configuring the topology
697 * is not allowed at this time
699 struct GNUNET_TESTING_Operation *
700 GNUNET_TESTING_underlay_configure_topology (void *op_cls,
701 unsigned int num_peers,
702 struct GNUNET_TESTING_Peer **peers,
703 enum GNUNET_TESTING_TopologyOption topo,
708 * Both peers must have been started before calling this function.
709 * This function then obtains a HELLO from 'p1', gives it to 'p2'
710 * and asks 'p2' to connect to 'p1'.
712 * @param op_cls closure argument to give with the operation event
713 * @param p1 first peer
714 * @param p2 second peer
715 * @return handle to the operation, NULL if connecting these two
716 * peers is fundamentally not possible at this time (peers
717 * not running or underlay disallows)
719 struct GNUNET_TESTING_Operation *
720 GNUNET_TESTING_overlay_connect (void *op_cls,
721 struct GNUNET_TESTING_Peer *p1,
722 struct GNUNET_TESTING_Peer *p2);
726 * All peers must have been started before calling this function.
727 * This function then connects the given peers in the P2P overlay
728 * using the given topology.
730 * @param op_cls closure argument to give with the operation event
731 * @param num_peers number of peers in 'peers'
732 * @param peers array of 'num_peers' with the peers to configure
733 * @param topo desired underlay topology to use
734 * @param va topology-specific options
735 * @return handle to the operation, NULL if connecting these
736 * peers is fundamentally not possible at this time (peers
737 * not running or underlay disallows)
739 struct GNUNET_TESTING_Operation *
740 GNUNET_TESTING_overlay_configure_topology_va (void *op_cls,
741 unsigned int num_peers,
742 struct GNUNET_TESTING_Peer *peers,
743 enum GNUNET_TESTING_TopologyOption topo,
748 * All peers must have been started before calling this function.
749 * This function then connects the given peers in the P2P overlay
750 * using the given topology.
752 * @param op_cls closure argument to give with the operation event
753 * @param num_peers number of peers in 'peers'
754 * @param peers array of 'num_peers' with the peers to configure
755 * @param topo desired underlay topology to use
756 * @param ... topology-specific options
757 * @return handle to the operation, NULL if connecting these
758 * peers is fundamentally not possible at this time (peers
759 * not running or underlay disallows)
761 struct GNUNET_TESTING_Operation *
762 GNUNET_TESTING_overlay_configure_topology (void *op_cls,
763 unsigned int num_peers,
764 struct GNUNET_TESTING_Peer *peers,
765 enum GNUNET_TESTING_TopologyOption topo,
771 * Ask the testbed controller to write the current overlay topology to
772 * a file. Naturally, the file will only contain a snapshot as the
773 * topology may evolve all the time.
775 * @param controller overlay controller to inspect
776 * @param filename name of the file the topology should
780 GNUNET_TESTING_overlay_write_topology_to_file (struct GNUNET_TESTING_Controller *controller,
781 const char *filename);
785 * Adapter function called to establish a connection to
789 * @param cfg configuration of the peer to connect to
790 * @return service handle to return in 'op_result', NULL on error
792 typedef void * (*GNUNET_TESTING_ConnectAdapter)(void *cls,
793 const struct GNUNET_CONFIGURATION_Handle *cfg);
797 * Adapter function called to destroy a connection to
801 * @param op_result service handle returned from the connect adapter
803 typedef void (*GNUNET_TESTING_DisconnectAdapter)(void *cls,
808 * Connect to a service offered by the given peer. Will ensure that
809 * the request is queued to not overwhelm our ability to create and
810 * maintain connections with other systems. The actual service
811 * handle is then returned via the 'op_result' member in the event
812 * callback. The 'ca' callback is used to create the connection
813 * when the time is right; the 'da' callback will be used to
814 * destroy the connection (upon 'GNUNET_TESTING_operation_done').
815 * 'GNUNET_TESTING_operation_cancel' can be used to abort this
816 * operation until the event callback has been called.
818 * @param op_cls closure to pass in operation event
819 * @param peer peer that runs the service
820 * @param service_name name of the service to connect to
821 * @param ca helper function to establish the connection
822 * @param da helper function to close the connection
823 * @param cada_cls closure for ca and da
824 * @return handle for the operation
826 struct GNUNET_TESTING_Operation *
827 GNUNET_TESTING_service_connect (void *op_cls,
828 struct GNUNET_TESTING_Peer *peer,
829 const char *service_name,
830 GNUNET_TESTING_ConnectAdapter ca,
831 GNUNET_TESTING_DisconnectAdapter da,
836 * Cancel a pending operation. Releases all resources
837 * of the operation and will ensure that no event
838 * is generated for the operation. Does NOT guarantee
839 * that the operation will be fully undone (or that
840 * nothing ever happened).
842 * @param operation operation to cancel
845 GNUNET_TESTING_operation_cancel (struct GNUNET_TESTING_Operation *operation);
849 * Signal that the information from an operation has been fully
850 * processed. This function MUST be called for each event
851 * of type 'operation_finished' to fully remove the operation
852 * from the operation queue. After calling this function, the
853 * 'op_result' becomes invalid (!).
855 * @param operation operation to signal completion for
858 GNUNET_TESTING_operation_done (struct GNUNET_TESTING_Operation *operation);
862 * Configure and run a testbed using the given
863 * master controller on 'num_hosts' starting
864 * 'num_peers' using the given peer configuration.
866 * @param controller master controller for the testbed
867 * (must not be destroyed until after the
868 * testbed is destroyed).
869 * @param num_hosts number of hosts in 'hosts', 0 to only
871 * @param hosts list of hosts to use for the testbed
872 * @param num_peers number of peers to start
873 * @param peer_cfg peer configuration template to use
874 * @param underlay_topology underlay topology to create
875 * @param va topology-specific options
876 * @return handle to the testbed
878 struct GNUNET_TESTING_Testbed *
879 GNUNET_TESTING_testbed_create_va (struct GNUNET_TESTING_Controller *controller,
880 unsigned int num_hosts,
881 struct GNUNET_TESTING_Host **hosts,
882 unsigned int num_peers,
883 const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
884 enum GNUNET_TESTING_Topology topo,
889 * Configure and run a testbed using the given
890 * master controller on 'num_hosts' starting
891 * 'num_peers' using the given peer configuration.
893 * @param controller master controller for the testbed
894 * (must not be destroyed until after the
895 * testbed is destroyed).
896 * @param num_hosts number of hosts in 'hosts', 0 to only
898 * @param hosts list of hosts to use for the testbed
899 * @param num_peers number of peers to start
900 * @param peer_cfg peer configuration template to use
901 * @param underlay_topology underlay topology to create
902 * @param ... topology-specific options
904 struct GNUNET_TESTING_Testbed *
905 GNUNET_TESTING_testbed_create (struct GNUNET_TESTING_Controller *controller,
906 unsigned int num_hosts,
907 struct GNUNET_TESTING_Host **hosts,
908 unsigned int num_peers,
909 const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
910 enum GNUNET_TESTING_Topology topo,
915 * Destroy a testbed. Stops all running peers and then
916 * destroys all peers. Does NOT destroy the master controller.
918 * @param testbed testbed to destroy
921 GNUNET_TESTING_testbed_destroy (struct GNUNET_TESTING_Testbed *testbed);
925 * Convenience method for running a testbed with
926 * a single call. Underlay and overlay topology
927 * are configured using the "UNDERLAY" and "OVERLAY"
928 * options in the "[testbed]" section of the configuration\
929 * (with possible options given in "UNDERLAY_XXX" and/or
932 * The testbed is to be terminated using a call to
933 * "GNUNET_SCHEDULER_shutdown".
935 * @param host_filename name of the file with the 'hosts', NULL
936 * to run everything on 'localhost'
937 * @param cfg configuration to use (for testbed, controller and peers)
938 * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg?
939 * @param event_mask bit mask with set of events to call 'cc' for;
940 * or-ed values of "1LL" shifted by the
941 * respective 'enum GNUNET_TESTING_EventType'
942 * (i.e. "(1LL << GNUNET_TESTING_ET_CONNECT) || ...")
943 * @param cc controller callback to invoke on events
944 * @param cc_cls closure for cc
945 * @param master task to run once the testbed is ready
946 * @param master_cls closure for 'task'.
949 GNUNET_TESTING_testbed_run (const char *host_filename,
950 const struct GNUNET_CONFIGURATION_Handle *cfg,
951 unsigned int num_peers,
953 GNUNET_TESTING_ControllerCallback cc,
955 GNUNET_SCHEDULER_Task master,
960 * Signature of a main function for a testcase.
963 * @param num_peers number of peers in 'peers'
964 * @param peers handle to peers run in the testbed
966 typedef void (*GNUNET_TESTING_TestMaster)(void *cls,
967 unsigned int num_peers,
968 struct GNUNET_TESTING_Peer **peers);
972 * Convenience method for running a "simple" test on the local system
973 * with a single call from 'main'. Underlay and overlay topology are
974 * configured using the "UNDERLAY" and "OVERLAY" options in the
975 * "[testbed]" section of the configuration (with possible options
976 * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX").
978 * The test is to be terminated using a call to
979 * "GNUNET_SCHEDULER_shutdown". If starting the test fails,
980 * the program is stopped without 'master' ever being run.
982 * NOTE: this function should be called from 'main', NOT from
983 * within a GNUNET_SCHEDULER-loop. This function will initialze
984 * the scheduler loop, the testbed and then pass control to
987 * @param testname name of the testcase (to configure logging, etc.)
988 * @param cfg_filename configuration filename to use
989 * (for testbed, controller and peers)
990 * @param num_peers number of peers to start
991 * @param test_master task to run once the test is ready
992 * @param test_master_cls closure for 'task'.
995 GNUNET_TESTING_test_run (const char *testname,
996 const char *cfg_filename,
997 unsigned int num_peers,
998 GNUNET_TESTING_TestMaster master,
1002 #if 0 /* keep Emacsens' auto-indent happy */