src/testbed/gnunet-service-testbed.h

   1 /*
   2   This file is part of GNUnet.
   3   (C) 2008--2013 Christian Grothoff (and other contributing authors)
   4
   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.
   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   General Public License for more details.
  14
  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.
  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_SERVER_Client *client;
 100
 101   /**
 102    * Closure pointer
 103    */
 104   void *cls;
 105
 106   /**
 107    * Task ID for the timeout task
 108    */
 109   GNUNET_SCHEDULER_TaskIdentifier 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 /**
 125  * A DLL of host registrations to be made
 126  */
 127 struct HostRegistration
 128 {
 129   /**
 130    * next registration in the DLL
 131    */
 132   struct HostRegistration *next;
 133
 134   /**
 135    * previous registration in the DLL
 136    */
 137   struct HostRegistration *prev;
 138
 139   /**
 140    * The callback to call after this registration's status is available
 141    */
 142   GNUNET_TESTBED_HostRegistrationCompletion cb;
 143
 144   /**
 145    * The closure for the above callback
 146    */
 147   void *cb_cls;
 148
 149   /**
 150    * The host that has to be registered
 151    */
 152   struct GNUNET_TESTBED_Host *host;
 153 };
 154
 155
 156 /**
 157  * Context information used while linking controllers
 158  */
 159 struct LinkControllersContext
 160 {
 161   /**
 162    * The client which initiated the link controller operation
 163    */
 164   struct GNUNET_SERVER_Client *client;
 165
 166   /**
 167    * The ID of the operation
 168    */
 169   uint64_t operation_id;
 170
 171 };
 172
 173
 174 /**
 175  * A peer
 176  */
 177
 178 struct Peer
 179 {
 180
 181   union
 182   {
 183     struct
 184     {
 185       /**
 186        * The peer handle from testing API
 187        */
 188       struct GNUNET_TESTING_Peer *peer;
 189
 190       /**
 191        * The modified (by GNUNET_TESTING_peer_configure) configuration this
 192        * peer is configured with
 193        */
 194       struct GNUNET_CONFIGURATION_Handle *cfg;
 195
 196       /**
 197        * Is the peer running
 198        */
 199       int is_running;
 200
 201     } local;
 202
 203     struct
 204     {
 205       /**
 206        * The slave this peer is started through
 207        */
 208       struct Slave *slave;
 209
 210       /**
 211        * The id of the remote host this peer is running on
 212        */
 213       uint32_t remote_host_id;
 214
 215     } remote;
 216
 217   } details;
 218
 219   /**
 220    * Is this peer locally created?
 221    */
 222   int is_remote;
 223
 224   /**
 225    * Our local reference id for this peer
 226    */
 227   uint32_t id;
 228
 229   /**
 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
 235    */
 236   uint32_t reference_cnt;
 237
 238   /**
 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
 243    * the peer
 244    */
 245   uint32_t destroy_flag;
 246
 247 };
 248
 249
 250 /**
 251  * The main context information associated with the client which started us
 252  */
 253 struct Context
 254 {
 255   /**
 256    * The client handle associated with this context
 257    */
 258   struct GNUNET_SERVER_Client *client;
 259
 260   /**
 261    * The network address of the master controller
 262    */
 263   char *master_ip;
 264
 265   /**
 266    * The TESTING system handle for starting peers locally
 267    */
 268   struct GNUNET_TESTING_System *system;
 269
 270   /**
 271    * Our host id according to this context
 272    */
 273   uint32_t host_id;
 274 };
 275
 276
 277 /**
 278  * The structure for identifying a shared service
 279  */
 280 struct SharedService
 281 {
 282   /**
 283    * The name of the shared service
 284    */
 285   char *name;
 286
 287   /**
 288    * Number of shared peers per instance of the shared service
 289    */
 290   uint32_t num_shared;
 291
 292   /**
 293    * Number of peers currently sharing the service
 294    */
 295   uint32_t num_sharing;
 296 };
 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    * A copy of the original overlay connect message
 317    */
 318   struct GNUNET_MessageHeader *orig_msg;
 319
 320   /**
 321    * The id of the operation which created this context information
 322    */
 323   uint64_t operation_id;
 324
 325   /**
 326    * the id of peer 1
 327    */
 328   uint32_t peer1;
 329
 330   /**
 331    * The id of peer 2
 332    */
 333   uint32_t peer2;
 334
 335   /**
 336    * Id of the host where peer2 is running
 337    */
 338   uint32_t peer2_host_id;
 339 };
 340
 341
 342 /**
 343  * The type for data structures which commonly arrive at the slave_event_callback
 344  */
 345 enum ClosureType
 346 {
 347   /**
 348    * Type for RegisteredHostContext closures
 349    */
 350   CLOSURE_TYPE_RHC = 1,
 351
 352   /**
 353    * Type for LinkControllersForwardingContext closures
 354    */
 355   CLOSURE_TYPE_LCF
 356 };
 357
 358
 359 /**
 360  * This context information will be created for each host that is registered at
 361  * slave controllers during overlay connects.
 362  */
 363 struct RegisteredHostContext
 364 {
 365   /**
 366    * The type of this data structure. Set this to CLOSURE_TYPE_RHC
 367    */
 368   enum ClosureType type;
 369
 370   /**
 371    * The host which is being registered
 372    */
 373   struct GNUNET_TESTBED_Host *reg_host;
 374
 375   /**
 376    * The host of the controller which has to connect to the above rhost
 377    */
 378   struct GNUNET_TESTBED_Host *host;
 379
 380   /**
 381    * The gateway to which this operation is forwarded to
 382    */
 383   struct Slave *gateway;
 384
 385   /**
 386    * The gateway through which peer2's controller can be reached
 387    */
 388   struct Slave *gateway2;
 389
 390   /**
 391    * Handle for sub-operations
 392    */
 393   struct GNUNET_TESTBED_Operation *sub_op;
 394
 395   /**
 396    * The client which initiated the link controller operation
 397    */
 398   struct GNUNET_SERVER_Client *client;
 399
 400   /**
 401    * Head of the ForwardedOverlayConnectContext DLL
 402    */
 403   struct ForwardedOverlayConnectContext *focc_dll_head;
 404
 405   /**
 406    * Tail of the ForwardedOverlayConnectContext DLL
 407    */
 408   struct ForwardedOverlayConnectContext *focc_dll_tail;
 409
 410   /**
 411    * Enumeration of states for this context
 412    */
 413   enum RHCState
 414   {
 415
 416     /**
 417      * The initial state
 418      */
 419     RHC_INIT = 0,
 420
 421     /**
 422      * State where we attempt to get peer2's controller configuration
 423      */
 424     RHC_GET_CFG,
 425
 426     /**
 427      * State where we attempt to link the controller of peer 1 to the controller
 428      * of peer2
 429      */
 430     RHC_LINK,
 431
 432     /**
 433      * State where we attempt to do the overlay connection again
 434      */
 435     RHC_OL_CONNECT
 436   } state;
 437
 438 };
 439
 440
 441 /**
 442  * Context data for GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS handler
 443  */
 444 struct HandlerContext_ShutdownPeers
 445 {
 446   /**
 447    * The number of slave we expect to hear from since we forwarded the
 448    * GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS message to them
 449    */
 450   unsigned int nslaves;
 451
 452   /**
 453    * Did we observe a timeout with respect to this operation at any of the
 454    * slaves
 455    */
 456   int timeout;
 457 };
 458
 459
 460 /**
 461  * Our configuration
 462  */
 463 struct GNUNET_CONFIGURATION_Handle *our_config;
 464
 465 /**
 466  * The master context; generated with the first INIT message
 467  */
 468 extern struct Context *GST_context;
 469
 470 /**
 471  * DLL head for forwarded operation contexts
 472  */
 473 extern struct ForwardedOperationContext *fopcq_head;
 474
 475 /**
 476  * DLL tail for forwarded operation contexts
 477  */
 478 extern struct ForwardedOperationContext *fopcq_tail;
 479
 480 /**
 481  * A list of peers we know about
 482  */
 483 extern struct Peer **GST_peer_list;
 484
 485 /**
 486  * Array of hosts
 487  */
 488 extern struct GNUNET_TESTBED_Host **GST_host_list;
 489
 490 /**
 491  * Operation queue for open file descriptors
 492  */
 493 extern struct OperationQueue *GST_opq_openfds;
 494
 495 /**
 496  * Timeout for operations which may take some time
 497  */
 498 const extern struct GNUNET_TIME_Relative GST_timeout;
 499
 500 /**
 501  * The size of the peer list
 502  */
 503 extern unsigned int GST_peer_list_size;
 504
 505 /**
 506  * The size of the host list
 507  */
 508 extern unsigned int GST_host_list_size;
 509
 510 /**
 511  * The directory where to store load statistics data
 512  */
 513 extern char *GST_stats_dir;
 514
 515
 516 /**
 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
 519  * of LIST_GROW_STEP.
 520  *
 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
 525  *          accommodate_size
 526  */
 527 #define GST_array_grow_large_enough(ptr, size, accommodate_size) \
 528   do                                                                    \
 529   {                                                                     \
 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);                            \
 537   } while (0)
 538
 539
 540 /**
 541  * Queues a message in send queue for sending to the service
 542  *
 543  * @param client the client to whom the queued message has to be sent
 544  * @param msg the message to queue
 545  */
 546 void
 547 GST_queue_message (struct GNUNET_SERVER_Client *client,
 548                    struct GNUNET_MessageHeader *msg);
 549
 550
 551 /**
 552  * Function to destroy a peer
 553  *
 554  * @param peer the peer structure to destroy
 555  */
 556 void
 557 GST_destroy_peer (struct Peer *peer);
 558
 559
 560 /**
 561  * Stops and destroys all peers
 562  */
 563 void
 564 GST_destroy_peers ();
 565
 566
 567 /**
 568  * Finds the route with directly connected host as destination through which
 569  * the destination host can be reached
 570  *
 571  * @param host_id the id of the destination host
 572  * @return the route with directly connected destination host; NULL if no route
 573  *           is found
 574  */
 575 struct Route *
 576 GST_find_dest_route (uint32_t host_id);
 577
 578
 579 /**
 580  * Handler for GNUNET_MESSAGE_TYPE_TESTBED_OLCONNECT messages
 581  *
 582  * @param cls NULL
 583  * @param client identification of the client
 584  * @param message the actual message
 585  */
 586 void
 587 GST_handle_overlay_connect (void *cls, struct GNUNET_SERVER_Client *client,
 588                             const struct GNUNET_MessageHeader *message);
 589
 590
 591 /**
 592  * Adds a host registration's request to a slave's registration queue
 593  *
 594  * @param slave the slave controller at which the given host has to be
 595  *          registered
 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
 599  */
 600 void
 601 GST_queue_host_registration (struct Slave *slave,
 602                              GNUNET_TESTBED_HostRegistrationCompletion cb,
 603                              void *cb_cls, struct GNUNET_TESTBED_Host *host);
 604
 605
 606 /**
 607  * Callback to relay the reply msg of a forwarded operation back to the client
 608  *
 609  * @param cls ForwardedOperationContext
 610  * @param msg the message to relay
 611  */
 612 void
 613 GST_forwarded_operation_reply_relay (void *cls,
 614                                      const struct GNUNET_MessageHeader *msg);
 615
 616
 617 /**
 618  * Task to free resources when forwarded operation has been timedout
 619  *
 620  * @param cls the ForwardedOperationContext
 621  * @param tc the task context from scheduler
 622  */
 623 void
 624 GST_forwarded_operation_timeout (void *cls,
 625                                  const struct GNUNET_SCHEDULER_TaskContext *tc);
 626
 627
 628 /**
 629  * Clears the forwarded operations queue
 630  */
 631 void
 632 GST_clear_fopcq ();
 633
 634
 635 /**
 636  * Send operation failure message to client
 637  *
 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
 641  */
 642 void
 643 GST_send_operation_fail_msg (struct GNUNET_SERVER_Client *client,
 644                              uint64_t operation_id, const char *emsg);
 645
 646
 647 /**
 648  * Function to send generic operation success message to given client
 649  *
 650  * @param client the client to send the message to
 651  * @param operation_id the id of the operation which was successful
 652  */
 653 void
 654 GST_send_operation_success_msg (struct GNUNET_SERVER_Client *client,
 655                                 uint64_t operation_id);
 656
 657
 658 /**
 659  * Handler for GNUNET_MESSAGE_TYPE_TESTBED_REQUESTCONNECT messages
 660  *
 661  * @param cls NULL
 662  * @param client identification of the client
 663  * @param message the actual message
 664  */
 665 void
 666 GST_handle_remote_overlay_connect (void *cls,
 667                                    struct GNUNET_SERVER_Client *client,
 668                                    const struct GNUNET_MessageHeader *message);
 669
 670
 671 /**
 672  * Handler for GNUNET_MESSAGE_TYPE_TESTBED_CREATEPEER messages
 673  *
 674  * @param cls NULL
 675  * @param client identification of the client
 676  * @param message the actual message
 677  */
 678 void
 679 GST_handle_peer_create (void *cls, struct GNUNET_SERVER_Client *client,
 680                         const struct GNUNET_MessageHeader *message);
 681
 682
 683 /**
 684  * Message handler for GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
 685  *
 686  * @param cls NULL
 687  * @param client identification of the client
 688  * @param message the actual message
 689  */
 690 void
 691 GST_handle_peer_destroy (void *cls, struct GNUNET_SERVER_Client *client,
 692                          const struct GNUNET_MessageHeader *message);
 693
 694
 695 /**
 696  * Message handler for GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
 697  *
 698  * @param cls NULL
 699  * @param client identification of the client
 700  * @param message the actual message
 701  */
 702 void
 703 GST_handle_peer_start (void *cls, struct GNUNET_SERVER_Client *client,
 704                        const struct GNUNET_MessageHeader *message);
 705
 706
 707 /**
 708  * Message handler for GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER messages
 709  *
 710  * @param cls NULL
 711  * @param client identification of the client
 712  * @param message the actual message
 713  */
 714 void
 715 GST_handle_peer_stop (void *cls, struct GNUNET_SERVER_Client *client,
 716                       const struct GNUNET_MessageHeader *message);
 717
 718
 719 /**
 720  * Handler for GNUNET_MESSAGE_TYPE_TESTBED_GETPEERCONFIG messages
 721  *
 722  * @param cls NULL
 723  * @param client identification of the client
 724  * @param message the actual message
 725  */
 726 void
 727 GST_handle_peer_get_config (void *cls, struct GNUNET_SERVER_Client *client,
 728                             const struct GNUNET_MessageHeader *message);
 729
 730
 731 /**
 732  * Handler for GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS messages
 733  *
 734  * @param cls NULL
 735  * @param client identification of the client
 736  * @param message the actual message
 737  */
 738 void
 739 GST_handle_shutdown_peers (void *cls, struct GNUNET_SERVER_Client *client,
 740                            const struct GNUNET_MessageHeader *message);
 741
 742
 743 /**
 744  * Handler for GNUNET_TESTBED_ManagePeerServiceMessage message
 745  *
 746  * @param cls NULL
 747  * @param client identification of client
 748  * @param message the actual message
 749  */
 750 void
 751 GST_handle_manage_peer_service (void *cls, struct GNUNET_SERVER_Client *client,
 752                                 const struct GNUNET_MessageHeader *message);
 753
 754
 755 /**
 756  * Frees the ManageServiceContext queue
 757  */
 758 void
 759 GST_free_mctxq ();
 760
 761
 762 /**
 763  * Cleans up the queue used for forwarding link controllers requests
 764  */
 765 void
 766 GST_free_lcfq ();
 767
 768
 769 /**
 770  * Cleans up the route list
 771  */
 772 void
 773 GST_route_list_clear ();
 774
 775
 776 /**
 777  * Processes a forwarded overlay connect context in the queue of the given RegisteredHostContext
 778  *
 779  * @param rhc the RegisteredHostContext
 780  */
 781 void
 782 GST_process_next_focc (struct RegisteredHostContext *rhc);
 783
 784
 785 /**
 786  * Cleans up ForwardedOverlayConnectContext
 787  *
 788  * @param focc the ForwardedOverlayConnectContext to cleanup
 789  */
 790 void
 791 GST_cleanup_focc (struct ForwardedOverlayConnectContext *focc);
 792
 793
 794 /**
 795  * Clears all pending overlay connect contexts in queue
 796  */
 797 void
 798 GST_free_occq ();
 799
 800
 801 /**
 802  * Clears all pending remote overlay connect contexts in queue
 803  */
 804 void
 805 GST_free_roccq ();
 806
 807
 808 /**
 809  * Initializes the cache
 810  *
 811  * @param size the size of the cache
 812  */
 813 void
 814 GST_cache_init (unsigned int size);
 815
 816
 817 /**
 818  * Clear cache
 819  */
 820 void
 821 GST_cache_clear ();
 822
 823
 824 /**
 825  * Looks up in the hello cache and returns the HELLO of the given peer
 826  *
 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
 829  */
 830 const struct GNUNET_MessageHeader *
 831 GST_cache_lookup_hello (const unsigned int peer_id);
 832
 833
 834 /**
 835  * Caches the HELLO of the given peer. Updates the HELLO if it was already
 836  * cached before
 837  *
 838  * @param peer_id the peer identity of the peer whose HELLO has to be cached
 839  * @param hello the HELLO message
 840  */
 841 void
 842 GST_cache_add_hello (const unsigned int peer_id,
 843                      const struct GNUNET_MessageHeader *hello);
 844
 845
 846 /**
 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.
 852  *
 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.
 859  */
 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 *
 864                                            peer_id);
 865
 866
 867 /**
 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).
 874  *
 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.
 878  */
 879 typedef void (*GST_cache_peer_connect_notify) (void *cls,
 880                                                const struct GNUNET_PeerIdentity
 881                                                * target);
 882
 883
 884 /**
 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.
 889  *
 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
 902  *           longer being used
 903  */
 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);
 911
 912
 913 /**
 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
 919  *
 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
 932  *           longer being used
 933  */
 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);
 941
 942
 943 /**
 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.
 946  *
 947  * @param cgh the CacheGetHandle handle
 948  */
 949 void
 950 GST_cache_get_handle_done (struct GSTCacheGetHandle *cgh);
 951
 952
 953 /**
 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.
 957  */
 958 void
 959 GST_stats_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
 960
 961
 962 /**
 963  * Shutdown the status calls module.
 964  */
 965 void
 966 GST_stats_destroy ();
 967
 968 /* End of gnunet-service-testbed.h */