2 This file is part of GNUnet.
3 (C) 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 2, 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 testbed/gnunet-service-testbed.h
23 * @brief data structures shared amongst components of TESTBED service
24 * @author Sree Harsha Totakura
28 #include "gnunet_util_lib.h"
29 #include "gnunet_testbed_service.h"
30 #include "gnunet_transport_service.h"
31 #include "gnunet_core_service.h"
34 #include "testbed_api.h"
35 #include "testbed_api_operations.h"
36 #include "testbed_api_hosts.h"
37 #include "gnunet_testing_lib.h"
43 #define LOG(kind,...) \
44 GNUNET_log (kind, __VA_ARGS__)
49 #define LOG_DEBUG(...) \
50 LOG (GNUNET_ERROR_TYPE_DEBUG, __VA_ARGS__)
53 * By how much should the arrays lists grow
55 #define LIST_GROW_STEP 10
69 * The destination host is reachable thru
76 * Context information for operations forwarded to subcontrollers
78 struct ForwardedOperationContext
81 * The next pointer for DLL
83 struct ForwardedOperationContext *next;
86 * The prev pointer for DLL
88 struct ForwardedOperationContext *prev;
91 * The generated operation context
93 struct OperationContext *opc;
96 * The client to which we have to reply
98 struct GNUNET_SERVER_Client *client;
106 * Task ID for the timeout task
108 GNUNET_SCHEDULER_TaskIdentifier timeout_task;
111 * The id of the operation that has been forwarded
113 uint64_t operation_id;
116 * The type of the operation which is forwarded
118 enum OperationType type;
124 * A DLL of host registrations to be made
126 struct HostRegistration
129 * next registration in the DLL
131 struct HostRegistration *next;
134 * previous registration in the DLL
136 struct HostRegistration *prev;
139 * The callback to call after this registration's status is available
141 GNUNET_TESTBED_HostRegistrationCompletion cb;
144 * The closure for the above callback
149 * The host that has to be registered
151 struct GNUNET_TESTBED_Host *host;
156 * Context information used while linking controllers
158 struct LinkControllersContext
161 * The client which initiated the link controller operation
163 struct GNUNET_SERVER_Client *client;
166 * The ID of the operation
168 uint64_t operation_id;
174 * Structure representing a connected(directly-linked) controller
179 * The controller process handle if we had started the controller
181 struct GNUNET_TESTBED_ControllerProc *controller_proc;
184 * The controller handle
186 struct GNUNET_TESTBED_Controller *controller;
189 * handle to lcc which is associated with this slave startup. Should be set to
190 * NULL when the slave has successfully started up
192 struct LinkControllersContext *lcc;
195 * Head of the host registration DLL
197 struct HostRegistration *hr_dll_head;
200 * Tail of the host registration DLL
202 struct HostRegistration *hr_dll_tail;
205 * The current host registration handle
207 struct GNUNET_TESTBED_HostRegistrationHandle *rhandle;
210 * Hashmap to hold Registered host contexts
212 struct GNUNET_CONTAINER_MultiHashMap *reghost_map;
215 * The id of the host this controller is running on
234 * The peer handle from testing API
236 struct GNUNET_TESTING_Peer *peer;
239 * The modified (by GNUNET_TESTING_peer_configure) configuration this
240 * peer is configured with
242 struct GNUNET_CONFIGURATION_Handle *cfg;
245 * Is the peer running
254 * The slave this peer is started through
259 * The id of the remote host this peer is running on
261 uint32_t remote_host_id;
268 * Is this peer locally created?
273 * Our local reference id for this peer
278 * References to peers are using in forwarded overlay contexts and remote
279 * overlay connect contexts. A peer can only be destroyed after all such
280 * contexts are destroyed. For this, we maintain a reference counter. When we
281 * use a peer in any such context, we increment this counter. We decrement it
282 * when we are destroying these contexts
284 uint32_t reference_cnt;
287 * While destroying a peer, due to the fact that there could be references to
288 * this peer, we delay the peer destroy to a further time. We do this by using
289 * this flag to destroy the peer while destroying a context in which this peer
290 * has been used. When the flag is set to 1 and reference_cnt = 0 we destroy
293 uint32_t destroy_flag;
299 * The main context information associated with the client which started us
304 * The client handle associated with this context
306 struct GNUNET_SERVER_Client *client;
309 * The network address of the master controller
314 * The TESTING system handle for starting peers locally
316 struct GNUNET_TESTING_System *system;
319 * Our host id according to this context
326 * The structure for identifying a shared service
331 * The name of the shared service
336 * Number of shared peers per instance of the shared service
341 * Number of peers currently sharing the service
343 uint32_t num_sharing;
348 * Context information to used during operations which forward the overlay
351 struct ForwardedOverlayConnectContext
354 * next ForwardedOverlayConnectContext in the DLL
356 struct ForwardedOverlayConnectContext *next;
359 * previous ForwardedOverlayConnectContext in the DLL
361 struct ForwardedOverlayConnectContext *prev;
364 * A copy of the original overlay connect message
366 struct GNUNET_MessageHeader *orig_msg;
369 * The id of the operation which created this context information
371 uint64_t operation_id;
384 * Id of the host where peer2 is running
386 uint32_t peer2_host_id;
391 * The type for data structures which commonly arrive at the slave_event_callback
396 * Type for RegisteredHostContext closures
398 CLOSURE_TYPE_RHC = 1,
401 * Type for LinkControllersForwardingContext closures
408 * This context information will be created for each host that is registered at
409 * slave controllers during overlay connects.
411 struct RegisteredHostContext
414 * The type of this data structure. Set this to CLOSURE_TYPE_RHC
416 enum ClosureType type;
419 * The host which is being registered
421 struct GNUNET_TESTBED_Host *reg_host;
424 * The host of the controller which has to connect to the above rhost
426 struct GNUNET_TESTBED_Host *host;
429 * The gateway to which this operation is forwarded to
431 struct Slave *gateway;
434 * The gateway through which peer2's controller can be reached
436 struct Slave *gateway2;
439 * Handle for sub-operations
441 struct GNUNET_TESTBED_Operation *sub_op;
444 * The client which initiated the link controller operation
446 struct GNUNET_SERVER_Client *client;
449 * Head of the ForwardedOverlayConnectContext DLL
451 struct ForwardedOverlayConnectContext *focc_dll_head;
454 * Tail of the ForwardedOverlayConnectContext DLL
456 struct ForwardedOverlayConnectContext *focc_dll_tail;
459 * Enumeration of states for this context
470 * State where we attempt to get peer2's controller configuration
475 * State where we attempt to link the controller of peer 1 to the controller
481 * State where we attempt to do the overlay connection again
490 * States of LCFContext
495 * The Context has been initialized; Nothing has been done on it
500 * Delegated host has been registered at the forwarding controller
502 DELEGATED_HOST_REGISTERED,
505 * The slave host has been registred at the forwarding controller
507 SLAVE_HOST_REGISTERED,
510 * The context has been finished (may have error)
517 * Link controllers request forwarding context
522 * The type of this data structure. Set this to CLOSURE_TYPE_LCF
524 enum ClosureType type;
527 * The gateway which will pass the link message to delegated host
529 struct Slave *gateway;
532 * The client which has asked to perform this operation
534 struct GNUNET_SERVER_Client *client;
537 * Handle for operations which are forwarded while linking controllers
539 struct GNUNET_TESTBED_Operation *op;
542 * The configuration which has to be either used as a template while starting
543 * the delegated controller or for connecting to the delegated controller
545 struct GNUNET_CONFIGURATION_Handle *cfg;
550 GNUNET_SCHEDULER_TaskIdentifier timeout_task;
553 * The id of the operation which created this context
555 uint64_t operation_id;
558 * should the slave controller start the delegated controller?
563 * The state of this context
565 enum LCFContextState state;
570 uint32_t delegated_host_id;
575 uint32_t slave_host_id;
581 * Structure of a queue entry in LCFContext request queue
583 struct LCFContextQueue
588 struct LCFContext *lcf;
593 struct LCFContextQueue *next;
598 struct LCFContextQueue *prev;
603 * Context data for GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS handler
605 struct HandlerContext_ShutdownPeers
608 * The number of slave we expect to hear from since we forwarded the
609 * GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS message to them
611 unsigned int nslaves;
614 * Did we observe a timeout with respect to this operation at any of the
624 struct GNUNET_CONFIGURATION_Handle *our_config;
627 * The master context; generated with the first INIT message
629 extern struct Context *GST_context;
632 * DLL head for forwarded operation contexts
634 extern struct ForwardedOperationContext *fopcq_head;
637 * DLL tail for forwarded operation contexts
639 extern struct ForwardedOperationContext *fopcq_tail;
642 * A list of peers we know about
644 extern struct Peer **GST_peer_list;
649 extern struct GNUNET_TESTBED_Host **GST_host_list;
652 * A list of directly linked neighbours
654 extern struct Slave **GST_slave_list;
657 * Operation queue for open file descriptors
659 extern struct OperationQueue *GST_opq_openfds;
662 * Timeout for operations which may take some time
664 const extern struct GNUNET_TIME_Relative GST_timeout;
667 * The size of the peer list
669 extern unsigned int GST_peer_list_size;
672 * The size of the host list
674 extern unsigned int GST_host_list_size;
677 * The size of directly linked neighbours list
679 extern unsigned int GST_slave_list_size;
682 * The directory where to store load statistics data
684 extern char *GST_stats_dir;
688 * Similar to GNUNET_array_grow(); however instead of calling GNUNET_array_grow()
689 * several times we call it only once. The array is also made to grow in steps
692 * @param ptr the array pointer to grow
693 * @param size the size of array
694 * @param accommodate_size the size which the array has to accommdate; after
695 * this call the array will be big enough to accommdate sizes upto
698 #define GST_array_grow_large_enough(ptr, size, accommodate_size) \
701 unsigned int growth_size; \
702 GNUNET_assert (size <= accommodate_size); \
703 growth_size = size; \
704 while (growth_size <= accommodate_size) \
705 growth_size += LIST_GROW_STEP; \
706 GNUNET_array_grow (ptr, size, growth_size); \
707 GNUNET_assert (size > accommodate_size); \
712 * Queues a message in send queue for sending to the service
714 * @param client the client to whom the queued message has to be sent
715 * @param msg the message to queue
718 GST_queue_message (struct GNUNET_SERVER_Client *client,
719 struct GNUNET_MessageHeader *msg);
723 * Function to destroy a peer
725 * @param peer the peer structure to destroy
728 GST_destroy_peer (struct Peer *peer);
732 * Stops and destroys all peers
735 GST_destroy_peers ();
739 * Finds the route with directly connected host as destination through which
740 * the destination host can be reached
742 * @param host_id the id of the destination host
743 * @return the route with directly connected destination host; NULL if no route
747 GST_find_dest_route (uint32_t host_id);
751 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_OLCONNECT messages
754 * @param client identification of the client
755 * @param message the actual message
758 GST_handle_overlay_connect (void *cls, struct GNUNET_SERVER_Client *client,
759 const struct GNUNET_MessageHeader *message);
763 * Adds a host registration's request to a slave's registration queue
765 * @param slave the slave controller at which the given host has to be
767 * @param cb the host registration completion callback
768 * @param cb_cls the closure for the host registration completion callback
769 * @param host the host which has to be registered
772 GST_queue_host_registration (struct Slave *slave,
773 GNUNET_TESTBED_HostRegistrationCompletion cb,
774 void *cb_cls, struct GNUNET_TESTBED_Host *host);
778 * Callback to relay the reply msg of a forwarded operation back to the client
780 * @param cls ForwardedOperationContext
781 * @param msg the message to relay
784 GST_forwarded_operation_reply_relay (void *cls,
785 const struct GNUNET_MessageHeader *msg);
789 * Task to free resources when forwarded operation has been timedout
791 * @param cls the ForwardedOperationContext
792 * @param tc the task context from scheduler
795 GST_forwarded_operation_timeout (void *cls,
796 const struct GNUNET_SCHEDULER_TaskContext *tc);
800 * Clears the forwarded operations queue
807 * Send operation failure message to client
809 * @param client the client to which the failure message has to be sent to
810 * @param operation_id the id of the failed operation
811 * @param emsg the error message; can be NULL
814 GST_send_operation_fail_msg (struct GNUNET_SERVER_Client *client,
815 uint64_t operation_id, const char *emsg);
819 * Function to send generic operation success message to given client
821 * @param client the client to send the message to
822 * @param operation_id the id of the operation which was successful
825 GST_send_operation_success_msg (struct GNUNET_SERVER_Client *client,
826 uint64_t operation_id);
830 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_REQUESTCONNECT messages
833 * @param client identification of the client
834 * @param message the actual message
837 GST_handle_remote_overlay_connect (void *cls,
838 struct GNUNET_SERVER_Client *client,
839 const struct GNUNET_MessageHeader *message);
843 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_CREATEPEER messages
846 * @param client identification of the client
847 * @param message the actual message
850 GST_handle_peer_create (void *cls, struct GNUNET_SERVER_Client *client,
851 const struct GNUNET_MessageHeader *message);
855 * Message handler for GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
858 * @param client identification of the client
859 * @param message the actual message
862 GST_handle_peer_destroy (void *cls, struct GNUNET_SERVER_Client *client,
863 const struct GNUNET_MessageHeader *message);
867 * Message handler for GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
870 * @param client identification of the client
871 * @param message the actual message
874 GST_handle_peer_start (void *cls, struct GNUNET_SERVER_Client *client,
875 const struct GNUNET_MessageHeader *message);
879 * Message handler for GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
882 * @param client identification of the client
883 * @param message the actual message
886 GST_handle_peer_stop (void *cls, struct GNUNET_SERVER_Client *client,
887 const struct GNUNET_MessageHeader *message);
891 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_GETPEERCONFIG messages
894 * @param client identification of the client
895 * @param message the actual message
898 GST_handle_peer_get_config (void *cls, struct GNUNET_SERVER_Client *client,
899 const struct GNUNET_MessageHeader *message);
903 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS messages
906 * @param client identification of the client
907 * @param message the actual message
910 GST_handle_shutdown_peers (void *cls, struct GNUNET_SERVER_Client *client,
911 const struct GNUNET_MessageHeader *message);
915 * Handler for GNUNET_TESTBED_ManagePeerServiceMessage message
918 * @param client identification of client
919 * @param message the actual message
922 GST_handle_manage_peer_service (void *cls, struct GNUNET_SERVER_Client *client,
923 const struct GNUNET_MessageHeader *message);
927 * Frees the ManageServiceContext queue
934 * Processes a forwarded overlay connect context in the queue of the given RegisteredHostContext
936 * @param rhc the RegisteredHostContext
939 GST_process_next_focc (struct RegisteredHostContext *rhc);
943 * Cleans up ForwardedOverlayConnectContext
945 * @param focc the ForwardedOverlayConnectContext to cleanup
948 GST_cleanup_focc (struct ForwardedOverlayConnectContext *focc);
952 * Clears all pending overlay connect contexts in queue
959 * Clears all pending remote overlay connect contexts in queue
966 * Initializes the cache
968 * @param size the size of the cache
971 GST_cache_init (unsigned int size);
982 * Looks up in the hello cache and returns the HELLO of the given peer
984 * @param peer_id the index of the peer whose HELLO has to be looked up
985 * @return the HELLO message; NULL if not found
987 const struct GNUNET_MessageHeader *
988 GST_cache_lookup_hello (const unsigned int peer_id);
992 * Caches the HELLO of the given peer. Updates the HELLO if it was already
995 * @param peer_id the peer identity of the peer whose HELLO has to be cached
996 * @param hello the HELLO message
999 GST_cache_add_hello (const unsigned int peer_id,
1000 const struct GNUNET_MessageHeader *hello);
1004 * Functions of this type are called when the needed handle is available for
1005 * usage. These functions are to be registered with either of the functions
1006 * GST_cache_get_handle_transport() or GST_cache_get_handle_core(). The
1007 * corresponding handles will be set and if they are not, then it signals an
1008 * error while opening the handles.
1010 * @param cls the closure passed to GST_cache_get_handle_transport() or
1011 * GST_cache_get_handle_core()
1012 * @param ch the handle to CORE. Can be NULL if it is not requested
1013 * @param th the handle to TRANSPORT. Can be NULL if it is not requested
1014 * @param peer_id the identity of the peer. Will be NULL if ch is NULL. In other
1015 * cases, its value being NULL means that CORE connection has failed.
1017 typedef void (*GST_cache_handle_ready_cb) (void *cls,
1018 struct GNUNET_CORE_Handle * ch,
1019 struct GNUNET_TRANSPORT_Handle * th,
1020 const struct GNUNET_PeerIdentity *
1025 * Callback to notify when the target peer given to
1026 * GST_cache_get_handle_transport() is connected. Note that this callback may
1027 * not be called if the target peer is already connected. Use
1028 * GNUNET_TRANSPORT_check_neighbour_connected() to check if the target peer is
1029 * already connected or not. This callback will be called only once or never (in
1030 * case the target cannot be connected).
1032 * @param cls the closure given to GST_cache_get_handle_done() for this callback
1033 * @param target the peer identity of the target peer. The pointer should be
1034 * valid until GST_cache_get_handle_done() is called.
1036 typedef void (*GST_cache_peer_connect_notify) (void *cls,
1037 const struct GNUNET_PeerIdentity
1042 * Get a transport handle with the given configuration. If the handle is already
1043 * cached before, it will be retured in the given callback; the peer_id is used to lookup in the
1044 * cache. If not a new operation is started to open the transport handle and
1045 * will be given in the callback when it is available.
1047 * @param peer_id the index of the peer
1048 * @param cfg the configuration with which the transport handle has to be
1049 * created if it was not present in the cache
1050 * @param cb the callback to notify when the transport handle is available
1051 * @param cb_cls the closure for the above callback
1052 * @param target the peer identify of the peer whose connection to our TRANSPORT
1053 * subsystem will be notified through the connect_notify_cb. Can be NULL
1054 * @param connect_notify_cb the callback to call when the given target peer is
1055 * connected. This callback will only be called once or never again (in
1056 * case the target peer cannot be connected). Can be NULL
1057 * @param connect_notify_cb_cls the closure for the above callback
1058 * @return the handle which can be used cancel or mark that the handle is no
1061 struct GSTCacheGetHandle *
1062 GST_cache_get_handle_transport (unsigned int peer_id,
1063 const struct GNUNET_CONFIGURATION_Handle *cfg,
1064 GST_cache_handle_ready_cb cb, void *cb_cls,
1065 const struct GNUNET_PeerIdentity *target,
1066 GST_cache_peer_connect_notify connect_notify_cb,
1067 void *connect_notify_cb_cls);
1071 * Get a CORE handle with the given configuration. If the handle is already
1072 * cached before, it will be retured in the given callback; the peer_id is used
1073 * to lookup in the cache. If the handle is not cached before, a new operation
1074 * is started to open the CORE handle and will be given in the callback when it
1075 * is available along with the peer identity
1077 * @param peer_id the index of the peer
1078 * @param cfg the configuration with which the transport handle has to be
1079 * created if it was not present in the cache
1080 * @param cb the callback to notify when the transport handle is available
1081 * @param cb_cls the closure for the above callback
1082 * @param target the peer identify of the peer whose connection to our CORE
1083 * subsystem will be notified through the connect_notify_cb. Can be NULL
1084 * @param connect_notify_cb the callback to call when the given target peer is
1085 * connected. This callback will only be called once or never again (in
1086 * case the target peer cannot be connected). Can be NULL
1087 * @param connect_notify_cb_cls the closure for the above callback
1088 * @return the handle which can be used cancel or mark that the handle is no
1091 struct GSTCacheGetHandle *
1092 GST_cache_get_handle_core (unsigned int peer_id,
1093 const struct GNUNET_CONFIGURATION_Handle *cfg,
1094 GST_cache_handle_ready_cb cb, void *cb_cls,
1095 const struct GNUNET_PeerIdentity *target,
1096 GST_cache_peer_connect_notify connect_notify_cb,
1097 void *connect_notify_cb_cls);
1101 * Mark the GetCacheHandle as being done if a handle has been provided already
1102 * or as being cancelled if the callback for the handle hasn't been called.
1104 * @param cgh the CacheGetHandle handle
1107 GST_cache_get_handle_done (struct GSTCacheGetHandle *cgh);
1111 * Initialize logging CPU and IO statisticfs. Checks the configuration for
1112 * "STATS_DIR" and logs to a file in that directory. The file is name is
1113 * generated from the hostname and the process's PID.
1116 GST_stats_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
1120 * Shutdown the status calls module.
1123 GST_stats_destroy ();
1125 /* End of gnunet-service-testbed.h */