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_testbed_service.h
23 * @brief API for writing tests and creating large-scale
24 * emulation testbeds for GNUnet.
25 * @author Christian Grothoff
28 #ifndef GNUNET_TESTBED_SERVICE_H
29 #define GNUNET_TESTBED_SERVICE_H
31 #include "gnunet_util_lib.h"
32 #include "gnunet_testing_lib-new.h"
37 #if 0 /* keep Emacsens' auto-indent happy */
44 * Opaque handle to a host running experiments managed by the testbed framework.
45 * The master process must be able to SSH to this host without password (via
48 struct GNUNET_TESTBED_Host;
51 * Opaque handle to a peer controlled by the testbed framework. A peer runs
52 * at a particular host.
54 struct GNUNET_TESTBED_Peer;
57 * Opaque handle to an abstract operation to be executed by the testbed framework.
59 struct GNUNET_TESTBED_Operation;
62 * Handle to interact with a GNUnet testbed controller. Each
63 * controller has at least one master handle which is created when the
64 * controller is created; this master handle interacts with the
65 * controller process, destroying it destroys the controller (by
66 * closing stdin of the controller process). Additionally,
67 * controllers can interact with each other (in a P2P fashion); those
68 * links are established via TCP/IP on the controller's service port.
70 struct GNUNET_TESTBED_Controller;
73 * Handle to a large-scale testbed that is managed at a high level.
75 struct GNUNET_TESTBED_Testbed;
79 * Create a host to run peers and controllers on.
81 * @param hostname name of the host, use "NULL" for localhost
82 * @param username username to use for the login; may be NULL
83 * @param port port number to use for ssh; use 0 to let ssh decide
84 * @return handle to the host, NULL on error
86 struct GNUNET_TESTBED_Host *
87 GNUNET_TESTBED_host_create (const char *hostname,
94 * Create a host to run peers and controllers on. This function is used
95 * if a peer learns about a host via IPC between controllers (and thus
96 * some higher-level controller has already determined the unique IDs).
98 * @param id global host ID assigned to the host; 0 is
99 * reserved to always mean 'localhost'
100 * @param hostname name of the host, use "NULL" for localhost
101 * @param username username to use for the login; may be NULL
102 * @param port port number to use for ssh; use 0 to let ssh decide
103 * @return handle to the host, NULL on error
105 struct GNUNET_TESTBED_Host *
106 GNUNET_TESTBED_host_create_with_id (uint32_t id,
107 const char *hostname,
108 const char *username,
113 * Load a set of hosts from a configuration file.
115 * @param filename file with the host specification
116 * @param hosts set to the hosts found in the file
117 * @return number of hosts returned in 'hosts', 0 on error
120 GNUNET_TESTBED_hosts_load_from_file (const char *filename,
121 struct GNUNET_TESTBED_Host **hosts);
125 * Destroy a host handle. Must only be called once everything
126 * running on that host has been stopped.
128 * @param host handle to destroy
131 GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host);
135 * Enumeration with (at most 64) possible event types that
136 * can be monitored using the testbed framework.
138 enum GNUNET_TESTBED_EventType
141 * A peer has been started.
143 GNUNET_TESTBED_ET_PEER_START = 0,
146 * A peer has been stopped.
148 GNUNET_TESTBED_ET_PEER_STOP = 1,
151 * A connection between two peers was established.
153 GNUNET_TESTBED_ET_CONNECT = 2,
156 * A connection between two peers was torn down.
158 GNUNET_TESTBED_ET_DISCONNECT = 3,
161 * A requested testbed operation has been completed.
163 GNUNET_TESTBED_ET_OPERATION_FINISHED = 4,
166 * The 'GNUNET_TESTBED_run' operation has been completed
168 GNUNET_TESTBED_ET_TESTBED_ONLINE = 5
174 * Types of information that can be requested about a peer.
176 enum GNUNET_TESTBED_PeerInformationType
180 * Special value (not valid for requesting information)
181 * that is used in the event struct if a 'generic' pointer
182 * is returned (for other operations not related to this
185 GNUNET_TESTBED_PIT_GENERIC = 0,
188 * What host is the peer running on? Returns a 'const struct
189 * GNUNET_TESTBED_Host *'. Valid until
190 * 'GNUNET_TESTBED_operation_done' is called.
192 GNUNET_TESTBED_PIT_HOST,
195 * What configuration is the peer using? Returns a 'const struct
196 * GNUNET_CONFIGURATION_Handle *'. Valid until
197 * 'GNUNET_TESTNIG_operation_done' is called. However, the
198 * values may be inaccurate if the peer is reconfigured in
201 GNUNET_TESTBED_PIT_CONFIGURATION,
204 * What is the identity of the peer? Returns a
205 * 'const struct GNUNET_PeerIdentity *'. Valid until
206 * 'GNUNET_TESTNIG_operation_done' is called.
208 GNUNET_TESTBED_PIT_IDENTITY
214 * Argument to GNUNET_TESTBED_ControllerCallback with details about
217 struct GNUNET_TESTBED_EventInformation
223 enum GNUNET_TESTBED_EventType type;
226 * Details about the event.
232 * Details about peer start event.
237 * Handle for the host where the peer
240 struct GNUNET_TESTBED_Host *host;
243 * Handle for the peer that was started.
245 struct GNUNET_TESTBED_Peer *peer;
250 * Details about peer stop event.
256 * Handle for the peer that was started.
258 struct GNUNET_TESTBED_Peer *peer;
263 * Details about connect event.
268 * Handle for one of the connected peers.
270 struct GNUNET_TESTBED_Peer *peer1;
273 * Handle for one of the connected peers.
275 struct GNUNET_TESTBED_Peer *peer2;
280 * Details about disconnect event.
285 * Handle for one of the disconnected peers.
287 struct GNUNET_TESTBED_Peer *peer1;
290 * Handle for one of the disconnected peers.
292 struct GNUNET_TESTBED_Peer *peer2;
297 * Details about an operation finished event.
303 * Handle for the operation that was finished.
305 struct GNUNET_TESTBED_Operation *operation;
308 * Closure that was passed in when the event was
314 * Error message for the operation, NULL on success.
319 * Peer information type; captures which of the types
320 * in the 'op_result' is actually in use.
322 enum GNUNET_TESTBED_PeerInformationType pit;
325 * Pointer to an operation-specific return value; NULL on error;
326 * can be NULL for certain operations. Valid until
327 * 'GNUNET_TESTBED_operation_done' is called.
332 * No result (NULL pointer) or generic result
333 * (whatever the GNUNET_TESTBED_ConnectAdapter returned).
338 * Identity of host running the peer.
340 struct GNUNET_TESTBED_Host *host;
343 * Identity of the peer.
345 const struct GNUNET_PeerIdentity *pid;
348 * Configuration of the peer.
350 const struct GNUNET_CONFIGURATION_Handle *cfg;
354 } operation_finished;
358 * Details about an testbed run completed event.
364 * Error message for the operation, NULL on success.
369 * Array of peers now running (valid until
370 * 'GNUNET_TESTBED_testbed_stop' is called). Note that it is
371 * not allowed to call 'GNUNET_TESTBED_peer_destroy' on peers
374 struct GNUNET_TESTBED_Peer **peers;
377 * Size of the 'peers' array.
379 unsigned int num_peers;
381 } testbed_run_finished;
389 * Signature of the event handler function called by the
390 * respective event controller.
393 * @param event information about the event
395 typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls,
396 const struct GNUNET_TESTBED_EventInformation *event);
400 * Opaque Handle for Controller process
402 struct GNUNET_TESTBED_ControllerProc;
406 * Function called on errors with the controller.
409 * @param emsg error message if available; can be NULL, which does NOT mean
410 * that there was no error
412 typedef void (*GNUNET_TESTBED_ControllerErrorCallback)(void *cls,
417 * Starts a controller process at the host. FIXME: add controller start callback
418 * with the configuration with which the controller is started
420 * @param controller_ip the ip address of the controller. Will be set as TRUSTED
421 * host when starting testbed controller at host
422 * @param host the host where the controller has to be started; NULL for localhost
423 * @param cfg template configuration to use for the remote controller; the
424 * remote controller will be started with a slightly modified
425 * configuration (port numbers, unix domain sockets and service home
426 * values are changed as per TESTING library on the remote host)
427 * @param cec function called if the contoller dies unexpectedly; will not be
428 * invoked after GNUNET_TESTBED_controller_stop, if 'cec' was called,
429 * GNUNET_TESTBED_controller_stop must no longer be called; will
430 * never be called in the same task as 'GNUNET_TESTBED_controller_start'
431 * (synchronous errors will be signalled by returning NULL)
432 * @param cec_cls closure for 'cec'
433 * @return the controller process handle, NULL on errors
435 struct GNUNET_TESTBED_ControllerProc *
436 GNUNET_TESTBED_controller_start (const char *controller_ip,
437 struct GNUNET_TESTBED_Host *host,
438 const struct GNUNET_CONFIGURATION_Handle *cfg,
439 GNUNET_TESTBED_ControllerErrorCallback cec,
444 * Stop the controller process (also will terminate all peers and controllers
445 * dependent on this controller). This function blocks until the testbed has
446 * been fully terminated (!).
448 * @param cproc the controller process handle
451 GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_ControllerProc *cproc);
455 * Connect to a controller process using the given configuration at the
458 * @param cfg configuration to use
459 * @param host host to run the controller on; This should be the same host if
460 * the controller was previously started with
461 * GNUNET_TESTBED_controller_start; NULL for localhost
462 * @param host host where this controller is being run;
463 * @param event_mask bit mask with set of events to call 'cc' for;
464 * or-ed values of "1LL" shifted by the
465 * respective 'enum GNUNET_TESTBED_EventType'
466 * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...")
467 * @param cc controller callback to invoke on events
468 * @param cc_cls closure for cc
469 * @return handle to the controller
471 struct GNUNET_TESTBED_Controller *
472 GNUNET_TESTBED_controller_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
473 struct GNUNET_TESTBED_Host *host,
475 GNUNET_TESTBED_ControllerCallback cc,
480 * Configure shared services at a controller. Using this function,
481 * you can specify that certain services (such as "resolver")
482 * should not be run for each peer but instead be shared
483 * across N peers on the specified host. This function
484 * must be called before any peers are created at the host.
486 * @param controller controller to configure
487 * @param service_name name of the service to share
488 * @param num_peers number of peers that should share one instance
489 * of the specified service (1 for no sharing is the default),
490 * use 0 to disable the service
493 GNUNET_TESTBED_controller_configure_sharing (struct GNUNET_TESTBED_Controller *controller,
494 const char *service_name,
499 * Stop the given controller (also will terminate all peers and
500 * controllers dependent on this controller). This function
501 * blocks until the testbed has been fully terminated (!).
503 * @param controller handle to controller to stop
506 GNUNET_TESTBED_controller_disconnect (struct GNUNET_TESTBED_Controller *controller);
510 * Opaque handle for host registration
512 struct GNUNET_TESTBED_HostRegistrationHandle;
516 * Callback which will be called to after a host registration succeeded or failed
518 * @param cls the closure
519 * @param emsg the error message; NULL if host registration is successful
521 typedef void (* GNUNET_TESTBED_HostRegistrationCompletion) (void *cls,
526 * Register a host with the controller
528 * @param controller the controller handle
529 * @param host the host to register
530 * @param cc the completion callback to call to inform the status of
531 * registration. After calling this callback the registration handle
532 * will be invalid. Cannot be NULL
533 * @param cc_cls the closure for the cc
534 * @return handle to the host registration which can be used to cancel the
535 * registration; NULL if another registration handle is present and
538 struct GNUNET_TESTBED_HostRegistrationHandle *
539 GNUNET_TESTBED_register_host (struct GNUNET_TESTBED_Controller *controller,
540 struct GNUNET_TESTBED_Host *host,
541 GNUNET_TESTBED_HostRegistrationCompletion cc,
546 * Cancel the pending registration. Note that the registration message will
547 * already be queued to be sent to the service, cancellation has only the
548 * effect that the registration completion callback for the registration is
549 * never called and from our perspective the host is not registered until the
550 * completion callback is called.
552 * @param handle the registration handle to cancel
555 GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle
560 * Create a link from slave controller to delegated controller. Whenever the
561 * master controller is asked to start a peer at the delegated controller the
562 * request will be routed towards slave controller (if a route exists). The
563 * slave controller will then route it to the delegated controller. The
564 * configuration of the slave controller is given and to be used to either
565 * create the slave controller or to connect to an existing slave controller
566 * process. 'is_subordinate' specifies if the given slave controller should be
567 * started and managed by the master controller, or if the slave already has a
568 * master and this is just a secondary master that is also allowed to use the
571 * @param master handle to the master controller who creates the association
572 * @param delegated_host requests to which host should be delegated; cannot be NULL
573 * @param slave_host which host is used to run the slave controller; use NULL to
574 * make the master controller connect to the delegated host
575 * @param slave_cfg configuration to use for the slave controller
576 * @param is_subordinate GNUNET_YES if the controller at delegated_host should
577 * be started by the master controller; GNUNET_NO if we are just
578 * allowed to use the slave via TCP/IP
581 GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master,
582 struct GNUNET_TESTBED_Host *delegated_host,
583 struct GNUNET_TESTBED_Host *slave_host,
584 const struct GNUNET_CONFIGURATION_Handle *slave_cfg,
589 * Same as the GNUNET_TESTBED_controller_link, however expects configuration in
590 * serialized and compressed
592 * @param master handle to the master controller who creates the association
593 * @param delegated_host requests to which host should be delegated; cannot be NULL
594 * @param slave_host which host is used to run the slave controller; use NULL to
595 * make the master controller connect to the delegated host
596 * @param sxcfg serialized and compressed configuration
597 * @param sxcfg_size the size scfg
598 * @param scfg_size the size of uncompressed serialized configuration
599 * @param is_subordinate GNUNET_YES if the controller at delegated_host should
600 * be started by the master controller; GNUNET_NO if we are just
601 * allowed to use the slave via TCP/IP
604 GNUNET_TESTBED_controller_link_2 (struct GNUNET_TESTBED_Controller *master,
605 struct GNUNET_TESTBED_Host *delegated_host,
606 struct GNUNET_TESTBED_Host *slave_host,
614 * Create the given peer at the specified host using the given
615 * controller. If the given controller is not running on the target
616 * host, it should find or create a controller at the target host and
617 * delegate creating the peer. Explicit delegation paths can be setup
618 * using 'GNUNET_TESTBED_controller_link'. If no explicit delegation
619 * path exists, a direct link with a subordinate controller is setup
620 * for the first delegated peer to a particular host; the subordinate
621 * controller is then destroyed once the last peer that was delegated
622 * to the remote host is stopped.
624 * Creating the peer only creates the handle to manipulate and further
625 * configure the peer; use "GNUNET_TESTBED_peer_start" and
626 * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's
629 * Note that the given configuration will be adjusted by the
630 * controller to avoid port/path conflicts with other peers.
631 * The "final" configuration can be obtained using
632 * 'GNUNET_TESTBED_peer_get_information'.
634 * @param controller controller process to use
635 * @param host host to run the peer on
636 * @param cfg configuration to use for the peer
637 * @return handle to the peer (actual startup will happen asynchronously)
639 struct GNUNET_TESTBED_Peer *
640 GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller,
641 struct GNUNET_TESTBED_Host *host,
642 const struct GNUNET_CONFIGURATION_Handle *cfg);
646 * Start the given peer.
648 * @param peer peer to start
649 * @return handle to the operation
651 struct GNUNET_TESTBED_Operation *
652 GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer);
656 * Stop the given peer. The handle remains valid (use
657 * "GNUNET_TESTBED_peer_destroy" to fully clean up the
658 * state of the peer).
660 * @param peer peer to stop
661 * @return handle to the operation
663 struct GNUNET_TESTBED_Operation *
664 GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer);
668 * Request information about a peer.
670 * @param peer peer to request information about
671 * @param pit desired information
672 * @return handle to the operation
674 struct GNUNET_TESTBED_Operation *
675 GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer,
676 enum GNUNET_TESTBED_PeerInformationType pit);
680 * Change peer configuration. Must only be called while the
681 * peer is stopped. Ports and paths cannot be changed this
684 * @param peer peer to change configuration for
685 * @param cfg new configuration (differences to existing
686 * configuration only)
687 * @return handle to the operation
689 struct GNUNET_TESTBED_Operation *
690 GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer,
691 const struct GNUNET_CONFIGURATION_Handle *cfg);
695 * Destroy the given peer; the peer should have been
696 * stopped first (if it was started).
698 * @param peer peer to stop
699 * @return handle to the operation
701 struct GNUNET_TESTBED_Operation *
702 GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer);
706 * Options for peer connections.
708 enum GNUNET_TESTBED_ConnectOption
711 * No option (not valid as an argument).
713 GNUNET_TESTBED_CO_NONE = 0,
716 * Allow or disallow a connection between the specified peers.
717 * Followed by GNUNET_NO (int) if a connection is disallowed
718 * or GNUNET_YES if a connection is allowed. Note that the
719 * default (all connections allowed or disallowed) is
720 * specified in the configuration of the controller.
722 GNUNET_TESTBED_CO_ALLOW = 1,
725 * FIXME: add (and implement) options to limit connection to
726 * particular transports, force simulation of particular latencies
727 * or message loss rates, or set bandwidth limitations.
734 * Manipulate the P2P underlay topology by configuring a link
737 * @param op_cls closure argument to give with the operation event
738 * @param p1 first peer
739 * @param p2 second peer
740 * @param co option to change
741 * @param ap option-specific values
742 * @return handle to the operation, NULL if configuring the link at this
743 * time is not allowed
745 struct GNUNET_TESTBED_Operation *
746 GNUNET_TESTBED_underlay_configure_link_va (void *op_cls,
747 struct GNUNET_TESTBED_Peer *p1,
748 struct GNUNET_TESTBED_Peer *p2,
749 enum GNUNET_TESTBED_ConnectOption co,
754 * Manipulate the P2P underlay topology by configuring a link
757 * @param op_cls closure argument to give with the operation event
758 * @param p1 first peer
759 * @param p2 second peer
760 * @param co option to change
761 * @param ... option-specific values
762 * @return handle to the operation, NULL if configuring the link at this
763 * time is not allowed
765 struct GNUNET_TESTBED_Operation *
766 GNUNET_TESTBED_underlay_configure_link (void *op_cls,
767 struct GNUNET_TESTBED_Peer *p1,
768 struct GNUNET_TESTBED_Peer *p2,
769 enum GNUNET_TESTBED_ConnectOption co, ...);
774 * Topologies supported for testbeds.
776 enum GNUNET_TESTBED_TopologyOption
779 * A clique (everyone connected to everyone else). No options.
781 GNUNET_TESTBED_TOPOLOGY_CLIQUE,
784 * Small-world network (2d torus plus random links). Followed
785 * by the number of random links to add (unsigned int).
787 GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD,
790 * Small-world network (ring plus random links). Followed
791 * by the number of random links to add (unsigned int).
793 GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING,
796 * Ring topology. No options.
798 GNUNET_TESTBED_TOPOLOGY_RING,
801 * 2-d torus. No options.
803 GNUNET_TESTBED_TOPOLOGY_2D_TORUS,
806 * Random graph. Followed by the link density, that is the
807 * percentage of links present in relation to a clique
810 GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI,
813 * Certain percentage of peers are unable to communicate directly
814 * replicating NAT conditions. Followed by the fraction of
815 * NAT'ed peers (float).
817 GNUNET_TESTBED_TOPOLOGY_INTERNAT,
820 * Scale free topology. FIXME: options?
822 GNUNET_TESTBED_TOPOLOGY_SCALE_FREE,
825 * Straight line topology. No options.
827 GNUNET_TESTBED_TOPOLOGY_LINE,
830 * All peers are disconnected. No options.
832 GNUNET_TESTBED_TOPOLOGY_NONE,
835 * Read a topology from a given file. Followed by the name of the file (const char *).
837 GNUNET_TESTBED_TOPOLOGY_FROM_FILE
842 * Configure overall network topology to have a particular shape.
844 * @param op_cls closure argument to give with the operation event
845 * @param num_peers number of peers in 'peers'
846 * @param peers array of 'num_peers' with the peers to configure
847 * @param topo desired underlay topology to use
848 * @param ap topology-specific options
849 * @return handle to the operation, NULL if configuring the topology
850 * is not allowed at this time
852 struct GNUNET_TESTBED_Operation *
853 GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls,
854 unsigned int num_peers,
855 struct GNUNET_TESTBED_Peer **peers,
856 enum GNUNET_TESTBED_TopologyOption topo,
861 * Configure overall network topology to have a particular shape.
863 * @param op_cls closure argument to give with the operation event
864 * @param num_peers number of peers in 'peers'
865 * @param peers array of 'num_peers' with the peers to configure
866 * @param topo desired underlay topology to use
867 * @param ... topology-specific options
868 * @return handle to the operation, NULL if configuring the topology
869 * is not allowed at this time
871 struct GNUNET_TESTBED_Operation *
872 GNUNET_TESTBED_underlay_configure_topology (void *op_cls,
873 unsigned int num_peers,
874 struct GNUNET_TESTBED_Peer **peers,
875 enum GNUNET_TESTBED_TopologyOption topo,
880 * Both peers must have been started before calling this function.
881 * This function then obtains a HELLO from 'p1', gives it to 'p2'
882 * and asks 'p2' to connect to 'p1'.
884 * @param op_cls closure argument to give with the operation event
885 * @param p1 first peer
886 * @param p2 second peer
887 * @return handle to the operation, NULL if connecting these two
888 * peers is fundamentally not possible at this time (peers
889 * not running or underlay disallows)
891 struct GNUNET_TESTBED_Operation *
892 GNUNET_TESTBED_overlay_connect (void *op_cls,
893 struct GNUNET_TESTBED_Peer *p1,
894 struct GNUNET_TESTBED_Peer *p2);
898 * All peers must have been started before calling this function.
899 * This function then connects the given peers in the P2P overlay
900 * using the given topology.
902 * @param op_cls closure argument to give with the operation event
903 * @param num_peers number of peers in 'peers'
904 * @param peers array of 'num_peers' with the peers to configure
905 * @param topo desired underlay topology to use
906 * @param va topology-specific options
907 * @return handle to the operation, NULL if connecting these
908 * peers is fundamentally not possible at this time (peers
909 * not running or underlay disallows)
911 struct GNUNET_TESTBED_Operation *
912 GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls,
913 unsigned int num_peers,
914 struct GNUNET_TESTBED_Peer *peers,
915 enum GNUNET_TESTBED_TopologyOption topo,
920 * All peers must have been started before calling this function.
921 * This function then connects the given peers in the P2P overlay
922 * using the given topology.
924 * @param op_cls closure argument to give with the operation event
925 * @param num_peers number of peers in 'peers'
926 * @param peers array of 'num_peers' with the peers to configure
927 * @param topo desired underlay topology to use
928 * @param ... topology-specific options
929 * @return handle to the operation, NULL if connecting these
930 * peers is fundamentally not possible at this time (peers
931 * not running or underlay disallows)
933 struct GNUNET_TESTBED_Operation *
934 GNUNET_TESTBED_overlay_configure_topology (void *op_cls,
935 unsigned int num_peers,
936 struct GNUNET_TESTBED_Peer *peers,
937 enum GNUNET_TESTBED_TopologyOption topo,
942 * Ask the testbed controller to write the current overlay topology to
943 * a file. Naturally, the file will only contain a snapshot as the
944 * topology may evolve all the time.
946 * @param controller overlay controller to inspect
947 * @param filename name of the file the topology should
951 GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller *controller,
952 const char *filename);
956 * Adapter function called to establish a connection to
960 * @param cfg configuration of the peer to connect to
961 * @return service handle to return in 'op_result', NULL on error
963 typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls,
964 const struct GNUNET_CONFIGURATION_Handle *cfg);
968 * Adapter function called to destroy a connection to
972 * @param op_result service handle returned from the connect adapter
974 typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls,
979 * Connect to a service offered by the given peer. Will ensure that
980 * the request is queued to not overwhelm our ability to create and
981 * maintain connections with other systems. The actual service
982 * handle is then returned via the 'op_result' member in the event
983 * callback. The 'ca' callback is used to create the connection
984 * when the time is right; the 'da' callback will be used to
985 * destroy the connection (upon 'GNUNET_TESTBED_operation_done').
986 * 'GNUNET_TESTBED_operation_cancel' can be used to abort this
987 * operation until the event callback has been called.
989 * @param op_cls closure to pass in operation event
990 * @param peer peer that runs the service
991 * @param service_name name of the service to connect to
992 * @param ca helper function to establish the connection
993 * @param da helper function to close the connection
994 * @param cada_cls closure for ca and da
995 * @return handle for the operation
997 struct GNUNET_TESTBED_Operation *
998 GNUNET_TESTBED_service_connect (void *op_cls,
999 struct GNUNET_TESTBED_Peer *peer,
1000 const char *service_name,
1001 GNUNET_TESTBED_ConnectAdapter ca,
1002 GNUNET_TESTBED_DisconnectAdapter da,
1007 * Cancel a pending operation. Releases all resources
1008 * of the operation and will ensure that no event
1009 * is generated for the operation. Does NOT guarantee
1010 * that the operation will be fully undone (or that
1011 * nothing ever happened).
1013 * @param operation operation to cancel
1016 GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation);
1020 * Signal that the information from an operation has been fully
1021 * processed. This function MUST be called for each event
1022 * of type 'operation_finished' to fully remove the operation
1023 * from the operation queue. After calling this function, the
1024 * 'op_result' becomes invalid (!).
1026 * @param operation operation to signal completion for
1029 GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation);
1033 * Configure and run a testbed using the given
1034 * master controller on 'num_hosts' starting
1035 * 'num_peers' using the given peer configuration.
1037 * @param controller master controller for the testbed
1038 * (must not be destroyed until after the
1039 * testbed is destroyed).
1040 * @param num_hosts number of hosts in 'hosts', 0 to only
1042 * @param hosts list of hosts to use for the testbed
1043 * @param num_peers number of peers to start
1044 * @param peer_cfg peer configuration template to use
1045 * @param underlay_topology underlay topology to create
1046 * @param va topology-specific options
1047 * @return handle to the testbed
1049 struct GNUNET_TESTBED_Testbed *
1050 GNUNET_TESTBED_create_va (struct GNUNET_TESTBED_Controller *controller,
1051 unsigned int num_hosts,
1052 struct GNUNET_TESTBED_Host **hosts,
1053 unsigned int num_peers,
1054 const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
1055 enum GNUNET_TESTBED_TopologyOption underlay_topology,
1060 * Configure and run a testbed using the given
1061 * master controller on 'num_hosts' starting
1062 * 'num_peers' using the given peer configuration.
1064 * @param controller master controller for the testbed
1065 * (must not be destroyed until after the
1066 * testbed is destroyed).
1067 * @param num_hosts number of hosts in 'hosts', 0 to only
1069 * @param hosts list of hosts to use for the testbed
1070 * @param num_peers number of peers to start
1071 * @param peer_cfg peer configuration template to use
1072 * @param underlay_topology underlay topology to create
1073 * @param ... topology-specific options
1075 struct GNUNET_TESTBED_Testbed *
1076 GNUNET_TESTBED_create (struct GNUNET_TESTBED_Controller *controller,
1077 unsigned int num_hosts,
1078 struct GNUNET_TESTBED_Host **hosts,
1079 unsigned int num_peers,
1080 const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
1081 enum GNUNET_TESTBED_TopologyOption underlay_topology,
1086 * Destroy a testbed. Stops all running peers and then
1087 * destroys all peers. Does NOT destroy the master controller.
1089 * @param testbed testbed to destroy
1092 GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed);
1096 * Convenience method for running a testbed with
1097 * a single call. Underlay and overlay topology
1098 * are configured using the "UNDERLAY" and "OVERLAY"
1099 * options in the "[testbed]" section of the configuration\
1100 * (with possible options given in "UNDERLAY_XXX" and/or
1103 * The testbed is to be terminated using a call to
1104 * "GNUNET_SCHEDULER_shutdown".
1106 * @param host_filename name of the file with the 'hosts', NULL
1107 * to run everything on 'localhost'
1108 * @param cfg configuration to use (for testbed, controller and peers)
1109 * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg?
1110 * @param event_mask bit mask with set of events to call 'cc' for;
1111 * or-ed values of "1LL" shifted by the
1112 * respective 'enum GNUNET_TESTBED_EventType'
1113 * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...")
1114 * @param cc controller callback to invoke on events
1115 * @param cc_cls closure for cc
1116 * @param master task to run once the testbed is ready
1117 * @param master_cls closure for 'task'.
1120 GNUNET_TESTBED_run (const char *host_filename,
1121 const struct GNUNET_CONFIGURATION_Handle *cfg,
1122 unsigned int num_peers,
1123 uint64_t event_mask,
1124 GNUNET_TESTBED_ControllerCallback cc,
1126 GNUNET_SCHEDULER_Task master,
1131 * Signature of a main function for a testcase.
1133 * @param cls closure
1134 * @param num_peers number of peers in 'peers'
1135 * @param peers handle to peers run in the testbed
1137 typedef void (*GNUNET_TESTBED_TestMaster)(void *cls,
1138 unsigned int num_peers,
1139 struct GNUNET_TESTBED_Peer **peers);
1143 * Convenience method for running a "simple" test on the local system
1144 * with a single call from 'main'. Underlay and overlay topology are
1145 * configured using the "UNDERLAY" and "OVERLAY" options in the
1146 * "[testbed]" section of the configuration (with possible options
1147 * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX").
1149 * The test is to be terminated using a call to
1150 * "GNUNET_SCHEDULER_shutdown". If starting the test fails,
1151 * the program is stopped without 'master' ever being run.
1153 * NOTE: this function should be called from 'main', NOT from
1154 * within a GNUNET_SCHEDULER-loop. This function will initialze
1155 * the scheduler loop, the testbed and then pass control to
1158 * @param testname name of the testcase (to configure logging, etc.)
1159 * @param cfg_filename configuration filename to use
1160 * (for testbed, controller and peers)
1161 * @param num_peers number of peers to start
1162 * @param test_master task to run once the test is ready
1163 * @param test_master_cls closure for 'task'.
1166 GNUNET_TESTBED_test_run (const char *testname,
1167 const char *cfg_filename,
1168 unsigned int num_peers,
1169 GNUNET_TESTBED_TestMaster test_master,
1170 void *test_master_cls);
1173 #if 0 /* keep Emacsens' auto-indent happy */