paragraph for gnunet devs that don't know how to use the web
[oweals/gnunet.git] / src / testbed / gnunet-service-testbed.h
1 /*
2   This file is part of GNUnet.
3   Copyright (C) 2008--2013 GNUnet e.V.
4
5   GNUnet is free software: you can redistribute it and/or modify it
6   under the terms of the GNU Affero General Public License as published
7   by the Free Software Foundation, either version 3 of the License,
8   or (at your option) any later version.
9
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   Affero General Public License for more details.
14  
15   You should have received a copy of the GNU Affero General Public License
16   along with this program.  If not, see <http://www.gnu.org/licenses/>.
17 */
18
19 /**
20  * @file testbed/gnunet-service-testbed.h
21  * @brief data structures shared amongst components of TESTBED service
22  * @author Sree Harsha Totakura
23  */
24
25 #include "platform.h"
26 #include "gnunet_util_lib.h"
27 #include "gnunet_testbed_service.h"
28 #include "gnunet_transport_service.h"
29 #include "gnunet_core_service.h"
30
31 #include "testbed.h"
32 #include "testbed_api.h"
33 #include "testbed_api_operations.h"
34 #include "testbed_api_hosts.h"
35 #include "gnunet_testing_lib.h"
36 #include "gnunet-service-testbed_links.h"
37
38
39 /**
40  * Generic logging
41  */
42 #define LOG(kind,...)                           \
43   GNUNET_log (kind, __VA_ARGS__)
44
45 /**
46  * Debug logging
47  */
48 #define LOG_DEBUG(...)                          \
49   LOG (GNUNET_ERROR_TYPE_DEBUG, __VA_ARGS__)
50
51 /**
52  * By how much should the arrays lists grow
53  */
54 #define LIST_GROW_STEP 10
55
56
57 /**
58  * A routing entry
59  */
60 struct Route
61 {
62   /**
63    * destination host
64    */
65   uint32_t dest;
66
67   /**
68    * The destination host is reachable thru
69    */
70   uint32_t thru;
71 };
72
73
74 /**
75  * Context information for operations forwarded to subcontrollers
76  */
77 struct ForwardedOperationContext
78 {
79   /**
80    * The next pointer for DLL
81    */
82   struct ForwardedOperationContext *next;
83
84   /**
85    * The prev pointer for DLL
86    */
87   struct ForwardedOperationContext *prev;
88
89   /**
90    * The generated operation context
91    */
92   struct OperationContext *opc;
93
94   /**
95    * The client to which we have to reply
96    */
97   struct GNUNET_SERVICE_Client *client;
98
99   /**
100    * Closure pointer
101    */
102   void *cls;
103
104   /**
105    * Task ID for the timeout task
106    */
107   struct GNUNET_SCHEDULER_Task * timeout_task;
108
109   /**
110    * The id of the operation that has been forwarded
111    */
112   uint64_t operation_id;
113
114   /**
115    * The type of the operation which is forwarded
116    */
117   enum OperationType type;
118
119 };
120
121
122 /**
123  * A DLL of host registrations to be made
124  */
125 struct HostRegistration
126 {
127   /**
128    * next registration in the DLL
129    */
130   struct HostRegistration *next;
131
132   /**
133    * previous registration in the DLL
134    */
135   struct HostRegistration *prev;
136
137   /**
138    * The callback to call after this registration's status is available
139    */
140   GNUNET_TESTBED_HostRegistrationCompletion cb;
141
142   /**
143    * The closure for the above callback
144    */
145   void *cb_cls;
146
147   /**
148    * The host that has to be registered
149    */
150   struct GNUNET_TESTBED_Host *host;
151 };
152
153
154 /**
155  * Context information used while linking controllers
156  */
157 struct LinkControllersContext
158 {
159   /**
160    * The client which initiated the link controller operation
161    */
162   struct GNUNET_SERVICE_Client *client;
163
164   /**
165    * The ID of the operation
166    */
167   uint64_t operation_id;
168
169 };
170
171
172 /**
173  * A peer
174  */
175 struct Peer
176 {
177
178   union
179   {
180     struct
181     {
182       /**
183        * The peer handle from testing API
184        */
185       struct GNUNET_TESTING_Peer *peer;
186
187       /**
188        * The modified (by GNUNET_TESTING_peer_configure) configuration this
189        * peer is configured with
190        */
191       struct GNUNET_CONFIGURATION_Handle *cfg;
192
193       /**
194        * Is the peer running
195        */
196       int is_running;
197
198     } local;
199
200     struct
201     {
202       /**
203        * The slave this peer is started through
204        */
205       struct Slave *slave;
206
207       /**
208        * The id of the remote host this peer is running on
209        */
210       uint32_t remote_host_id;
211
212     } remote;
213
214   } details;
215
216   /**
217    * Is this peer locally created?
218    */
219   int is_remote;
220
221   /**
222    * Our local reference id for this peer
223    */
224   uint32_t id;
225
226   /**
227    * References to peers are using in forwarded overlay contexts and remote
228    * overlay connect contexts. A peer can only be destroyed after all such
229    * contexts are destroyed. For this, we maintain a reference counter. When we
230    * use a peer in any such context, we increment this counter. We decrement it
231    * when we are destroying these contexts
232    */
233   uint32_t reference_cnt;
234
235   /**
236    * While destroying a peer, due to the fact that there could be references to
237    * this peer, we delay the peer destroy to a further time. We do this by using
238    * this flag to destroy the peer while destroying a context in which this peer
239    * has been used. When the flag is set to 1 and reference_cnt = 0 we destroy
240    * the peer
241    */
242   uint32_t destroy_flag;
243
244 };
245
246
247 /**
248  * The main context information associated with the client which started us
249  */
250 struct Context
251 {
252   /**
253    * The client handle associated with this context
254    */
255   struct GNUNET_SERVICE_Client *client;
256
257   /**
258    * The network address of the master controller
259    */
260   char *master_ip;
261
262   /**
263    * The TESTING system handle for starting peers locally
264    */
265   struct GNUNET_TESTING_System *system;
266
267   /**
268    * Our host id according to this context
269    */
270   uint32_t host_id;
271 };
272
273
274 /**
275  * The structure for identifying a shared service
276  */
277 struct SharedService
278 {
279   /**
280    * The name of the shared service
281    */
282   char *name;
283
284   /**
285    * Number of shared peers per instance of the shared service
286    */
287   uint32_t num_shared;
288
289   /**
290    * Number of peers currently sharing the service
291    */
292   uint32_t num_sharing;
293 };
294
295
296 struct RegisteredHostContext;
297
298
299 /**
300  * Context information to used during operations which forward the overlay
301  * connect message
302  */
303 struct ForwardedOverlayConnectContext
304 {
305   /**
306    * next ForwardedOverlayConnectContext in the DLL
307    */
308   struct ForwardedOverlayConnectContext *next;
309
310   /**
311    * previous ForwardedOverlayConnectContext in the DLL
312    */
313   struct ForwardedOverlayConnectContext *prev;
314
315   /**
316    * Which host does this FOCC belong to?
317    */
318   struct RegisteredHostContext *rhc;
319
320   /**
321    * A copy of the original overlay connect message
322    */
323   struct GNUNET_MessageHeader *orig_msg;
324
325   /**
326    * The client handle
327    */
328   struct GNUNET_SERVICE_Client *client;
329
330   /**
331    * The id of the operation which created this context information
332    */
333   uint64_t operation_id;
334
335   /**
336    * the id of peer 1
337    */
338   uint32_t peer1;
339
340   /**
341    * The id of peer 2
342    */
343   uint32_t peer2;
344
345   /**
346    * Id of the host where peer2 is running
347    */
348   uint32_t peer2_host_id;
349 };
350
351
352 /**
353  * This context information will be created for each host that is registered at
354  * slave controllers during overlay connects.
355  */
356 struct RegisteredHostContext
357 {
358   /**
359    * The host which is being registered
360    */
361   struct GNUNET_TESTBED_Host *reg_host;
362
363   /**
364    * The host of the controller which has to connect to the above rhost
365    */
366   struct GNUNET_TESTBED_Host *host;
367
368   /**
369    * Head of the ForwardedOverlayConnectContext DLL
370    */
371   struct ForwardedOverlayConnectContext *focc_dll_head;
372
373   /**
374    * Tail of the ForwardedOverlayConnectContext DLL
375    */
376   struct ForwardedOverlayConnectContext *focc_dll_tail;
377
378   /**
379    * Enumeration of states for this context
380    */
381   enum RHCState
382   {
383
384     /**
385      * The initial state
386      */
387     RHC_INIT = 0,
388
389     /**
390      * State where we attempt to do the overlay connection again
391      */
392     RHC_DONE
393   } state;
394
395 };
396
397
398 /**
399  * Context data for #GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS handler
400  */
401 struct HandlerContext_ShutdownPeers
402 {
403   /**
404    * The number of slave we expect to hear from since we forwarded the
405    * #GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS message to them
406    */
407   unsigned int nslaves;
408
409   /**
410    * Did we observe a timeout with respect to this operation at any of the
411    * slaves
412    */
413   int timeout;
414 };
415
416
417 /**
418  * Our configuration
419  */
420 extern struct GNUNET_CONFIGURATION_Handle *GST_config;
421
422 /**
423  * The master context; generated with the first INIT message
424  */
425 extern struct Context *GST_context;
426
427 /**
428  * DLL head for forwarded operation contexts
429  */
430 extern struct ForwardedOperationContext *fopcq_head;
431
432 /**
433  * DLL tail for forwarded operation contexts
434  */
435 extern struct ForwardedOperationContext *fopcq_tail;
436
437 /**
438  * A list of peers we know about
439  */
440 extern struct Peer **GST_peer_list;
441
442 /**
443  * Array of hosts
444  */
445 extern struct GNUNET_TESTBED_Host **GST_host_list;
446
447 /**
448  * Operation queue for open file descriptors
449  */
450 extern struct OperationQueue *GST_opq_openfds;
451
452 /**
453  * Timeout for operations which may take some time
454  */
455 const extern struct GNUNET_TIME_Relative GST_timeout;
456
457 /**
458  * The size of the peer list
459  */
460 extern unsigned int GST_peer_list_size;
461
462 /**
463  * The current number of peers running locally under this controller
464  */
465 extern unsigned int GST_num_local_peers;
466
467 /**
468  * The size of the host list
469  */
470 extern unsigned int GST_host_list_size;
471
472 /**
473  * The directory where to store load statistics data
474  */
475 extern char *GST_stats_dir;
476
477 /**
478  * Condition to check if host id is valid
479  */
480 #define VALID_HOST_ID(id) \
481   ( ((id) < GST_host_list_size) && (NULL != GST_host_list[id]) )
482
483 /**
484  * Condition to check if peer id is valid
485  */
486 #define VALID_PEER_ID(id) \
487   ( ((id) < GST_peer_list_size) && (NULL != GST_peer_list[id]) )
488
489
490 /**
491  * Similar to GNUNET_array_grow(); however instead of calling GNUNET_array_grow()
492  * several times we call it only once. The array is also made to grow in steps
493  * of LIST_GROW_STEP.
494  *
495  * @param ptr the array pointer to grow
496  * @param size the size of array
497  * @param accommodate_size the size which the array has to accommdate; after
498  *          this call the array will be big enough to accommdate sizes upto
499  *          accommodate_size
500  */
501 #define GST_array_grow_large_enough(ptr, size, accommodate_size) \
502   do                                                                    \
503   {                                                                     \
504     unsigned int growth_size;                                           \
505     GNUNET_assert (size <= accommodate_size);                            \
506     growth_size = size;                                                 \
507     while (growth_size <= accommodate_size)                             \
508       growth_size += LIST_GROW_STEP;                                    \
509     GNUNET_array_grow (ptr, size, growth_size);                         \
510     GNUNET_assert (size > accommodate_size);                            \
511   } while (0)
512
513
514 /**
515  * Function to destroy a peer
516  *
517  * @param peer the peer structure to destroy
518  */
519 void
520 GST_destroy_peer (struct Peer *peer);
521
522
523 /**
524  * Stops and destroys all peers
525  */
526 void
527 GST_destroy_peers (void);
528
529
530 /**
531  * Finds the route with directly connected host as destination through which
532  * the destination host can be reached
533  *
534  * @param host_id the id of the destination host
535  * @return the route with directly connected destination host; NULL if no route
536  *           is found
537  */
538 struct Route *
539 GST_find_dest_route (uint32_t host_id);
540
541
542 /**
543  * Handler for #GNUNET_MESSAGE_TYPE_TESTBED_OVERLAY_CONNECT messages
544  *
545  * @param cls identification of the client
546  * @param msg the actual message
547  */
548 void
549 handle_overlay_connect (void *cls,
550                         const struct GNUNET_TESTBED_OverlayConnectMessage *msg);
551
552
553 /**
554  * Adds a host registration's request to a slave's registration queue
555  *
556  * @param slave the slave controller at which the given host has to be
557  *          registered
558  * @param cb the host registration completion callback
559  * @param cb_cls the closure for the host registration completion callback
560  * @param host the host which has to be registered
561  */
562 void
563 GST_queue_host_registration (struct Slave *slave,
564                              GNUNET_TESTBED_HostRegistrationCompletion cb,
565                              void *cb_cls, struct GNUNET_TESTBED_Host *host);
566
567
568 /**
569  * Callback to relay the reply msg of a forwarded operation back to the client
570  *
571  * @param cls ForwardedOperationContext
572  * @param msg the message to relay
573  */
574 void
575 GST_forwarded_operation_reply_relay (void *cls,
576                                      const struct GNUNET_MessageHeader *msg);
577
578
579 /**
580  * Task to free resources when forwarded operation has been timedout
581  *
582  * @param cls the ForwardedOperationContext
583  * @param tc the task context from scheduler
584  */
585 void
586 GST_forwarded_operation_timeout (void *cls);
587
588
589 /**
590  * Clears the forwarded operations queue
591  */
592 void
593 GST_clear_fopcq (void);
594
595
596 /**
597  * Send operation failure message to client
598  *
599  * @param client the client to which the failure message has to be sent to
600  * @param operation_id the id of the failed operation
601  * @param emsg the error message; can be NULL
602  */
603 void
604 GST_send_operation_fail_msg (struct GNUNET_SERVICE_Client *client,
605                              uint64_t operation_id,
606                              const char *emsg);
607
608
609 /**
610  * Notify OC subsystem that @a client disconnected.
611  *
612  * @param client the client that disconnected
613  */
614 void
615 GST_notify_client_disconnect_oc (struct GNUNET_SERVICE_Client *client);
616
617
618 /**
619  * Notify peers subsystem that @a client disconnected.
620  *
621  * @param client the client that disconnected
622  */
623 void
624 GST_notify_client_disconnect_peers (struct GNUNET_SERVICE_Client *client);
625
626
627 /**
628  * Function to send generic operation success message to given client
629  *
630  * @param client the client to send the message to
631  * @param operation_id the id of the operation which was successful
632  */
633 void
634 GST_send_operation_success_msg (struct GNUNET_SERVICE_Client *client,
635                                 uint64_t operation_id);
636
637
638 /**
639  * Check #GNUNET_MESSAGE_TYPE_TESTBED_REMOTE_OVERLAY_CONNECT messages
640  *
641  * @param cls identification of the client
642  * @param msg the actual message
643  * @return #GNUNET_OK if @a msg is well-formed
644  */
645 int
646 check_remote_overlay_connect (void *cls,
647                               const struct GNUNET_TESTBED_RemoteOverlayConnectMessage *msg);
648
649
650 /**
651  * Handler for #GNUNET_MESSAGE_TYPE_TESTBED_REMOTE_OVERLAY_CONNECT messages
652  *
653  * @param cls identification of the client
654  * @param msg the actual message
655  */
656 void
657 handle_remote_overlay_connect (void *cls,
658                                const struct GNUNET_TESTBED_RemoteOverlayConnectMessage *msg);
659
660
661 /**
662  * Check #GNUNET_MESSAGE_TYPE_TESTBED_CREATEPEER messages
663  *
664  * @param cls identification of the client
665  * @param msg the actual message
666  * @return #GNUNET_OK if @a msg is well-formed
667  */
668 int
669 check_peer_create (void *cls,
670                    const struct GNUNET_TESTBED_PeerCreateMessage *msg);
671
672
673 /**
674  * Handler for #GNUNET_MESSAGE_TYPE_TESTBED_CREATEPEER messages
675  *
676  * @param cls identification of the client
677  * @param message the actual message
678  */
679 void
680 handle_peer_create (void *cls,
681                     const struct GNUNET_TESTBED_PeerCreateMessage *msg);
682
683
684 /**
685  * Message handler for #GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
686  *
687  * @param cls identification of the client
688  * @param msg the actual message
689  */
690 void
691 handle_peer_destroy (void *cls,
692                      const struct GNUNET_TESTBED_PeerDestroyMessage *msg);
693
694
695 /**
696  * Message handler for #GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
697  *
698  * @param cls identification of the client
699  * @param msg the actual message
700  */
701 void
702 handle_peer_start (void *cls,
703                    const struct GNUNET_TESTBED_PeerStartMessage *msg);
704
705
706 /**
707  * Message handler for #GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
708  *
709  * @param cls identification of the client
710  * @param message the actual message
711  */
712 void
713 handle_peer_stop (void *cls,
714                   const struct GNUNET_TESTBED_PeerStopMessage *msg);
715
716
717 /**
718  * Handler for #GNUNET_MESSAGE_TYPE_TESTBED_GETPEERCONFIG messages
719  *
720  * @param cls identification of the client
721  * @param msg the actual message
722  */
723 void
724 handle_peer_get_config (void *cls,
725                         const struct GNUNET_TESTBED_PeerGetConfigurationMessage *msg);
726
727
728 /**
729  * Handler for #GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS messages
730  *
731  * @param cls identification of the client
732  * @param msg the actual message
733  */
734 void
735 handle_shutdown_peers (void *cls,
736                        const struct GNUNET_TESTBED_ShutdownPeersMessage *msg);
737
738
739 /**
740  * Check #GNUNET_MESSAGE_TYPE_TESTBED_MANAGE_PEER_SERVICE message
741  *
742  * @param cls identification of client
743  * @param msg the actual message
744  * @return #GNUNET_OK if @a msg is well-formed
745  */
746 int
747 check_manage_peer_service (void *cls,
748                            const struct GNUNET_TESTBED_ManagePeerServiceMessage *msg);
749
750
751 /**
752  * Handler for #GNUNET_MESSAGE_TYPE_TESTBED_MANAGE_PEER_SERVICE message
753  *
754  * @param cls identification of client
755  * @param msg the actual message
756  */
757 void
758 handle_manage_peer_service (void *cls,
759                             const struct GNUNET_TESTBED_ManagePeerServiceMessage *msg);
760
761
762
763
764 /**
765  * Check #GNUNET_MESSAGE_TYPDE_TESTBED_RECONFIGURE_PEER type messages.
766  *
767  * @param cls identification of the client
768  * @param msg the actual message
769  * @return #GNUNET_OK if @a msg is well-formed
770  */
771 int
772 check_peer_reconfigure (void *cls,
773                         const struct GNUNET_TESTBED_PeerReconfigureMessage *msg);
774
775
776 /**
777  * Handler for #GNUNET_MESSAGE_TYPDE_TESTBED_RECONFIGURE_PEER type messages.
778  * Should stop the peer asyncronously, destroy it and create it again with the
779  * new configuration.
780  *
781  * @param cls identification of the client
782  * @param msg the actual message
783  */
784 void
785 handle_peer_reconfigure (void *cls,
786                          const struct GNUNET_TESTBED_PeerReconfigureMessage *msg);
787
788
789 /**
790  * Frees the ManageServiceContext queue
791  */
792 void
793 GST_free_mctxq (void);
794
795
796 /**
797  * Cleans up the queue used for forwarding link controllers requests
798  */
799 void
800 GST_free_lcf (void);
801
802
803 /**
804  * Cleans up the route list
805  */
806 void
807 GST_route_list_clear (void);
808
809
810 /**
811  * Processes a forwarded overlay connect context in the queue of the given RegisteredHostContext
812  *
813  * @param rhc the RegisteredHostContext
814  */
815 void
816 GST_process_next_focc (struct RegisteredHostContext *rhc);
817
818
819 /**
820  * Cleans up ForwardedOverlayConnectContext
821  *
822  * @param focc the ForwardedOverlayConnectContext to cleanup
823  */
824 void
825 GST_cleanup_focc (struct ForwardedOverlayConnectContext *focc);
826
827
828 /**
829  * Clears all pending overlay connect contexts in queue
830  */
831 void
832 GST_free_occq (void);
833
834
835 /**
836  * Clears all pending remote overlay connect contexts in queue
837  */
838 void
839 GST_free_roccq (void);
840
841
842 /**
843  * Cleans up the Peer reconfigure context list
844  */
845 void
846 GST_free_prcq (void);
847
848
849 /**
850  * Initializes the cache
851  *
852  * @param size the size of the cache
853  */
854 void
855 GST_cache_init (unsigned int size);
856
857
858 /**
859  * Clear cache
860  */
861 void
862 GST_cache_clear (void);
863
864
865 /**
866  * Looks up in the hello cache and returns the HELLO of the given peer
867  *
868  * @param peer_id the index of the peer whose HELLO has to be looked up
869  * @return the HELLO message; NULL if not found
870  */
871 const struct GNUNET_MessageHeader *
872 GST_cache_lookup_hello (const unsigned int peer_id);
873
874
875 /**
876  * Caches the HELLO of the given peer. Updates the HELLO if it was already
877  * cached before
878  *
879  * @param peer_id the peer identity of the peer whose HELLO has to be cached
880  * @param hello the HELLO message
881  */
882 void
883 GST_cache_add_hello (const unsigned int peer_id,
884                      const struct GNUNET_MessageHeader *hello);
885
886
887 /**
888  * Initialize logging CPU and IO statisticfs.  Checks the configuration for
889  * "STATS_DIR" and logs to a file in that directory.  The file is name is
890  * generated from the hostname and the process's PID.
891  */
892 void
893 GST_stats_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
894
895
896 /**
897  * Shutdown the status calls module.
898  */
899 void
900 GST_stats_destroy (void);
901
902 /* End of gnunet-service-testbed.h */