src/testbed/testbed_api.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2012 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 3, 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/testbed_api.h
  23  * @brief Interface for functions internally exported from testbed_api.c
  24  * @author Sree Harsha Totakura
  25  */
  26
  27 #ifndef TESTBED_API_H
  28 #define TESTBED_API_H
  29
  30 #include "gnunet_testbed_service.h"
  31 #include "testbed.h"
  32
  33
  34 /**
  35  * Testbed Helper binary name
  36  */
  37 #define HELPER_TESTBED_BINARY "gnunet-helper-testbed"
  38
  39
  40 /**
  41  * Enumeration of operations
  42  */
  43 enum OperationType
  44 {
  45     /**
  46      * Peer create operation
  47      */
  48   OP_PEER_CREATE,
  49
  50     /**
  51      * Peer start operation
  52      */
  53   OP_PEER_START,
  54
  55     /**
  56      * Peer stop operation
  57      */
  58   OP_PEER_STOP,
  59
  60     /**
  61      * Peer destroy operation
  62      */
  63   OP_PEER_DESTROY,
  64
  65     /**
  66      * Get peer information operation
  67      */
  68   OP_PEER_INFO,
  69
  70     /**
  71      * Overlay connection operation
  72      */
  73   OP_OVERLAY_CONNECT,
  74
  75     /**
  76      * Forwarded operation
  77      */
  78   OP_FORWARDED,
  79
  80     /**
  81      * Link controllers operation
  82      */
  83   OP_LINK_CONTROLLERS,
  84
  85   /**
  86    * Get slave config operation
  87    */
  88   OP_GET_SLAVE_CONFIG
  89
  90 };
  91
  92
  93 /**
  94  * The message queue for sending messages to the controller service
  95  */
  96 struct MessageQueue;
  97
  98 /**
  99  * Structure for a controller link
 100  */
 101 struct ControllerLink;
 102
 103
 104 /**
 105  * Enumeration of states of OperationContext
 106  */
 107 enum OperationContextState
 108 {
 109     /**
 110      * The initial state where the associated operation has just been created
 111      * and is waiting in the operation queues to be started
 112      */
 113   OPC_STATE_INIT = 0,
 114
 115     /**
 116      * The operation has been started. It may occupy some resources which are to
 117      * be freed if cancelled.
 118      */
 119   OPC_STATE_STARTED,
 120
 121     /**
 122      * The operation has finished. The end results of this operation may occupy
 123      * some resources which are to be freed by operation_done
 124      */
 125   OPC_STATE_FINISHED
 126 };
 127
 128
 129 /**
 130  * Context information for GNUNET_TESTBED_Operation
 131  */
 132 struct OperationContext
 133 {
 134   /**
 135    * next ptr for DLL
 136    */
 137   struct OperationContext *next;
 138
 139   /**
 140    * prev ptr for DLL
 141    */
 142   struct OperationContext *prev;
 143
 144   /**
 145    * The controller to which this operation context belongs to
 146    */
 147   struct GNUNET_TESTBED_Controller *c;
 148
 149   /**
 150    * The operation
 151    */
 152   struct GNUNET_TESTBED_Operation *op;
 153
 154   /**
 155    * The operation closure
 156    */
 157   void *op_cls;
 158
 159   /**
 160    * Data relevant to the operation
 161    */
 162   void *data;
 163
 164   /**
 165    * The id of the opearation
 166    */
 167   uint64_t id;
 168
 169   /**
 170    * The type of operation
 171    */
 172   enum OperationType type;
 173
 174   /**
 175    * The state of the operation
 176    */
 177   enum OperationContextState state;
 178 };
 179
 180
 181 /**
 182  * Opaque handle for SD calculations
 183  */
 184 struct SDHandle;
 185
 186
 187 /**
 188  * A slot to record time taken by an overlay connect operation
 189  */
 190 struct TimeSlot
 191 {
 192   /**
 193    * A key to identify this timeslot
 194    */
 195   void *key;
 196
 197   /**
 198    * Time
 199    */
 200   struct GNUNET_TIME_Relative time;
 201
 202 };
 203
 204
 205 /**
 206  * Handle to interact with a GNUnet testbed controller.  Each
 207  * controller has at least one master handle which is created when the
 208  * controller is created; this master handle interacts with the
 209  * controller process, destroying it destroys the controller (by
 210  * closing stdin of the controller process).  Additionally,
 211  * controllers can interact with each other (in a P2P fashion); those
 212  * links are established via TCP/IP on the controller's service port.
 213  */
 214 struct GNUNET_TESTBED_Controller
 215 {
 216   /**
 217    * The host where the controller is running
 218    */
 219   struct GNUNET_TESTBED_Host *host;
 220
 221   /**
 222    * The controller callback
 223    */
 224   GNUNET_TESTBED_ControllerCallback cc;
 225
 226   /**
 227    * The closure for controller callback
 228    */
 229   void *cc_cls;
 230
 231   /**
 232    * The configuration to use while connecting to controller
 233    */
 234   struct GNUNET_CONFIGURATION_Handle *cfg;
 235
 236   /**
 237    * The client connection handle to the controller service
 238    */
 239   struct GNUNET_CLIENT_Connection *client;
 240
 241   /**
 242    * The head of the message queue
 243    */
 244   struct MessageQueue *mq_head;
 245
 246   /**
 247    * The tail of the message queue
 248    */
 249   struct MessageQueue *mq_tail;
 250
 251   /**
 252    * The head of the ControllerLink list
 253    */
 254   struct ControllerLink *cl_head;
 255
 256   /**
 257    * The tail of the ControllerLink list
 258    */
 259   struct ControllerLink *cl_tail;
 260
 261   /**
 262    * The client transmit handle
 263    */
 264   struct GNUNET_CLIENT_TransmitHandle *th;
 265
 266   /**
 267    * The host registration handle; NULL if no current registration requests are
 268    * present
 269    */
 270   struct GNUNET_TESTBED_HostRegistrationHandle *rh;
 271
 272   /**
 273    * The head of the opeartion context queue
 274    */
 275   struct OperationContext *ocq_head;
 276
 277   /**
 278    * The tail of the operation context queue
 279    */
 280   struct OperationContext *ocq_tail;
 281
 282   /**
 283    * Operation queue for simultaneous operations
 284    */
 285   struct OperationQueue *opq_parallel_operations;
 286
 287   /**
 288    * Operation queue for simultaneous service connections
 289    */
 290   struct OperationQueue *opq_parallel_service_connections;
 291
 292   /**
 293    * Operation queue for simultaneous topology configuration operations
 294    */
 295   struct OperationQueue *opq_parallel_topology_config_operations;
 296
 297   /**
 298    * Operation queue for simultaneous overlay connect operations
 299    */
 300   struct OperationQueue *opq_parallel_overlay_connect_operations;
 301
 302   /**
 303    * An array of timing slots; size should be equal to the current number of parallel
 304    * overlay connects
 305    */
 306   struct TimeSlot *tslots;
 307
 308   /**
 309    * Handle for SD calculations amount parallel overlay connect operation finish
 310    * times
 311    */
 312   struct SDHandle *poc_sd;
 313
 314   /**
 315    * The controller event mask
 316    */
 317   uint64_t event_mask;
 318
 319   /**
 320    * Did we start the receive loop yet?
 321    */
 322   int in_receive;
 323
 324   /**
 325    * Did we create the host for this?
 326    */
 327   int aux_host;
 328
 329   /**
 330    * The number of parallel overlay connects we do currently
 331    */
 332   unsigned int num_parallel_connects;
 333
 334   /**
 335    * Counter to indicate when all the available time slots are filled
 336    */
 337   unsigned int tslots_filled;
 338
 339   /**
 340    * The operation id counter. use current value and increment
 341    */
 342   uint32_t operation_counter;
 343
 344 };
 345
 346
 347 /**
 348  * Queues a message in send queue for sending to the service
 349  *
 350  * @param controller the handle to the controller
 351  * @param msg the message to queue
 352  */
 353 void
 354 GNUNET_TESTBED_queue_message_ (struct GNUNET_TESTBED_Controller *controller,
 355                                struct GNUNET_MessageHeader *msg);
 356
 357
 358 /**
 359  * Compresses given configuration using zlib compress
 360  *
 361  * @param config the serialized configuration
 362  * @param size the size of config
 363  * @param xconfig will be set to the compressed configuration (memory is fresly
 364  *          allocated)
 365  * @return the size of the xconfig
 366  */
 367 size_t
 368 GNUNET_TESTBED_compress_config_ (const char *config, size_t size,
 369                                  char **xconfig);
 370
 371
 372 /**
 373  * Adds an operation to the queue of operations
 374  *
 375  * @param op the operation to add
 376  */
 377 void
 378 GNUNET_TESTBED_operation_add_ (struct GNUNET_TESTBED_Operation *op);
 379
 380
 381 /**
 382  * Creates a helper initialization message. This function is here because we
 383  * want to use this in testing
 384  *
 385  * @param trusted_ip the ip address of the controller which will be set as TRUSTED
 386  *          HOST(all connections form this ip are permitted by the testbed) when
 387  *          starting testbed controller at host. This can either be a single ip
 388  *          address or a network address in CIDR notation.
 389  * @param hostname the hostname of the destination this message is intended for
 390  * @param cfg the configuration that has to used to start the testbed service
 391  *          thru helper
 392  * @return the initialization message
 393  */
 394 struct GNUNET_TESTBED_HelperInit *
 395 GNUNET_TESTBED_create_helper_init_msg_ (const char *cname,
 396                                         const char *hostname,
 397                                         const struct GNUNET_CONFIGURATION_Handle
 398                                         *cfg);
 399
 400
 401 /**
 402  * Sends the given message as an operation. The given callback is called when a
 403  * reply for the operation is available.  Call
 404  * GNUNET_TESTBED_forward_operation_msg_cancel_() to cleanup the returned
 405  * operation context if the cc hasn't been called
 406  *
 407  * @param controller the controller to which the message has to be sent
 408  * @param operation_id the operation id of the message
 409  * @param msg the message to send
 410  * @param cc the callback to call when reply is available
 411  * @param cc_cls the closure for the above callback
 412  * @return the operation context which can be used to cancel the forwarded
 413  *           operation
 414  */
 415 struct OperationContext *
 416 GNUNET_TESTBED_forward_operation_msg_ (struct GNUNET_TESTBED_Controller
 417                                        *controller, uint64_t operation_id,
 418                                        const struct GNUNET_MessageHeader *msg,
 419                                        GNUNET_CLIENT_MessageHandler cc,
 420                                        void *cc_cls);
 421
 422 /**
 423  * Function to cancel an operation created by simply forwarding an operation
 424  * message.
 425  *
 426  * @param opc the operation context from GNUNET_TESTBED_forward_operation_msg_()
 427  */
 428 void
 429 GNUNET_TESTBED_forward_operation_msg_cancel_ (struct OperationContext *opc);
 430
 431
 432 /**
 433  * Generates configuration by uncompressing configuration in given message. The
 434  * given message should be of the following types:
 435  * GNUNET_MESSAGE_TYPE_TESTBED_PEERCONFIG,
 436  * GNUNET_MESSAGE_TYPE_TESTBED_SLAVECONFIG
 437  *
 438  * @param msg the message containing compressed configuration
 439  * @return handle to the parsed configuration
 440  */
 441 struct GNUNET_CONFIGURATION_Handle *
 442 GNUNET_TESTBED_extract_config_ (const struct GNUNET_MessageHeader *msg);
 443
 444
 445 /**
 446  * Checks the integrity of the OpeationFailureEventMessage and if good returns
 447  * the error message it contains.
 448  *
 449  * @param msg the OperationFailureEventMessage
 450  * @return the error message
 451  */
 452 const char *
 453 GNUNET_TESTBED_parse_error_string_ (const struct
 454                                     GNUNET_TESTBED_OperationFailureEventMessage
 455                                     *msg);
 456
 457
 458 /**
 459  * Function to return the operation id for a controller. The operation id is
 460  * created from the controllers host id and its internal operation counter.
 461  *
 462  * @param controller the handle to the controller whose operation id has to be incremented
 463  * @return the incremented operation id.
 464  */
 465 uint64_t
 466 GNUNET_TESTBED_get_next_op_id (struct GNUNET_TESTBED_Controller *controller);
 467
 468
 469 /**
 470  * Like GNUNET_TESTBED_get_slave_config(), however without the host registration
 471  * check. Another difference is that this function takes the id of the slave
 472  * host.
 473  *
 474  * @param op_cls the closure for the operation
 475  * @param master the handle to master controller
 476  * @param slave_host_id id of the host where the slave controller is running to
 477  *          the slave_host should remain valid until this operation is cancelled
 478  *          or marked as finished
 479  * @return the operation handle;
 480  */
 481 struct GNUNET_TESTBED_Operation *
 482 GNUNET_TESTBED_get_slave_config_ (void *op_cls,
 483                                   struct GNUNET_TESTBED_Controller *master,
 484                                   uint32_t slave_host_id);
 485
 486
 487 /**
 488  * Same as the GNUNET_TESTBED_controller_link_2, but with ids for delegated host
 489  * and slave host
 490  *
 491  * @param op_cls the operation closure for the event which is generated to
 492  *          signal success or failure of this operation
 493  * @param master handle to the master controller who creates the association
 494  * @param delegated_host_id id of the host to which requests should be delegated
 495  * @param slave_host_id id of the host which is used to run the slave controller
 496  * @param sxcfg serialized and compressed configuration
 497  * @param sxcfg_size the size sxcfg
 498  * @param scfg_size the size of uncompressed serialized configuration
 499  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 500  *          be started by the slave controller; GNUNET_NO if the slave
 501  *          controller has to connect to the already started delegated
 502  *          controller via TCP/IP
 503  * @return the operation handle
 504  */
 505 struct GNUNET_TESTBED_Operation *
 506 GNUNET_TESTBED_controller_link_2_ (void *op_cls,
 507                                    struct GNUNET_TESTBED_Controller *master,
 508                                    uint32_t delegated_host_id,
 509                                    uint32_t slave_host_id,
 510                                    const char *sxcfg, size_t sxcfg_size,
 511                                    size_t scfg_size, int is_subordinate);
 512
 513
 514 /**
 515  * Same as the GNUNET_TESTBED_controller_link, but with ids for delegated host
 516  * and slave host
 517  *
 518  * @param op_cls the operation closure for the event which is generated to
 519  *          signal success or failure of this operation
 520  * @param master handle to the master controller who creates the association
 521  * @param delegated_host_id id of the host to which requests should be
 522  *          delegated; cannot be NULL
 523  * @param slave_host_id id of the host which should connect to controller
 524  *          running on delegated host ; use NULL to make the master controller
 525  *          connect to the delegated host
 526  * @param slave_cfg configuration to use for the slave controller
 527  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 528  *          be started by the slave controller; GNUNET_NO if the slave
 529  *          controller has to connect to the already started delegated
 530  *          controller via TCP/IP
 531  * @return the operation handle
 532  */
 533 struct GNUNET_TESTBED_Operation *
 534 GNUNET_TESTBED_controller_link_ (void *op_cls,
 535                                 struct GNUNET_TESTBED_Controller *master,
 536                                 uint32_t delegated_host_id,
 537                                 uint32_t slave_host_id,
 538                                 const struct GNUNET_CONFIGURATION_Handle
 539                                 *slave_cfg,
 540                                  int is_subordinate);
 541
 542
 543 /**
 544  * Returns a timing slot which will be exclusively locked
 545  *
 546  * @param c the controller handle
 547  * @param key a pointer which is associated to the returned slot; should not be
 548  *          NULL. It serves as a key to determine the correct owner of the slot
 549  * @return the time slot index in the array of time slots in the controller
 550  *           handle
 551  */
 552 unsigned int
 553 GNUNET_TESTBED_get_tslot_ (struct GNUNET_TESTBED_Controller *c, void *key);
 554
 555
 556 /**
 557  * Function to update a time slot
 558  *
 559  * @param c the controller handle
 560  * @param index the index of the time slot to update
 561  * @param key the key to identify ownership of the slot
 562  * @param time the new time
 563  */
 564 void
 565 GNUNET_TESTBED_update_time_slot_ (struct GNUNET_TESTBED_Controller *c,
 566                                   unsigned int index,
 567                                   void *key,
 568                                   struct GNUNET_TIME_Relative time);
 569
 570
 571 /**
 572  * Releases a time slot thus making it available for be used again
 573  *
 574  * @param c the controller handle
 575  * @param index the index of the the time slot
 576  * @param key the key to prove ownership of the timeslot
 577  * @return GNUNET_YES if the time slot is successfully removed; GNUNET_NO if the
 578  *           time slot cannot be removed - this could be because of the index
 579  *           greater than existing number of time slots or `key' being different
 580  */
 581 int
 582 GNUNET_TESTBED_release_time_slot_ (struct GNUNET_TESTBED_Controller *c,
 583                                   unsigned int index,
 584                                    void *key);
 585
 586
 587
 588
 589 #endif
 590 /* end of testbed_api.h */