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