src/testbed/testbed_api.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
   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., 51 Franklin Street, Fifth Floor,
  18       Boston, MA 02110-1301, 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_util_lib.h"
  31 #include "gnunet_testbed_service.h"
  32 #include "testbed.h"
  33 #include "testbed_helper.h"
  34
  35 /**
  36  * Testbed Helper binary name
  37  */
  38 #define HELPER_TESTBED_BINARY "gnunet-helper-testbed"
  39
  40
  41 /**
  42  * Enumeration of operations
  43  */
  44 enum OperationType
  45 {
  46     /**
  47      * Peer create operation
  48      */
  49   OP_PEER_CREATE,
  50
  51     /**
  52      * Peer start operation
  53      */
  54   OP_PEER_START,
  55
  56     /**
  57      * Peer stop operation
  58      */
  59   OP_PEER_STOP,
  60
  61     /**
  62      * Peer destroy operation
  63      */
  64   OP_PEER_DESTROY,
  65
  66     /**
  67      * Get peer information operation
  68      */
  69   OP_PEER_INFO,
  70
  71   /**
  72    * Reconfigure a peer
  73    */
  74   OP_PEER_RECONFIGURE,
  75
  76     /**
  77      * Overlay connection operation
  78      */
  79   OP_OVERLAY_CONNECT,
  80
  81     /**
  82      * Forwarded operation
  83      */
  84   OP_FORWARDED,
  85
  86     /**
  87      * Link controllers operation
  88      */
  89   OP_LINK_CONTROLLERS,
  90
  91   /**
  92    * Get slave config operation
  93    */
  94   OP_GET_SLAVE_CONFIG,
  95
  96   /**
  97    * Stop and destroy all peers
  98    */
  99   OP_SHUTDOWN_PEERS,
 100
 101   /**
 102    * Start/stop service at a peer
 103    */
 104   OP_MANAGE_SERVICE
 105 };
 106
 107
 108 /**
 109  * The message queue for sending messages to the controller service
 110  */
 111 struct MessageQueue;
 112
 113
 114 /**
 115  * Enumeration of states of OperationContext
 116  */
 117 enum OperationContextState
 118 {
 119     /**
 120      * The initial state where the associated operation has just been created
 121      * and is waiting in the operation queues to be started
 122      */
 123   OPC_STATE_INIT = 0,
 124
 125     /**
 126      * The operation has been started. It may occupy some resources which are to
 127      * be freed if cancelled.
 128      */
 129   OPC_STATE_STARTED,
 130
 131     /**
 132      * The operation has finished. The end results of this operation may occupy
 133      * some resources which are to be freed by operation_done
 134      */
 135   OPC_STATE_FINISHED
 136 };
 137
 138
 139 /**
 140  * Context information for GNUNET_TESTBED_Operation
 141  */
 142 struct OperationContext
 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  * Operation empty callback
 183  *
 184  * @param cls closure
 185  */
 186 typedef void
 187 (*TESTBED_opcq_empty_cb) (void *cls);
 188
 189
 190 /**
 191  * Handle to interact with a GNUnet testbed controller.  Each
 192  * controller has at least one master handle which is created when the
 193  * controller is created; this master handle interacts with the
 194  * controller process, destroying it destroys the controller (by
 195  * closing stdin of the controller process).  Additionally,
 196  * controllers can interact with each other (in a P2P fashion); those
 197  * links are established via TCP/IP on the controller's service port.
 198  */
 199 struct GNUNET_TESTBED_Controller
 200 {
 201   /**
 202    * The host where the controller is running
 203    */
 204   struct GNUNET_TESTBED_Host *host;
 205
 206   /**
 207    * The controller callback
 208    */
 209   GNUNET_TESTBED_ControllerCallback cc;
 210
 211   /**
 212    * The closure for controller callback
 213    */
 214   void *cc_cls;
 215
 216   /**
 217    * The configuration to use while connecting to controller
 218    */
 219   struct GNUNET_CONFIGURATION_Handle *cfg;
 220
 221   /**
 222    * The client connection handle to the controller service
 223    */
 224   struct GNUNET_CLIENT_Connection *client;
 225
 226   /**
 227    * The head of the message queue
 228    */
 229   struct MessageQueue *mq_head;
 230
 231   /**
 232    * The tail of the message queue
 233    */
 234   struct MessageQueue *mq_tail;
 235
 236   /**
 237    * The client transmit handle
 238    */
 239   struct GNUNET_CLIENT_TransmitHandle *th;
 240
 241   /**
 242    * The host registration handle; NULL if no current registration requests are
 243    * present
 244    */
 245   struct GNUNET_TESTBED_HostRegistrationHandle *rh;
 246
 247   /**
 248    * The map of active operation contexts
 249    */
 250   struct GNUNET_CONTAINER_MultiHashMap32 *opc_map;
 251
 252   /**
 253    * If this callback is not NULL, schedule it as a task when opc_map gets empty
 254    */
 255   TESTBED_opcq_empty_cb opcq_empty_cb;
 256
 257   /**
 258    * Closure for the above task
 259    */
 260   void *opcq_empty_cls;
 261
 262   /**
 263    * Operation queue for simultaneous operations
 264    */
 265   struct OperationQueue *opq_parallel_operations;
 266
 267   /**
 268    * Operation queue for simultaneous service connections
 269    */
 270   struct OperationQueue *opq_parallel_service_connections;
 271
 272   /**
 273    * Operation queue for simultaneous topology configuration operations
 274    */
 275   struct OperationQueue *opq_parallel_topology_config_operations;
 276
 277   /**
 278    * handle for hashtable of barrier handles, values are
 279    * of type `struct GNUNET_TESTBED_Barrier`.
 280    */
 281   struct GNUNET_CONTAINER_MultiHashMap *barrier_map;
 282
 283   /**
 284    * The controller event mask
 285    */
 286   uint64_t event_mask;
 287
 288   /**
 289    * Did we start the receive loop yet?
 290    */
 291   int in_receive;
 292
 293   /**
 294    * The operation id counter. use current value and increment
 295    */
 296   uint32_t operation_counter;
 297
 298 };
 299
 300
 301 /**
 302  * Handle for barrier
 303  */
 304 struct GNUNET_TESTBED_Barrier
 305 {
 306   /**
 307    * hashcode identifying this barrier in the hashmap
 308    */
 309   struct GNUNET_HashCode key;
 310
 311   /**
 312    * The controller handle given while initiliasing this barrier
 313    */
 314   struct GNUNET_TESTBED_Controller *c;
 315
 316   /**
 317    * The name of the barrier
 318    */
 319   char *name;
 320
 321   /**
 322    * The continuation callback to call when we have a status update on this
 323    */
 324   GNUNET_TESTBED_barrier_status_cb cb;
 325
 326   /**
 327    * the closure for the above callback
 328    */
 329   void *cls;
 330
 331   /**
 332    * Should the barrier crossed status message be echoed back to the controller?
 333    */
 334   int echo;
 335 };
 336
 337
 338
 339 /**
 340  * Queues a message in send queue for sending to the service
 341  *
 342  * @param controller the handle to the controller
 343  * @param msg the message to queue
 344  */
 345 void
 346 GNUNET_TESTBED_queue_message_ (struct GNUNET_TESTBED_Controller *controller,
 347                                struct GNUNET_MessageHeader *msg);
 348
 349
 350 /**
 351  * Inserts the given operation context into the operation context map of the
 352  * given controller.  Creates the operation context map if one does not exist
 353  * for the controller
 354  *
 355  * @param c the controller
 356  * @param opc the operation context to be inserted
 357  */
 358 void
 359 GNUNET_TESTBED_insert_opc_ (struct GNUNET_TESTBED_Controller *c,
 360                             struct OperationContext *opc);
 361
 362
 363 /**
 364  * Removes the given operation context from the operation context map of the
 365  * given controller
 366  *
 367  * @param c the controller
 368  * @param opc the operation context to remove
 369  */
 370 void
 371 GNUNET_TESTBED_remove_opc_ (const struct GNUNET_TESTBED_Controller *c,
 372                             struct OperationContext *opc);
 373
 374
 375 /**
 376  * Compresses given configuration using zlib compress
 377  *
 378  * @param config the serialized configuration
 379  * @param size the size of config
 380  * @param xconfig will be set to the compressed configuration (memory is fresly
 381  *          allocated)
 382  * @return the size of the xconfig
 383  */
 384 size_t
 385 GNUNET_TESTBED_compress_config_ (const char *config, size_t size,
 386                                  char **xconfig);
 387
 388
 389 /**
 390  * Function to serialize and compress using zlib a configuration through a
 391  * configuration handle
 392  *
 393  * @param cfg the configuration
 394  * @param size the size of configuration when serialize.  Will be set on success.
 395  * @param xsize the sizeo of the compressed configuration.  Will be set on success.
 396  * @return the serialized and compressed configuration
 397  */
 398 char *
 399 GNUNET_TESTBED_compress_cfg_ (const struct GNUNET_CONFIGURATION_Handle *cfg,
 400                               size_t *size, size_t *xsize);
 401
 402
 403 /**
 404  * Creates a helper initialization message. This function is here because we
 405  * want to use this in testing
 406  *
 407  * @param trusted_ip the ip address of the controller which will be set as TRUSTED
 408  *          HOST(all connections form this ip are permitted by the testbed) when
 409  *          starting testbed controller at host. This can either be a single ip
 410  *          address or a network address in CIDR notation.
 411  * @param hostname the hostname of the destination this message is intended for
 412  * @param cfg the configuration that has to used to start the testbed service
 413  *          thru helper
 414  * @return the initialization message
 415  */
 416 struct GNUNET_TESTBED_HelperInit *
 417 GNUNET_TESTBED_create_helper_init_msg_ (const char *cname, const char *hostname,
 418                                         const struct GNUNET_CONFIGURATION_Handle
 419                                         *cfg);
 420
 421
 422 /**
 423  * Sends the given message as an operation. The given callback is called when a
 424  * reply for the operation is available.  Call
 425  * GNUNET_TESTBED_forward_operation_msg_cancel_() to cleanup the returned
 426  * operation context if the cc hasn't been called
 427  *
 428  * @param controller the controller to which the message has to be sent
 429  * @param operation_id the operation id of the message
 430  * @param msg the message to send
 431  * @param cc the callback to call when reply is available
 432  * @param cc_cls the closure for the above callback
 433  * @return the operation context which can be used to cancel the forwarded
 434  *           operation
 435  */
 436 struct OperationContext *
 437 GNUNET_TESTBED_forward_operation_msg_ (struct GNUNET_TESTBED_Controller
 438                                        *controller, uint64_t operation_id,
 439                                        const struct GNUNET_MessageHeader *msg,
 440                                        GNUNET_CLIENT_MessageHandler cc,
 441                                        void *cc_cls);
 442
 443 /**
 444  * Function to cancel an operation created by simply forwarding an operation
 445  * message.
 446  *
 447  * @param opc the operation context from GNUNET_TESTBED_forward_operation_msg_()
 448  */
 449 void
 450 GNUNET_TESTBED_forward_operation_msg_cancel_ (struct OperationContext *opc);
 451
 452
 453 /**
 454  * Generates configuration by uncompressing configuration in given message. The
 455  * given message should be of the following types:
 456  * GNUNET_MESSAGE_TYPE_TESTBED_PEERCONFIG,
 457  * GNUNET_MESSAGE_TYPE_TESTBED_SLAVECONFIG
 458  *
 459  * @param msg the message containing compressed configuration
 460  * @return handle to the parsed configuration
 461  */
 462 struct GNUNET_CONFIGURATION_Handle *
 463 GNUNET_TESTBED_extract_config_ (const struct GNUNET_MessageHeader *msg);
 464
 465
 466 /**
 467  * Checks the integrity of the OpeationFailureEventMessage and if good returns
 468  * the error message it contains.
 469  *
 470  * @param msg the OperationFailureEventMessage
 471  * @return the error message
 472  */
 473 const char *
 474 GNUNET_TESTBED_parse_error_string_ (const struct
 475                                     GNUNET_TESTBED_OperationFailureEventMessage
 476                                     *msg);
 477
 478
 479 /**
 480  * Function to return the operation id for a controller. The operation id is
 481  * created from the controllers host id and its internal operation counter.
 482  *
 483  * @param controller the handle to the controller whose operation id has to be incremented
 484  * @return the incremented operation id.
 485  */
 486 uint64_t
 487 GNUNET_TESTBED_get_next_op_id (struct GNUNET_TESTBED_Controller *controller);
 488
 489
 490 /**
 491  * Like GNUNET_TESTBED_get_slave_config(), however without the host registration
 492  * check. Another difference is that this function takes the id of the slave
 493  * host.
 494  *
 495  * @param op_cls the closure for the operation
 496  * @param master the handle to master controller
 497  * @param slave_host_id id of the host where the slave controller is running to
 498  *          the slave_host should remain valid until this operation is cancelled
 499  *          or marked as finished
 500  * @return the operation handle;
 501  */
 502 struct GNUNET_TESTBED_Operation *
 503 GNUNET_TESTBED_get_slave_config_ (void *op_cls,
 504                                   struct GNUNET_TESTBED_Controller *master,
 505                                   uint32_t slave_host_id);
 506
 507
 508 #endif
 509 /* end of testbed_api.h */