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"
36 #if 0 /* keep Emacsens' auto-indent happy */
43 * Opaque handle to a host running experiments managed by the testbed framework.
44 * The master process must be able to SSH to this host without password (via
47 struct GNUNET_TESTBED_Host;
50 * Opaque handle to a peer controlled by the testbed framework. A peer runs
51 * at a particular host.
53 struct GNUNET_TESTBED_Peer;
56 * Opaque handle to an abstract operation to be executed by the testbed framework.
58 struct GNUNET_TESTBED_Operation;
61 * Handle to interact with a GNUnet testbed controller. Each
62 * controller has at least one master handle which is created when the
63 * controller is created; this master handle interacts with the
64 * controller process, destroying it destroys the controller (by
65 * closing stdin of the controller process). Additionally,
66 * controllers can interact with each other (in a P2P fashion); those
67 * links are established via TCP/IP on the controller's service port.
69 struct GNUNET_TESTBED_Controller;
72 * Handle to a large-scale testbed that is managed at a high level.
74 struct GNUNET_TESTBED_Testbed;
78 * Create a host to run peers and controllers on.
80 * @param hostname name of the host, use "NULL" for localhost
81 * @param username username to use for the login; may be NULL
82 * @param port port number to use for ssh; use 0 to let ssh decide
83 * @return handle to the host, NULL on error
85 struct GNUNET_TESTBED_Host *
86 GNUNET_TESTBED_host_create (const char *hostname,
93 * Create a host to run peers and controllers on. This function is used
94 * if a peer learns about a host via IPC between controllers (and thus
95 * some higher-level controller has already determined the unique IDs).
97 * @param id global host ID assigned to the host; 0 is
98 * reserved to always mean 'localhost'
99 * @param hostname name of the host, use "NULL" for localhost
100 * @param username username to use for the login; may be NULL
101 * @param port port number to use for ssh; use 0 to let ssh decide
102 * @return handle to the host, NULL on error
104 struct GNUNET_TESTBED_Host *
105 GNUNET_TESTBED_host_create_with_id (uint32_t id,
106 const char *hostname,
107 const char *username,
112 * Load a set of hosts from a configuration file.
114 * @param filename file with the host specification
115 * @param hosts set to the hosts found in the file
116 * @return number of hosts returned in 'hosts', 0 on error
119 GNUNET_TESTBED_hosts_load_from_file (const char *filename,
120 struct GNUNET_TESTBED_Host **hosts);
124 * Destroy a host handle. Must only be called once everything
125 * running on that host has been stopped.
127 * @param host handle to destroy
130 GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host);
134 * Enumeration with (at most 64) possible event types that
135 * can be monitored using the testbed framework.
137 enum GNUNET_TESTBED_EventType
140 * A peer has been started.
142 GNUNET_TESTBED_ET_PEER_START = 0,
145 * A peer has been stopped.
147 GNUNET_TESTBED_ET_PEER_STOP = 1,
150 * A connection between two peers was established.
152 GNUNET_TESTBED_ET_CONNECT = 2,
155 * A connection between two peers was torn down.
157 GNUNET_TESTBED_ET_DISCONNECT = 3,
160 * A requested testbed operation has been completed.
162 GNUNET_TESTBED_ET_OPERATION_FINISHED = 4,
165 * The 'GNUNET_TESTBED_run' operation has been completed
167 GNUNET_TESTBED_ET_TESTBED_ONLINE = 5
173 * Types of information that can be requested about a peer.
175 enum GNUNET_TESTBED_PeerInformationType
179 * Special value (not valid for requesting information)
180 * that is used in the event struct if a 'generic' pointer
181 * is returned (for other operations not related to this
184 GNUNET_TESTBED_PIT_GENERIC = 0,
187 * What host is the peer running on? Returns a 'const struct
188 * GNUNET_TESTBED_Host *'. Valid until
189 * 'GNUNET_TESTBED_operation_done' is called.
191 GNUNET_TESTBED_PIT_HOST,
194 * What configuration is the peer using? Returns a 'const struct
195 * GNUNET_CONFIGURATION_Handle *'. Valid until
196 * 'GNUNET_TESTNIG_operation_done' is called. However, the
197 * values may be inaccurate if the peer is reconfigured in
200 GNUNET_TESTBED_PIT_CONFIGURATION,
203 * What is the identity of the peer? Returns a
204 * 'const struct GNUNET_PeerIdentity *'. Valid until
205 * 'GNUNET_TESTNIG_operation_done' is called.
207 GNUNET_TESTBED_PIT_IDENTITY
213 * Argument to GNUNET_TESTBED_ControllerCallback with details about
216 struct GNUNET_TESTBED_EventInformation
222 enum GNUNET_TESTBED_EventType type;
225 * Details about the event.
231 * Details about peer start event.
236 * Handle for the host where the peer
239 struct GNUNET_TESTBED_Host *host;
242 * Handle for the peer that was started.
244 struct GNUNET_TESTBED_Peer *peer;
249 * Details about peer stop event.
255 * Handle for the peer that was started.
257 struct GNUNET_TESTBED_Peer *peer;
262 * Details about connect event.
267 * Handle for one of the connected peers.
269 struct GNUNET_TESTBED_Peer *peer1;
272 * Handle for one of the connected peers.
274 struct GNUNET_TESTBED_Peer *peer2;
279 * Details about disconnect event.
284 * Handle for one of the disconnected peers.
286 struct GNUNET_TESTBED_Peer *peer1;
289 * Handle for one of the disconnected peers.
291 struct GNUNET_TESTBED_Peer *peer2;
296 * Details about an operation finished event.
302 * Handle for the operation that was finished.
304 struct GNUNET_TESTBED_Operation *operation;
307 * Closure that was passed in when the event was
313 * Error message for the operation, NULL on success.
318 * Peer information type; captures which of the types
319 * in the 'op_result' is actually in use.
321 enum GNUNET_TESTBED_PeerInformationType pit;
324 * Pointer to an operation-specific return value; NULL on error;
325 * can be NULL for certain operations. Valid until
326 * 'GNUNET_TESTBED_operation_done' is called.
331 * No result (NULL pointer) or generic result
332 * (whatever the GNUNET_TESTBED_ConnectAdapter returned).
337 * Identity of host running the peer.
339 struct GNUNET_TESTBED_Host *host;
342 * Identity of the peer.
344 const struct GNUNET_PeerIdentity *pid;
347 * Configuration of the peer.
349 const struct GNUNET_CONFIGURATION_Handle *cfg;
353 } operation_finished;
357 * Details about an testbed run completed event.
363 * Error message for the operation, NULL on success.
368 * Array of peers now running (valid until
369 * 'GNUNET_TESTBED_testbed_stop' is called). Note that it is
370 * not allowed to call 'GNUNET_TESTBED_peer_destroy' on peers
373 struct GNUNET_TESTBED_Peer **peers;
376 * Size of the 'peers' array.
378 unsigned int num_peers;
380 } testbed_run_finished;
388 * Signature of the event handler function called by the
389 * respective event controller.
392 * @param event information about the event
394 typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls,
395 const struct GNUNET_TESTBED_EventInformation *event);
399 * Opaque Handle for Controller process
401 struct GNUNET_TESTBED_ControllerProc;
405 * Starts a controller process at the host
407 * @param host the host where the controller has to be started; NULL for localhost
408 * @return the controller process handle
410 struct GNUNET_TESTBED_ControllerProc *
411 GNUNET_TESTBED_controller_start (struct GNUNET_TESTBED_Host *host);
415 * Stop the controller process (also will terminate all peers and controllers
416 * dependent on this controller). This function blocks until the testbed has
417 * been fully terminated (!).
419 * @param cproc the controller process handle
422 GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_ControllerProc *cproc);
426 * Connect to a controller process using the given configuration at the
429 * @param cfg configuration to use
430 * @param host host to run the controller on; This should be the same host if
431 * the controller was previously started with
432 * GNUNET_TESTBED_controller_start; NULL for localhost
433 * @param host host where this controller is being run;
434 * @param event_mask bit mask with set of events to call 'cc' for;
435 * or-ed values of "1LL" shifted by the
436 * respective 'enum GNUNET_TESTBED_EventType'
437 * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...")
438 * @param cc controller callback to invoke on events
439 * @param cc_cls closure for cc
440 * @return handle to the controller
442 struct GNUNET_TESTBED_Controller *
443 GNUNET_TESTBED_controller_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
444 struct GNUNET_TESTBED_Host *host,
446 GNUNET_TESTBED_ControllerCallback cc,
451 * Configure shared services at a controller. Using this function,
452 * you can specify that certain services (such as "resolver")
453 * should not be run for each peer but instead be shared
454 * across N peers on the specified host. This function
455 * must be called before any peers are created at the host.
457 * @param controller controller to configure
458 * @param service_name name of the service to share
459 * @param num_peers number of peers that should share one instance
460 * of the specified service (1 for no sharing is the default),
461 * use 0 to disable the service
464 GNUNET_TESTBED_controller_configure_sharing (struct GNUNET_TESTBED_Controller *controller,
465 const char *service_name,
470 * Stop the given controller (also will terminate all peers and
471 * controllers dependent on this controller). This function
472 * blocks until the testbed has been fully terminated (!).
474 * @param controller handle to controller to stop
477 GNUNET_TESTBED_controller_disconnect (struct GNUNET_TESTBED_Controller *controller);
481 * Opaque handle for host registration
483 struct GNUNET_TESTBED_HostRegistrationHandle;
487 * Callback which will be called to after a host registration succeeded or failed
489 * @param cls the closure
490 * @param emsg the error message; NULL if host registration is successful
492 typedef void (* GNUNET_TESTBED_HostRegistrationCompletion) (void *cls,
497 * Register a host with the controller
499 * @param controller the controller handle
500 * @param host the host to register
501 * @param cc the completion callback to call to inform the status of
502 * registration. After calling this callback the registration handle
503 * will be invalid. Cannot be NULL
504 * @param cc_cls the closure for the cc
505 * @return handle to the host registration which can be used to cancel the
506 * registration; NULL if another registration handle is present and
509 struct GNUNET_TESTBED_HostRegistrationHandle *
510 GNUNET_TESTBED_register_host (struct GNUNET_TESTBED_Controller *controller,
511 struct GNUNET_TESTBED_Host *host,
512 GNUNET_TESTBED_HostRegistrationCompletion cc,
517 * Cancel the pending registration. Note that the registration message will
518 * already be queued to be sent to the service, cancellation has only the
519 * effect that the registration completion callback for the registration is
520 * never called and from our perspective the host is not registered until the
521 * completion callback is called.
523 * @param handle the registration handle to cancel
526 GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle
531 * Create a link from slave controller to delegated controller. Whenever the
532 * master controller is asked to start a peer at the delegated controller the
533 * request will be routed towards slave controller (if a route exists). The
534 * slave controller will then route it to the delegated controller. The
535 * configuration of the slave controller is given and to be used to either
536 * create the slave controller or to connect to an existing slave controller
537 * process. 'is_subordinate' specifies if the given slave controller should be
538 * started and managed by the master controller, or if the slave already has a
539 * master and this is just a secondary master that is also allowed to use the
542 * @param master handle to the master controller who creates the association
543 * @param delegated_host requests to which host should be delegated; cannot be NULL
544 * @param slave_host which host is used to run the slave controller; use NULL to
545 * make the master controller connect to the delegated host
546 * @param slave_cfg configuration to use for the slave controller
547 * @param is_subordinate GNUNET_YES if the controller at delegated_host should
548 * be started by the master controller; GNUNET_NO if we are just
549 * allowed to use the slave via TCP/IP
552 GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master,
553 struct GNUNET_TESTBED_Host *delegated_host,
554 struct GNUNET_TESTBED_Host *slave_host,
555 const struct GNUNET_CONFIGURATION_Handle *slave_cfg,
560 * Same as the GNUNET_TESTBED_controller_link, however expects configuration in
561 * serialized and compressed
563 * @param master handle to the master controller who creates the association
564 * @param delegated_host requests to which host should be delegated; cannot be NULL
565 * @param slave_host which host is used to run the slave controller; use NULL to
566 * make the master controller connect to the delegated host
567 * @param sxcfg serialized and compressed configuration
568 * @param sxcfg_size the size scfg
569 * @param scfg_size the size of uncompressed serialized configuration
570 * @param is_subordinate GNUNET_YES if the controller at delegated_host should
571 * be started by the master controller; GNUNET_NO if we are just
572 * allowed to use the slave via TCP/IP
575 GNUNET_TESTBED_controller_link_2 (struct GNUNET_TESTBED_Controller *master,
576 struct GNUNET_TESTBED_Host *delegated_host,
577 struct GNUNET_TESTBED_Host *slave_host,
585 * Create the given peer at the specified host using the given
586 * controller. If the given controller is not running on the target
587 * host, it should find or create a controller at the target host and
588 * delegate creating the peer. Explicit delegation paths can be setup
589 * using 'GNUNET_TESTBED_controller_link'. If no explicit delegation
590 * path exists, a direct link with a subordinate controller is setup
591 * for the first delegated peer to a particular host; the subordinate
592 * controller is then destroyed once the last peer that was delegated
593 * to the remote host is stopped.
595 * Creating the peer only creates the handle to manipulate and further
596 * configure the peer; use "GNUNET_TESTBED_peer_start" and
597 * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's
600 * Note that the given configuration will be adjusted by the
601 * controller to avoid port/path conflicts with other peers.
602 * The "final" configuration can be obtained using
603 * 'GNUNET_TESTBED_peer_get_information'.
605 * @param controller controller process to use
606 * @param host host to run the peer on
607 * @param cfg configuration to use for the peer
608 * @return handle to the peer (actual startup will happen asynchronously)
610 struct GNUNET_TESTBED_Peer *
611 GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller,
612 struct GNUNET_TESTBED_Host *host,
613 const struct GNUNET_CONFIGURATION_Handle *cfg);
617 * Start the given peer.
619 * @param peer peer to start
620 * @return handle to the operation
622 struct GNUNET_TESTBED_Operation *
623 GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer);
627 * Stop the given peer. The handle remains valid (use
628 * "GNUNET_TESTBED_peer_destroy" to fully clean up the
629 * state of the peer).
631 * @param peer peer to stop
632 * @return handle to the operation
634 struct GNUNET_TESTBED_Operation *
635 GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer);
639 * Request information about a peer.
641 * @param peer peer to request information about
642 * @param pit desired information
643 * @return handle to the operation
645 struct GNUNET_TESTBED_Operation *
646 GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer,
647 enum GNUNET_TESTBED_PeerInformationType pit);
651 * Change peer configuration. Must only be called while the
652 * peer is stopped. Ports and paths cannot be changed this
655 * @param peer peer to change configuration for
656 * @param cfg new configuration (differences to existing
657 * configuration only)
658 * @return handle to the operation
660 struct GNUNET_TESTBED_Operation *
661 GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer,
662 const struct GNUNET_CONFIGURATION_Handle *cfg);
666 * Destroy the given peer; the peer should have been
667 * stopped first (if it was started).
669 * @param peer peer to stop
670 * @return handle to the operation
672 struct GNUNET_TESTBED_Operation *
673 GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer);
677 * Options for peer connections.
679 enum GNUNET_TESTBED_ConnectOption
682 * No option (not valid as an argument).
684 GNUNET_TESTBED_CO_NONE = 0,
687 * Allow or disallow a connection between the specified peers.
688 * Followed by GNUNET_NO (int) if a connection is disallowed
689 * or GNUNET_YES if a connection is allowed. Note that the
690 * default (all connections allowed or disallowed) is
691 * specified in the configuration of the controller.
693 GNUNET_TESTBED_CO_ALLOW = 1,
696 * FIXME: add (and implement) options to limit connection to
697 * particular transports, force simulation of particular latencies
698 * or message loss rates, or set bandwidth limitations.
705 * Manipulate the P2P underlay topology by configuring a link
708 * @param op_cls closure argument to give with the operation event
709 * @param p1 first peer
710 * @param p2 second peer
711 * @param co option to change
712 * @param ap option-specific values
713 * @return handle to the operation, NULL if configuring the link at this
714 * time is not allowed
716 struct GNUNET_TESTBED_Operation *
717 GNUNET_TESTBED_underlay_configure_link_va (void *op_cls,
718 struct GNUNET_TESTBED_Peer *p1,
719 struct GNUNET_TESTBED_Peer *p2,
720 enum GNUNET_TESTBED_ConnectOption co,
725 * Manipulate the P2P underlay topology by configuring a link
728 * @param op_cls closure argument to give with the operation event
729 * @param p1 first peer
730 * @param p2 second peer
731 * @param co option to change
732 * @param ... option-specific values
733 * @return handle to the operation, NULL if configuring the link at this
734 * time is not allowed
736 struct GNUNET_TESTBED_Operation *
737 GNUNET_TESTBED_underlay_configure_link (void *op_cls,
738 struct GNUNET_TESTBED_Peer *p1,
739 struct GNUNET_TESTBED_Peer *p2,
740 enum GNUNET_TESTBED_ConnectOption co, ...);
745 * Topologies supported for testbeds.
747 enum GNUNET_TESTBED_TopologyOption
750 * A clique (everyone connected to everyone else). No options.
752 GNUNET_TESTBED_TOPOLOGY_CLIQUE,
755 * Small-world network (2d torus plus random links). Followed
756 * by the number of random links to add (unsigned int).
758 GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD,
761 * Small-world network (ring plus random links). Followed
762 * by the number of random links to add (unsigned int).
764 GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING,
767 * Ring topology. No options.
769 GNUNET_TESTBED_TOPOLOGY_RING,
772 * 2-d torus. No options.
774 GNUNET_TESTBED_TOPOLOGY_2D_TORUS,
777 * Random graph. Followed by the link density, that is the
778 * percentage of links present in relation to a clique
781 GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI,
784 * Certain percentage of peers are unable to communicate directly
785 * replicating NAT conditions. Followed by the fraction of
786 * NAT'ed peers (float).
788 GNUNET_TESTBED_TOPOLOGY_INTERNAT,
791 * Scale free topology. FIXME: options?
793 GNUNET_TESTBED_TOPOLOGY_SCALE_FREE,
796 * Straight line topology. No options.
798 GNUNET_TESTBED_TOPOLOGY_LINE,
801 * All peers are disconnected. No options.
803 GNUNET_TESTBED_TOPOLOGY_NONE,
806 * Read a topology from a given file. Followed by the name of the file (const char *).
808 GNUNET_TESTBED_TOPOLOGY_FROM_FILE
813 * Configure overall network topology to have a particular shape.
815 * @param op_cls closure argument to give with the operation event
816 * @param num_peers number of peers in 'peers'
817 * @param peers array of 'num_peers' with the peers to configure
818 * @param topo desired underlay topology to use
819 * @param ap topology-specific options
820 * @return handle to the operation, NULL if configuring the topology
821 * is not allowed at this time
823 struct GNUNET_TESTBED_Operation *
824 GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls,
825 unsigned int num_peers,
826 struct GNUNET_TESTBED_Peer **peers,
827 enum GNUNET_TESTBED_TopologyOption topo,
832 * Configure overall network topology to have a particular shape.
834 * @param op_cls closure argument to give with the operation event
835 * @param num_peers number of peers in 'peers'
836 * @param peers array of 'num_peers' with the peers to configure
837 * @param topo desired underlay topology to use
838 * @param ... topology-specific options
839 * @return handle to the operation, NULL if configuring the topology
840 * is not allowed at this time
842 struct GNUNET_TESTBED_Operation *
843 GNUNET_TESTBED_underlay_configure_topology (void *op_cls,
844 unsigned int num_peers,
845 struct GNUNET_TESTBED_Peer **peers,
846 enum GNUNET_TESTBED_TopologyOption topo,
851 * Both peers must have been started before calling this function.
852 * This function then obtains a HELLO from 'p1', gives it to 'p2'
853 * and asks 'p2' to connect to 'p1'.
855 * @param op_cls closure argument to give with the operation event
856 * @param p1 first peer
857 * @param p2 second peer
858 * @return handle to the operation, NULL if connecting these two
859 * peers is fundamentally not possible at this time (peers
860 * not running or underlay disallows)
862 struct GNUNET_TESTBED_Operation *
863 GNUNET_TESTBED_overlay_connect (void *op_cls,
864 struct GNUNET_TESTBED_Peer *p1,
865 struct GNUNET_TESTBED_Peer *p2);
869 * All peers must have been started before calling this function.
870 * This function then connects the given peers in the P2P overlay
871 * using the given topology.
873 * @param op_cls closure argument to give with the operation event
874 * @param num_peers number of peers in 'peers'
875 * @param peers array of 'num_peers' with the peers to configure
876 * @param topo desired underlay topology to use
877 * @param va topology-specific options
878 * @return handle to the operation, NULL if connecting these
879 * peers is fundamentally not possible at this time (peers
880 * not running or underlay disallows)
882 struct GNUNET_TESTBED_Operation *
883 GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls,
884 unsigned int num_peers,
885 struct GNUNET_TESTBED_Peer *peers,
886 enum GNUNET_TESTBED_TopologyOption topo,
891 * All peers must have been started before calling this function.
892 * This function then connects the given peers in the P2P overlay
893 * using the given topology.
895 * @param op_cls closure argument to give with the operation event
896 * @param num_peers number of peers in 'peers'
897 * @param peers array of 'num_peers' with the peers to configure
898 * @param topo desired underlay topology to use
899 * @param ... topology-specific options
900 * @return handle to the operation, NULL if connecting these
901 * peers is fundamentally not possible at this time (peers
902 * not running or underlay disallows)
904 struct GNUNET_TESTBED_Operation *
905 GNUNET_TESTBED_overlay_configure_topology (void *op_cls,
906 unsigned int num_peers,
907 struct GNUNET_TESTBED_Peer *peers,
908 enum GNUNET_TESTBED_TopologyOption topo,
913 * Ask the testbed controller to write the current overlay topology to
914 * a file. Naturally, the file will only contain a snapshot as the
915 * topology may evolve all the time.
917 * @param controller overlay controller to inspect
918 * @param filename name of the file the topology should
922 GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller *controller,
923 const char *filename);
927 * Adapter function called to establish a connection to
931 * @param cfg configuration of the peer to connect to
932 * @return service handle to return in 'op_result', NULL on error
934 typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls,
935 const struct GNUNET_CONFIGURATION_Handle *cfg);
939 * Adapter function called to destroy a connection to
943 * @param op_result service handle returned from the connect adapter
945 typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls,
950 * Connect to a service offered by the given peer. Will ensure that
951 * the request is queued to not overwhelm our ability to create and
952 * maintain connections with other systems. The actual service
953 * handle is then returned via the 'op_result' member in the event
954 * callback. The 'ca' callback is used to create the connection
955 * when the time is right; the 'da' callback will be used to
956 * destroy the connection (upon 'GNUNET_TESTBED_operation_done').
957 * 'GNUNET_TESTBED_operation_cancel' can be used to abort this
958 * operation until the event callback has been called.
960 * @param op_cls closure to pass in operation event
961 * @param peer peer that runs the service
962 * @param service_name name of the service to connect to
963 * @param ca helper function to establish the connection
964 * @param da helper function to close the connection
965 * @param cada_cls closure for ca and da
966 * @return handle for the operation
968 struct GNUNET_TESTBED_Operation *
969 GNUNET_TESTBED_service_connect (void *op_cls,
970 struct GNUNET_TESTBED_Peer *peer,
971 const char *service_name,
972 GNUNET_TESTBED_ConnectAdapter ca,
973 GNUNET_TESTBED_DisconnectAdapter da,
978 * Cancel a pending operation. Releases all resources
979 * of the operation and will ensure that no event
980 * is generated for the operation. Does NOT guarantee
981 * that the operation will be fully undone (or that
982 * nothing ever happened).
984 * @param operation operation to cancel
987 GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation);
991 * Signal that the information from an operation has been fully
992 * processed. This function MUST be called for each event
993 * of type 'operation_finished' to fully remove the operation
994 * from the operation queue. After calling this function, the
995 * 'op_result' becomes invalid (!).
997 * @param operation operation to signal completion for
1000 GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation);
1004 * Configure and run a testbed using the given
1005 * master controller on 'num_hosts' starting
1006 * 'num_peers' using the given peer configuration.
1008 * @param controller master controller for the testbed
1009 * (must not be destroyed until after the
1010 * testbed is destroyed).
1011 * @param num_hosts number of hosts in 'hosts', 0 to only
1013 * @param hosts list of hosts to use for the testbed
1014 * @param num_peers number of peers to start
1015 * @param peer_cfg peer configuration template to use
1016 * @param underlay_topology underlay topology to create
1017 * @param va topology-specific options
1018 * @return handle to the testbed
1020 struct GNUNET_TESTBED_Testbed *
1021 GNUNET_TESTBED_create_va (struct GNUNET_TESTBED_Controller *controller,
1022 unsigned int num_hosts,
1023 struct GNUNET_TESTBED_Host **hosts,
1024 unsigned int num_peers,
1025 const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
1026 enum GNUNET_TESTBED_TopologyOption underlay_topology,
1031 * Configure and run a testbed using the given
1032 * master controller on 'num_hosts' starting
1033 * 'num_peers' using the given peer configuration.
1035 * @param controller master controller for the testbed
1036 * (must not be destroyed until after the
1037 * testbed is destroyed).
1038 * @param num_hosts number of hosts in 'hosts', 0 to only
1040 * @param hosts list of hosts to use for the testbed
1041 * @param num_peers number of peers to start
1042 * @param peer_cfg peer configuration template to use
1043 * @param underlay_topology underlay topology to create
1044 * @param ... topology-specific options
1046 struct GNUNET_TESTBED_Testbed *
1047 GNUNET_TESTBED_create (struct GNUNET_TESTBED_Controller *controller,
1048 unsigned int num_hosts,
1049 struct GNUNET_TESTBED_Host **hosts,
1050 unsigned int num_peers,
1051 const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
1052 enum GNUNET_TESTBED_TopologyOption underlay_topology,
1057 * Destroy a testbed. Stops all running peers and then
1058 * destroys all peers. Does NOT destroy the master controller.
1060 * @param testbed testbed to destroy
1063 GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed);
1067 * Convenience method for running a testbed with
1068 * a single call. Underlay and overlay topology
1069 * are configured using the "UNDERLAY" and "OVERLAY"
1070 * options in the "[testbed]" section of the configuration\
1071 * (with possible options given in "UNDERLAY_XXX" and/or
1074 * The testbed is to be terminated using a call to
1075 * "GNUNET_SCHEDULER_shutdown".
1077 * @param host_filename name of the file with the 'hosts', NULL
1078 * to run everything on 'localhost'
1079 * @param cfg configuration to use (for testbed, controller and peers)
1080 * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg?
1081 * @param event_mask bit mask with set of events to call 'cc' for;
1082 * or-ed values of "1LL" shifted by the
1083 * respective 'enum GNUNET_TESTBED_EventType'
1084 * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...")
1085 * @param cc controller callback to invoke on events
1086 * @param cc_cls closure for cc
1087 * @param master task to run once the testbed is ready
1088 * @param master_cls closure for 'task'.
1091 GNUNET_TESTBED_run (const char *host_filename,
1092 const struct GNUNET_CONFIGURATION_Handle *cfg,
1093 unsigned int num_peers,
1094 uint64_t event_mask,
1095 GNUNET_TESTBED_ControllerCallback cc,
1097 GNUNET_SCHEDULER_Task master,
1102 * Signature of a main function for a testcase.
1104 * @param cls closure
1105 * @param num_peers number of peers in 'peers'
1106 * @param peers handle to peers run in the testbed
1108 typedef void (*GNUNET_TESTBED_TestMaster)(void *cls,
1109 unsigned int num_peers,
1110 struct GNUNET_TESTBED_Peer **peers);
1114 * Convenience method for running a "simple" test on the local system
1115 * with a single call from 'main'. Underlay and overlay topology are
1116 * configured using the "UNDERLAY" and "OVERLAY" options in the
1117 * "[testbed]" section of the configuration (with possible options
1118 * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX").
1120 * The test is to be terminated using a call to
1121 * "GNUNET_SCHEDULER_shutdown". If starting the test fails,
1122 * the program is stopped without 'master' ever being run.
1124 * NOTE: this function should be called from 'main', NOT from
1125 * within a GNUNET_SCHEDULER-loop. This function will initialze
1126 * the scheduler loop, the testbed and then pass control to
1129 * @param testname name of the testcase (to configure logging, etc.)
1130 * @param cfg_filename configuration filename to use
1131 * (for testbed, controller and peers)
1132 * @param num_peers number of peers to start
1133 * @param test_master task to run once the test is ready
1134 * @param test_master_cls closure for 'task'.
1137 GNUNET_TESTBED_test_run (const char *testname,
1138 const char *cfg_filename,
1139 unsigned int num_peers,
1140 GNUNET_TESTBED_TestMaster test_master,
1141 void *test_master_cls);
1144 #if 0 /* keep Emacsens' auto-indent happy */