src/ats/test_ats_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010-2015 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  * @file ats/test_ats_lib.h
  20  * @brief test ATS library with a generic interpreter for running ATS tests
  21  * @author Christian Grothoff
  22  */
  23 #ifndef TEST_ATS_LIB_H
  24 #define TEST_ATS_LIB_H
  25
  26 #include "gnunet_util_lib.h"
  27 #include "gnunet_ats_service.h"
  28 #include "gnunet_testing_lib.h"
  29
  30
  31 /**
  32  * Commands for the interpreter.
  33  */
  34 enum CommandCode
  35 {
  36   /**
  37    * End the test (passing).
  38    */
  39   CMD_END_PASS = 0,
  40
  41   /**
  42    * Call #GNUNET_ATS_address_add().
  43    */
  44   CMD_ADD_ADDRESS,
  45
  46   /**
  47    * Call #GNUNET_ATS_address_del().
  48    */
  49   CMD_DEL_ADDRESS,
  50
  51   /**
  52    * Wait for ATS to suggest address.
  53    */
  54   CMD_AWAIT_ADDRESS_SUGGESTION,
  55
  56   /**
  57    * Wait for ATS to suggest disconnect.
  58    */
  59   CMD_AWAIT_DISCONNECT_SUGGESTION,
  60
  61   /**
  62    * Ask ATS to connect to a peer, using
  63    * #GNUNET_ATS_connectivity_suggest().
  64    */
  65   CMD_REQUEST_CONNECTION_START,
  66
  67   /**
  68    * Tell ATS we no longer need a connection to a peer, using
  69    * #GNUNET_ATS_connectivity_suggest_cancel().
  70    */
  71   CMD_REQUEST_CONNECTION_STOP,
  72
  73   /**
  74    * Wait for certain address information to be provided.
  75    */
  76   CMD_AWAIT_ADDRESS_INFORMATION,
  77
  78   /**
  79    * Update properties of an address, using
  80    * #GNUNET_ATS_address_update().
  81    */
  82   CMD_UPDATE_ADDRESS,
  83
  84   /**
  85    * Add session to an address, using
  86    * #GNUNET_ATS_address_add_session().
  87    */
  88   CMD_ADD_SESSION,
  89
  90   /**
  91    * Remove session from an address, using
  92    * #GNUNET_ATS_address_del_session().
  93    */
  94   CMD_DEL_SESSION,
  95
  96   /**
  97    * Change performance preferences for a peer, testing
  98    * #GNUNET_ATS_performance_change_preference().
  99    */
 100   CMD_CHANGE_PREFERENCE,
 101
 102   /**
 103    * Provide allocation quality feedback, testing
 104    * #GNUNET_ATS_performance_give_feedback().
 105    */
 106   CMD_PROVIDE_FEEDBACK,
 107
 108   /**
 109    * Obtain list of all addresses, testing
 110    * #GNUNET_ATS_performance_list_addresses().
 111    */
 112   CMD_LIST_ADDRESSES,
 113
 114   /**
 115    * Reserve bandwidth, testing
 116    * #GNUNET_ATS_reserve_bandwidth().
 117    */
 118   CMD_RESERVE_BANDWIDTH,
 119
 120   /**
 121    * Wait for a bit.
 122    */
 123   CMD_SLEEP
 124
 125 };
 126
 127
 128 /**
 129  * Details for the #CMD_ADD_ADDRESS command.
 130  */
 131 struct CommandAddAddress
 132 {
 133   /**
 134    * Number of the peer (used to generate PID).
 135    */
 136   unsigned int pid;
 137
 138   /**
 139    * Number of the address (used to generate binary address).
 140    */
 141   unsigned int addr_num;
 142
 143   /**
 144    * Session to supply, 0 for NULL.
 145    */
 146   unsigned int session;
 147
 148   /**
 149    * Flags to set for the address.
 150    */
 151   enum GNUNET_HELLO_AddressInfo addr_flags;
 152
 153   /**
 154    * Performance properties to supply.
 155    */
 156   struct GNUNET_ATS_Properties properties;
 157
 158   /**
 159    * Expect the operation to fail (duplicate).
 160    */
 161   int expect_fail;
 162
 163   /**
 164    * Here the result of the add address operation will be stored.
 165    */
 166   struct GNUNET_ATS_AddressRecord *ar;
 167 };
 168
 169
 170 /**
 171  * Details for the #CMD_DEL_ADDRESS command.
 172  */
 173 struct CommandDelAddress
 174 {
 175   /**
 176    * Label of the corresponding #CMD_ADD_ADDRESS that
 177    * we are now to remove.
 178    */
 179   const char *add_label;
 180 };
 181
 182
 183 /**
 184  * Details for the #CMD_AWAIT_ADDRESS_SUGGESTION command.
 185  */
 186 struct CommandAwaitAddressSuggestion
 187 {
 188   /**
 189    * For which peer do we expect a suggestion?
 190    */
 191   unsigned int pid;
 192
 193   /**
 194    * If we expect the address suggested to match a particular
 195    * addition, specify the label of the add operation here. Otherwise
 196    * use NULL for "any" available address.
 197    */
 198   const char *add_label;
 199
 200 };
 201
 202
 203 /**
 204  * Details for the #CMD_AWAIT_DISCONNECT_SUGGESTION command.
 205  */
 206 struct CommandAwaitDisconnectSuggestion
 207 {
 208   /**
 209    * For which peer do we expect the disconnect?
 210    */
 211   unsigned int pid;
 212
 213 };
 214
 215
 216 /**
 217  * Details for the #CMD_REQUEST_CONNECTION_START command.
 218  */
 219 struct CommandRequestConnectionStart
 220 {
 221   /**
 222    * Identity of the peer we would like to connect to.
 223    */
 224   unsigned int pid;
 225
 226   /**
 227    * Location where we store the handle returned from
 228    * #GNUNET_ATS_connectivity_suggest().
 229    */
 230   struct GNUNET_ATS_ConnectivitySuggestHandle *csh;
 231 };
 232
 233
 234 /**
 235  * Details for the #CMD_REQUEST_CONNECTION_STOP command.
 236  */
 237 struct CommandRequestConnectionStop
 238 {
 239   /**
 240    * Label of the corresponding #CMD_REQUEST_CONNECTION_START that
 241    * we are now stopping.
 242    */
 243   const char *connect_label;
 244 };
 245
 246
 247 /**
 248  * Details for the #CMD_AWAIT_ADDRESS_INFORMATION command.
 249  */
 250 struct CommandAwaitAddressInformation
 251 {
 252   /**
 253    * For which address do we expect information?
 254    * The address is identified by the respective
 255    * label of the corresponding add operation.
 256    */
 257   const char *add_label;
 258
 259   /**
 260    * Label of a possible update operation that may
 261    * have modified the properties.  NULL to use
 262    * the properties from the @e add_label.
 263    */
 264   const char *update_label;
 265
 266 };
 267
 268
 269 /**
 270  * Details for the #CMD_UPDATE_ADDRESS command.
 271  */
 272 struct CommandUpdateAddress
 273 {
 274   /**
 275    * Label of the addresses's add operation.
 276    */
 277   const char *add_label;
 278
 279   /**
 280    * Performance properties to supply.
 281    */
 282   struct GNUNET_ATS_Properties properties;
 283
 284 };
 285
 286
 287 /**
 288  * Details for the #CMD_ADD_SESSION command.
 289  */
 290 struct CommandAddSession
 291 {
 292  /**
 293    * Label of the addresses's add operation.
 294    */
 295   const char *add_label;
 296
 297   /**
 298    * Session to supply.
 299    */
 300   unsigned int session;
 301
 302 };
 303
 304
 305 /**
 306  * Details for the #CMD_DEL_SESSION command.
 307  */
 308 struct CommandDelSession
 309 {
 310  /**
 311    * Label of the addresses's add operation.
 312    */
 313   const char *add_session_label;
 314
 315 };
 316
 317
 318 /**
 319  * Details for the #CMD_CHANGE_PREFERENCE command.
 320  */
 321 struct CommandChangePreference
 322 {
 323   /**
 324    * Identity of the peer we have a preference change towards.
 325    */
 326   unsigned int pid;
 327
 328   /* FIXME: preference details! */
 329
 330 };
 331
 332
 333 /**
 334  * Details for the #CMD_PROVIDE_FEEDBACK command.
 335  */
 336 struct CommandProvideFeedback
 337 {
 338   /**
 339    * Identity of the peer we have a feedback for.
 340    */
 341   unsigned int pid;
 342
 343   /**
 344    * Over which timeframe does the feedback apply?
 345    */
 346   struct GNUNET_TIME_Relative scope;
 347
 348   /* FIXME: feedback details! */
 349 };
 350
 351
 352 /**
 353  * Details for the #CMD_LIST_ADDRESSES command.
 354  */
 355 struct CommandListAddresses
 356 {
 357   /**
 358    * Identity of the peer we want a list for.
 359    */
 360   unsigned int pid;
 361
 362   /**
 363    * All addresses or just active?
 364    */
 365   int all;
 366
 367   /**
 368    * Minimum number of addresses the callback may report.
 369    */
 370   unsigned int min_calls;
 371
 372   /**
 373    * Maximum number of addresses the callback may report.
 374    */
 375   unsigned int max_calls;
 376
 377   /**
 378    * Minimum number of active addresses the callback may report.
 379    */
 380   unsigned int min_active_calls;
 381
 382   /**
 383    * Maximum number of active addresses the callback may report.
 384    */
 385   unsigned int max_active_calls;
 386
 387   /**
 388    * Number of calls the command invoked the callback with
 389    * an address marked as active. (Set by command).
 390    */
 391   unsigned int active_calls;
 392
 393   /**
 394    * Number of calls the command invoked the callback with
 395    * any address marked as available to ATS. (Set by command).
 396    */
 397   unsigned int calls;
 398
 399   /**
 400    * Location where we store the return value from
 401    * #GNUNET_ATS_performance_list_addresses().
 402    */
 403   struct GNUNET_ATS_AddressListHandle *alh;
 404
 405 };
 406
 407
 408 /**
 409  * Details for the #CMD_RESERVE_BANDWIDTH command.
 410  */
 411 struct CommandReserveBandwidth
 412 {
 413   /**
 414    * For which peer do we reserve bandwidth?
 415    */
 416   unsigned int pid;
 417
 418   /**
 419    * How much should we try to reserve?
 420    */
 421   int32_t amount;
 422
 423   /**
 424    * Should we expect this to work or fail?
 425    * #GNUNET_YES: must work
 426    * #GNUNET_NO: may work or fail
 427    * #GNUNET_SYSERR: must fail
 428    */
 429   int expected_result;
 430
 431   /**
 432    * Location where we store the return value from
 433    * #GNUNET_ATS_reserve_bandwidth().
 434    */
 435   struct GNUNET_ATS_ReservationContext *rc;
 436
 437 };
 438
 439
 440 /**
 441  * Details for the #CMD_SLEEP command.
 442  */
 443 struct CommandSleep
 444 {
 445   /**
 446    * How long should we wait before running the next command?
 447    */
 448   struct GNUNET_TIME_Relative delay;
 449 };
 450
 451
 452 /**
 453  * A command for the test case interpreter.
 454  */
 455 struct Command
 456 {
 457   /**
 458    * Command code to run.
 459    */
 460   enum CommandCode code;
 461
 462   /**
 463    * Commands can be given a label so we can reference them later.
 464    */
 465   const char *label;
 466
 467   /**
 468    * Additional arguments to commands, if any.
 469    */
 470   union {
 471
 472     struct CommandAddAddress add_address;
 473
 474     struct CommandDelAddress del_address;
 475
 476     struct CommandAwaitAddressSuggestion await_address_suggestion;
 477
 478     struct CommandAwaitDisconnectSuggestion await_disconnect_suggestion;
 479
 480     struct CommandRequestConnectionStart request_connection_start;
 481
 482     struct CommandRequestConnectionStop request_connection_stop;
 483
 484     struct CommandAwaitAddressInformation await_address_information;
 485
 486     struct CommandUpdateAddress update_address;
 487
 488     struct CommandAddSession add_session;
 489
 490     struct CommandDelSession del_session;
 491
 492     struct CommandChangePreference change_preference;
 493
 494     struct CommandProvideFeedback provide_feedback;
 495
 496     struct CommandListAddresses list_addresses;
 497
 498     struct CommandReserveBandwidth reserve_bandwidth;
 499
 500     struct CommandSleep sleep;
 501
 502   } details;
 503
 504 };
 505
 506
 507 /**
 508  * Run ATS test.
 509  *
 510  * @param argc length of @a argv
 511  * @param argv command line
 512  * @param cmds commands to run with the interpreter
 513  * @param timeout how long is the test allowed to take?
 514  * @return 0 on success
 515  */
 516 int
 517 TEST_ATS_run (int argc,
 518               char *argv[],
 519               struct Command *cmds,
 520               struct GNUNET_TIME_Relative timeout);
 521
 522 #endif