2 This file is part of GNUnet.
3 (C) 2008--2013 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"
38 #include "gnunet-service-testbed_links.h"
44 #define LOG(kind,...) \
45 GNUNET_log (kind, __VA_ARGS__)
50 #define LOG_DEBUG(...) \
51 LOG (GNUNET_ERROR_TYPE_DEBUG, __VA_ARGS__)
54 * By how much should the arrays lists grow
56 #define LIST_GROW_STEP 10
70 * The destination host is reachable thru
77 * Context information for operations forwarded to subcontrollers
79 struct ForwardedOperationContext
82 * The next pointer for DLL
84 struct ForwardedOperationContext *next;
87 * The prev pointer for DLL
89 struct ForwardedOperationContext *prev;
92 * The generated operation context
94 struct OperationContext *opc;
97 * The client to which we have to reply
99 struct GNUNET_SERVER_Client *client;
107 * Task ID for the timeout task
109 GNUNET_SCHEDULER_TaskIdentifier timeout_task;
112 * The id of the operation that has been forwarded
114 uint64_t operation_id;
117 * The type of the operation which is forwarded
119 enum OperationType type;
125 * A DLL of host registrations to be made
127 struct HostRegistration
130 * next registration in the DLL
132 struct HostRegistration *next;
135 * previous registration in the DLL
137 struct HostRegistration *prev;
140 * The callback to call after this registration's status is available
142 GNUNET_TESTBED_HostRegistrationCompletion cb;
145 * The closure for the above callback
150 * The host that has to be registered
152 struct GNUNET_TESTBED_Host *host;
157 * Context information used while linking controllers
159 struct LinkControllersContext
162 * The client which initiated the link controller operation
164 struct GNUNET_SERVER_Client *client;
167 * The ID of the operation
169 uint64_t operation_id;
186 * The peer handle from testing API
188 struct GNUNET_TESTING_Peer *peer;
191 * The modified (by GNUNET_TESTING_peer_configure) configuration this
192 * peer is configured with
194 struct GNUNET_CONFIGURATION_Handle *cfg;
197 * Is the peer running
206 * The slave this peer is started through
211 * The id of the remote host this peer is running on
213 uint32_t remote_host_id;
220 * Is this peer locally created?
225 * Our local reference id for this peer
230 * References to peers are using in forwarded overlay contexts and remote
231 * overlay connect contexts. A peer can only be destroyed after all such
232 * contexts are destroyed. For this, we maintain a reference counter. When we
233 * use a peer in any such context, we increment this counter. We decrement it
234 * when we are destroying these contexts
236 uint32_t reference_cnt;
239 * While destroying a peer, due to the fact that there could be references to
240 * this peer, we delay the peer destroy to a further time. We do this by using
241 * this flag to destroy the peer while destroying a context in which this peer
242 * has been used. When the flag is set to 1 and reference_cnt = 0 we destroy
245 uint32_t destroy_flag;
251 * The main context information associated with the client which started us
256 * The client handle associated with this context
258 struct GNUNET_SERVER_Client *client;
261 * The network address of the master controller
266 * The TESTING system handle for starting peers locally
268 struct GNUNET_TESTING_System *system;
271 * Our host id according to this context
278 * The structure for identifying a shared service
283 * The name of the shared service
288 * Number of shared peers per instance of the shared service
293 * Number of peers currently sharing the service
295 uint32_t num_sharing;
300 * Context information to used during operations which forward the overlay
303 struct ForwardedOverlayConnectContext
306 * next ForwardedOverlayConnectContext in the DLL
308 struct ForwardedOverlayConnectContext *next;
311 * previous ForwardedOverlayConnectContext in the DLL
313 struct ForwardedOverlayConnectContext *prev;
316 * A copy of the original overlay connect message
318 struct GNUNET_MessageHeader *orig_msg;
321 * The id of the operation which created this context information
323 uint64_t operation_id;
336 * Id of the host where peer2 is running
338 uint32_t peer2_host_id;
343 * The type for data structures which commonly arrive at the slave_event_callback
348 * Type for RegisteredHostContext closures
350 CLOSURE_TYPE_RHC = 1,
353 * Type for LinkControllersForwardingContext closures
360 * This context information will be created for each host that is registered at
361 * slave controllers during overlay connects.
363 struct RegisteredHostContext
366 * The type of this data structure. Set this to CLOSURE_TYPE_RHC
368 enum ClosureType type;
371 * The host which is being registered
373 struct GNUNET_TESTBED_Host *reg_host;
376 * The host of the controller which has to connect to the above rhost
378 struct GNUNET_TESTBED_Host *host;
381 * The gateway to which this operation is forwarded to
383 struct Slave *gateway;
386 * The gateway through which peer2's controller can be reached
388 struct Slave *gateway2;
391 * Handle for sub-operations
393 struct GNUNET_TESTBED_Operation *sub_op;
396 * The client which initiated the link controller operation
398 struct GNUNET_SERVER_Client *client;
401 * Head of the ForwardedOverlayConnectContext DLL
403 struct ForwardedOverlayConnectContext *focc_dll_head;
406 * Tail of the ForwardedOverlayConnectContext DLL
408 struct ForwardedOverlayConnectContext *focc_dll_tail;
411 * Enumeration of states for this context
422 * State where we attempt to get peer2's controller configuration
427 * State where we attempt to link the controller of peer 1 to the controller
433 * State where we attempt to do the overlay connection again
442 * Context data for GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS handler
444 struct HandlerContext_ShutdownPeers
447 * The number of slave we expect to hear from since we forwarded the
448 * GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS message to them
450 unsigned int nslaves;
453 * Did we observe a timeout with respect to this operation at any of the
463 struct GNUNET_CONFIGURATION_Handle *our_config;
466 * The master context; generated with the first INIT message
468 extern struct Context *GST_context;
471 * DLL head for forwarded operation contexts
473 extern struct ForwardedOperationContext *fopcq_head;
476 * DLL tail for forwarded operation contexts
478 extern struct ForwardedOperationContext *fopcq_tail;
481 * A list of peers we know about
483 extern struct Peer **GST_peer_list;
488 extern struct GNUNET_TESTBED_Host **GST_host_list;
491 * Operation queue for open file descriptors
493 extern struct OperationQueue *GST_opq_openfds;
496 * Timeout for operations which may take some time
498 const extern struct GNUNET_TIME_Relative GST_timeout;
501 * The size of the peer list
503 extern unsigned int GST_peer_list_size;
506 * The size of the host list
508 extern unsigned int GST_host_list_size;
511 * The directory where to store load statistics data
513 extern char *GST_stats_dir;
517 * Similar to GNUNET_array_grow(); however instead of calling GNUNET_array_grow()
518 * several times we call it only once. The array is also made to grow in steps
521 * @param ptr the array pointer to grow
522 * @param size the size of array
523 * @param accommodate_size the size which the array has to accommdate; after
524 * this call the array will be big enough to accommdate sizes upto
527 #define GST_array_grow_large_enough(ptr, size, accommodate_size) \
530 unsigned int growth_size; \
531 GNUNET_assert (size <= accommodate_size); \
532 growth_size = size; \
533 while (growth_size <= accommodate_size) \
534 growth_size += LIST_GROW_STEP; \
535 GNUNET_array_grow (ptr, size, growth_size); \
536 GNUNET_assert (size > accommodate_size); \
541 * Queues a message in send queue for sending to the service
543 * @param client the client to whom the queued message has to be sent
544 * @param msg the message to queue
547 GST_queue_message (struct GNUNET_SERVER_Client *client,
548 struct GNUNET_MessageHeader *msg);
552 * Function to destroy a peer
554 * @param peer the peer structure to destroy
557 GST_destroy_peer (struct Peer *peer);
561 * Stops and destroys all peers
564 GST_destroy_peers ();
568 * Finds the route with directly connected host as destination through which
569 * the destination host can be reached
571 * @param host_id the id of the destination host
572 * @return the route with directly connected destination host; NULL if no route
576 GST_find_dest_route (uint32_t host_id);
580 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_OLCONNECT messages
583 * @param client identification of the client
584 * @param message the actual message
587 GST_handle_overlay_connect (void *cls, struct GNUNET_SERVER_Client *client,
588 const struct GNUNET_MessageHeader *message);
592 * Adds a host registration's request to a slave's registration queue
594 * @param slave the slave controller at which the given host has to be
596 * @param cb the host registration completion callback
597 * @param cb_cls the closure for the host registration completion callback
598 * @param host the host which has to be registered
601 GST_queue_host_registration (struct Slave *slave,
602 GNUNET_TESTBED_HostRegistrationCompletion cb,
603 void *cb_cls, struct GNUNET_TESTBED_Host *host);
607 * Callback to relay the reply msg of a forwarded operation back to the client
609 * @param cls ForwardedOperationContext
610 * @param msg the message to relay
613 GST_forwarded_operation_reply_relay (void *cls,
614 const struct GNUNET_MessageHeader *msg);
618 * Task to free resources when forwarded operation has been timedout
620 * @param cls the ForwardedOperationContext
621 * @param tc the task context from scheduler
624 GST_forwarded_operation_timeout (void *cls,
625 const struct GNUNET_SCHEDULER_TaskContext *tc);
629 * Clears the forwarded operations queue
636 * Send operation failure message to client
638 * @param client the client to which the failure message has to be sent to
639 * @param operation_id the id of the failed operation
640 * @param emsg the error message; can be NULL
643 GST_send_operation_fail_msg (struct GNUNET_SERVER_Client *client,
644 uint64_t operation_id, const char *emsg);
648 * Function to send generic operation success message to given client
650 * @param client the client to send the message to
651 * @param operation_id the id of the operation which was successful
654 GST_send_operation_success_msg (struct GNUNET_SERVER_Client *client,
655 uint64_t operation_id);
659 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_REQUESTCONNECT messages
662 * @param client identification of the client
663 * @param message the actual message
666 GST_handle_remote_overlay_connect (void *cls,
667 struct GNUNET_SERVER_Client *client,
668 const struct GNUNET_MessageHeader *message);
672 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_CREATEPEER messages
675 * @param client identification of the client
676 * @param message the actual message
679 GST_handle_peer_create (void *cls, struct GNUNET_SERVER_Client *client,
680 const struct GNUNET_MessageHeader *message);
684 * Message handler for GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
687 * @param client identification of the client
688 * @param message the actual message
691 GST_handle_peer_destroy (void *cls, struct GNUNET_SERVER_Client *client,
692 const struct GNUNET_MessageHeader *message);
696 * Message handler for GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
699 * @param client identification of the client
700 * @param message the actual message
703 GST_handle_peer_start (void *cls, struct GNUNET_SERVER_Client *client,
704 const struct GNUNET_MessageHeader *message);
708 * Message handler for GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
711 * @param client identification of the client
712 * @param message the actual message
715 GST_handle_peer_stop (void *cls, struct GNUNET_SERVER_Client *client,
716 const struct GNUNET_MessageHeader *message);
720 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_GETPEERCONFIG messages
723 * @param client identification of the client
724 * @param message the actual message
727 GST_handle_peer_get_config (void *cls, struct GNUNET_SERVER_Client *client,
728 const struct GNUNET_MessageHeader *message);
732 * Handler for GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS messages
735 * @param client identification of the client
736 * @param message the actual message
739 GST_handle_shutdown_peers (void *cls, struct GNUNET_SERVER_Client *client,
740 const struct GNUNET_MessageHeader *message);
744 * Handler for GNUNET_TESTBED_ManagePeerServiceMessage message
747 * @param client identification of client
748 * @param message the actual message
751 GST_handle_manage_peer_service (void *cls, struct GNUNET_SERVER_Client *client,
752 const struct GNUNET_MessageHeader *message);
756 * Frees the ManageServiceContext queue
763 * Cleans up the queue used for forwarding link controllers requests
770 * Cleans up the route list
773 GST_route_list_clear ();
777 * Processes a forwarded overlay connect context in the queue of the given RegisteredHostContext
779 * @param rhc the RegisteredHostContext
782 GST_process_next_focc (struct RegisteredHostContext *rhc);
786 * Cleans up ForwardedOverlayConnectContext
788 * @param focc the ForwardedOverlayConnectContext to cleanup
791 GST_cleanup_focc (struct ForwardedOverlayConnectContext *focc);
795 * Clears all pending overlay connect contexts in queue
802 * Clears all pending remote overlay connect contexts in queue
809 * Initializes the cache
811 * @param size the size of the cache
814 GST_cache_init (unsigned int size);
825 * Looks up in the hello cache and returns the HELLO of the given peer
827 * @param peer_id the index of the peer whose HELLO has to be looked up
828 * @return the HELLO message; NULL if not found
830 const struct GNUNET_MessageHeader *
831 GST_cache_lookup_hello (const unsigned int peer_id);
835 * Caches the HELLO of the given peer. Updates the HELLO if it was already
838 * @param peer_id the peer identity of the peer whose HELLO has to be cached
839 * @param hello the HELLO message
842 GST_cache_add_hello (const unsigned int peer_id,
843 const struct GNUNET_MessageHeader *hello);
847 * Functions of this type are called when the needed handle is available for
848 * usage. These functions are to be registered with either of the functions
849 * GST_cache_get_handle_transport() or GST_cache_get_handle_core(). The
850 * corresponding handles will be set and if they are not, then it signals an
851 * error while opening the handles.
853 * @param cls the closure passed to GST_cache_get_handle_transport() or
854 * GST_cache_get_handle_core()
855 * @param ch the handle to CORE. Can be NULL if it is not requested
856 * @param th the handle to TRANSPORT. Can be NULL if it is not requested
857 * @param peer_id the identity of the peer. Will be NULL if ch is NULL. In other
858 * cases, its value being NULL means that CORE connection has failed.
860 typedef void (*GST_cache_handle_ready_cb) (void *cls,
861 struct GNUNET_CORE_Handle * ch,
862 struct GNUNET_TRANSPORT_Handle * th,
863 const struct GNUNET_PeerIdentity *
868 * Callback to notify when the target peer given to
869 * GST_cache_get_handle_transport() is connected. Note that this callback may
870 * not be called if the target peer is already connected. Use
871 * GNUNET_TRANSPORT_check_neighbour_connected() to check if the target peer is
872 * already connected or not. This callback will be called only once or never (in
873 * case the target cannot be connected).
875 * @param cls the closure given to GST_cache_get_handle_done() for this callback
876 * @param target the peer identity of the target peer. The pointer should be
877 * valid until GST_cache_get_handle_done() is called.
879 typedef void (*GST_cache_peer_connect_notify) (void *cls,
880 const struct GNUNET_PeerIdentity
885 * Get a transport handle with the given configuration. If the handle is already
886 * cached before, it will be retured in the given callback; the peer_id is used to lookup in the
887 * cache. If not a new operation is started to open the transport handle and
888 * will be given in the callback when it is available.
890 * @param peer_id the index of the peer
891 * @param cfg the configuration with which the transport handle has to be
892 * created if it was not present in the cache
893 * @param cb the callback to notify when the transport handle is available
894 * @param cb_cls the closure for the above callback
895 * @param target the peer identify of the peer whose connection to our TRANSPORT
896 * subsystem will be notified through the connect_notify_cb. Can be NULL
897 * @param connect_notify_cb the callback to call when the given target peer is
898 * connected. This callback will only be called once or never again (in
899 * case the target peer cannot be connected). Can be NULL
900 * @param connect_notify_cb_cls the closure for the above callback
901 * @return the handle which can be used cancel or mark that the handle is no
904 struct GSTCacheGetHandle *
905 GST_cache_get_handle_transport (unsigned int peer_id,
906 const struct GNUNET_CONFIGURATION_Handle *cfg,
907 GST_cache_handle_ready_cb cb, void *cb_cls,
908 const struct GNUNET_PeerIdentity *target,
909 GST_cache_peer_connect_notify connect_notify_cb,
910 void *connect_notify_cb_cls);
914 * Get a CORE handle with the given configuration. If the handle is already
915 * cached before, it will be retured in the given callback; the peer_id is used
916 * to lookup in the cache. If the handle is not cached before, a new operation
917 * is started to open the CORE handle and will be given in the callback when it
918 * is available along with the peer identity
920 * @param peer_id the index of the peer
921 * @param cfg the configuration with which the transport handle has to be
922 * created if it was not present in the cache
923 * @param cb the callback to notify when the transport handle is available
924 * @param cb_cls the closure for the above callback
925 * @param target the peer identify of the peer whose connection to our CORE
926 * subsystem will be notified through the connect_notify_cb. Can be NULL
927 * @param connect_notify_cb the callback to call when the given target peer is
928 * connected. This callback will only be called once or never again (in
929 * case the target peer cannot be connected). Can be NULL
930 * @param connect_notify_cb_cls the closure for the above callback
931 * @return the handle which can be used cancel or mark that the handle is no
934 struct GSTCacheGetHandle *
935 GST_cache_get_handle_core (unsigned int peer_id,
936 const struct GNUNET_CONFIGURATION_Handle *cfg,
937 GST_cache_handle_ready_cb cb, void *cb_cls,
938 const struct GNUNET_PeerIdentity *target,
939 GST_cache_peer_connect_notify connect_notify_cb,
940 void *connect_notify_cb_cls);
944 * Mark the GetCacheHandle as being done if a handle has been provided already
945 * or as being cancelled if the callback for the handle hasn't been called.
947 * @param cgh the CacheGetHandle handle
950 GST_cache_get_handle_done (struct GSTCacheGetHandle *cgh);
954 * Initialize logging CPU and IO statisticfs. Checks the configuration for
955 * "STATS_DIR" and logs to a file in that directory. The file is name is
956 * generated from the hostname and the process's PID.
959 GST_stats_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
963 * Shutdown the status calls module.
966 GST_stats_destroy ();
968 /* End of gnunet-service-testbed.h */