src/ats/ats_api_performance.c

   1 /*
   2   This file is part of GNUnet.
   3   Copyright (C) 2010, 2011, 2016 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  * @file ats/ats_api_performance.c
  22  * @brief automatic transport selection and outbound bandwidth determination
  23  * @author Christian Grothoff
  24  * @author Matthias Wachs
  25  */
  26 #include "platform.h"
  27 #include "gnunet_ats_service.h"
  28 #include "ats.h"
  29
  30
  31 #define LOG(kind,...) GNUNET_log_from(kind, "ats-performance-api", __VA_ARGS__)
  32
  33
  34 /**
  35  * Linked list of pending reservations.
  36  */
  37 struct GNUNET_ATS_ReservationContext
  38 {
  39
  40   /**
  41    * Kept in a DLL.
  42    */
  43   struct GNUNET_ATS_ReservationContext *next;
  44
  45   /**
  46    * Kept in a DLL.
  47    */
  48   struct GNUNET_ATS_ReservationContext *prev;
  49
  50   /**
  51    * Target peer.
  52    */
  53   struct GNUNET_PeerIdentity peer;
  54
  55   /**
  56    * Desired reservation
  57    */
  58   int32_t size;
  59
  60   /**
  61    * Function to call on result.
  62    */
  63   GNUNET_ATS_ReservationCallback rcb;
  64
  65   /**
  66    * Closure for @e rcb
  67    */
  68   void *rcb_cls;
  69
  70   /**
  71    * Do we need to undo this reservation if it succeeded?  Set to
  72    * #GNUNET_YES if a reservation is cancelled.  (at that point, 'info'
  73    * is also set to NULL; however, info will ALSO be NULL for the
  74    * reservation context that is created to undo the original request,
  75    * so 'info' being NULL cannot be used to check if undo is
  76    * required).
  77    */
  78   int undo;
  79 };
  80
  81
  82 /**
  83  * Linked list of pending reservations.
  84  */
  85 struct GNUNET_ATS_AddressListHandle
  86 {
  87
  88   /**
  89    * Kept in a DLL.
  90    */
  91   struct GNUNET_ATS_AddressListHandle *next;
  92
  93   /**
  94    * Kept in a DLL.
  95    */
  96   struct GNUNET_ATS_AddressListHandle *prev;
  97
  98   /**
  99    * Performance handle
 100    */
 101   struct GNUNET_ATS_PerformanceHandle *ph;
 102
 103   /**
 104    * Callback
 105    */
 106   GNUNET_ATS_AddressInformationCallback cb;
 107
 108   /**
 109    * Callback closure for @e cb
 110    */
 111   void *cb_cls;
 112
 113   /**
 114    * Target peer.
 115    */
 116   struct GNUNET_PeerIdentity peer;
 117
 118   /**
 119    * Return all or specific peer only
 120    */
 121   int all_peers;
 122
 123   /**
 124    * Return all or used address only
 125    */
 126   int all_addresses;
 127
 128   /**
 129    * Request multiplexing
 130    */
 131   uint32_t id;
 132 };
 133
 134
 135 /**
 136  * ATS Handle to obtain and/or modify performance information.
 137  */
 138 struct GNUNET_ATS_PerformanceHandle
 139 {
 140
 141   /**
 142    * Our configuration.
 143    */
 144   const struct GNUNET_CONFIGURATION_Handle *cfg;
 145
 146   /**
 147    * Callback to invoke when an address has performance changes.
 148    */
 149   GNUNET_ATS_AddressInformationCallback addr_info_cb;
 150
 151   /**
 152    * Closure for @e addr_info_cb.
 153    */
 154   void *addr_info_cb_cls;
 155
 156   /**
 157    * Connection to ATS service.
 158    */
 159   struct GNUNET_MQ_Handle *mq;
 160
 161   /**
 162    * Head of linked list of pending reservation requests.
 163    */
 164   struct GNUNET_ATS_ReservationContext *reservation_head;
 165
 166   /**
 167    * Tail of linked list of pending reservation requests.
 168    */
 169   struct GNUNET_ATS_ReservationContext *reservation_tail;
 170
 171   /**
 172    * Head of linked list of pending address list requests.
 173    */
 174   struct GNUNET_ATS_AddressListHandle *addresslist_head;
 175
 176   /**
 177    * Tail of linked list of pending address list requests.
 178    */
 179   struct GNUNET_ATS_AddressListHandle *addresslist_tail;
 180
 181   /**
 182    * Current request for transmission to ATS.
 183    */
 184   struct GNUNET_CLIENT_TransmitHandle *th;
 185
 186   /**
 187    * Task to trigger reconnect.
 188    */
 189   struct GNUNET_SCHEDULER_Task *task;
 190
 191   /**
 192    * Reconnect backoff delay.
 193    */
 194   struct GNUNET_TIME_Relative backoff;
 195
 196   /**
 197    * Monitor request multiplexing
 198    */
 199   uint32_t monitor_id;
 200
 201   /**
 202    * Request multiplexing
 203    */
 204   uint32_t id;
 205
 206   /**
 207    * Is the receive loop active?
 208    */
 209   int in_receive;
 210 };
 211
 212 /**
 213  * Re-establish the connection to the ATS service.
 214  *
 215  * @param ph handle to use to re-connect.
 216  */
 217 static void
 218 reconnect (struct GNUNET_ATS_PerformanceHandle *ph);
 219
 220
 221 /**
 222  * Re-establish the connection to the ATS service.
 223  *
 224  * @param cls handle to use to re-connect.
 225  */
 226 static void
 227 reconnect_task (void *cls)
 228 {
 229   struct GNUNET_ATS_PerformanceHandle *ph = cls;
 230
 231   ph->task = NULL;
 232   reconnect (ph);
 233 }
 234
 235
 236 /**
 237  * Reconnect to the ATS service, something went wrong.
 238  *
 239  * @param ph handle to reconnect
 240  */
 241 static void
 242 do_reconnect (struct GNUNET_ATS_PerformanceHandle *ph)
 243 {
 244   struct GNUNET_ATS_ReservationContext *rc;
 245   struct GNUNET_ATS_AddressListHandle *alh;
 246   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_zero;
 247
 248   if (NULL != ph->mq)
 249   {
 250     GNUNET_MQ_destroy (ph->mq);
 251     ph->mq = NULL;
 252   }
 253   while (NULL != (rc = ph->reservation_head))
 254   {
 255     GNUNET_CONTAINER_DLL_remove (ph->reservation_head,
 256                                  ph->reservation_tail,
 257                                  rc);
 258     if (NULL != rc->rcb)
 259       rc->rcb (rc->rcb_cls,
 260                NULL,
 261                0,
 262                GNUNET_TIME_UNIT_FOREVER_REL);
 263     GNUNET_free (rc);
 264   }
 265   bandwidth_zero.value__ = htonl (0);
 266   while (NULL != (alh = ph->addresslist_head))
 267   {
 268     GNUNET_CONTAINER_DLL_remove (ph->addresslist_head,
 269                                  ph->addresslist_tail,
 270                                  alh);
 271     if (NULL != alh->cb)
 272       alh->cb (alh->cb_cls,
 273                NULL,
 274                GNUNET_NO,
 275                bandwidth_zero,
 276                bandwidth_zero,
 277                NULL);
 278     GNUNET_free (alh);
 279   }
 280   if (NULL != ph->addr_info_cb)
 281   {
 282     /* Indicate reconnect */
 283     ph->addr_info_cb (ph->addr_info_cb_cls,
 284                       NULL,
 285                       GNUNET_NO,
 286                       bandwidth_zero,
 287                       bandwidth_zero,
 288                       NULL);
 289   }
 290   ph->backoff = GNUNET_TIME_STD_BACKOFF (ph->backoff);
 291   ph->task = GNUNET_SCHEDULER_add_delayed (ph->backoff,
 292                                            &reconnect_task,
 293                                            ph);
 294 }
 295
 296
 297 /**
 298  * We received a peer information message.  Validate and process it.
 299  *
 300  * @param cls our context with the callback
 301  * @param pi the message
 302  * @return #GNUNET_OK if the message was well-formed
 303  */
 304 static int
 305 check_peer_information (void *cls,
 306                         const struct PeerInformationMessage *pi)
 307 {
 308   const char *plugin_address;
 309   const char *plugin_name;
 310   uint16_t plugin_address_length;
 311   uint16_t plugin_name_length;
 312
 313   plugin_address_length = ntohs (pi->address_length);
 314   plugin_name_length = ntohs (pi->plugin_name_length);
 315   plugin_address = (const char *) &pi[1];
 316   plugin_name = &plugin_address[plugin_address_length];
 317   if ( (plugin_address_length + plugin_name_length
 318         + sizeof(struct PeerInformationMessage) != ntohs (pi->header.size)) ||
 319        (plugin_name[plugin_name_length - 1] != '\0'))
 320   {
 321     GNUNET_break(0);
 322     return GNUNET_SYSERR;
 323   }
 324   return GNUNET_OK;
 325 }
 326
 327
 328 /**
 329  * We received a peer information message.  Validate and process it.
 330  *
 331  * @param cls our context with the callback
 332  * @param pi the message
 333  * @return #GNUNET_OK if the message was well-formed
 334  */
 335 static void
 336 handle_peer_information (void *cls,
 337                          const struct PeerInformationMessage *pi)
 338 {
 339   struct GNUNET_ATS_PerformanceHandle *ph = cls;
 340   const char *plugin_address;
 341   const char *plugin_name;
 342   struct GNUNET_HELLO_Address address;
 343   uint16_t plugin_address_length;
 344   int addr_active;
 345   struct GNUNET_ATS_Properties prop;
 346
 347   if (NULL == ph->addr_info_cb)
 348     return;
 349   plugin_address_length = ntohs (pi->address_length);
 350   addr_active = (int) ntohl (pi->address_active);
 351   plugin_address = (const char *) &pi[1];
 352   plugin_name = &plugin_address[plugin_address_length];
 353
 354   GNUNET_ATS_properties_ntoh (&prop,
 355                               &pi->properties);
 356   address.peer = pi->peer;
 357   address.local_info = (enum GNUNET_HELLO_AddressInfo) ntohl (pi->address_local_info);
 358   address.address = plugin_address;
 359   address.address_length = plugin_address_length;
 360   address.transport_name = plugin_name;
 361   ph->addr_info_cb (ph->addr_info_cb_cls,
 362                     &address,
 363                     addr_active,
 364                     pi->bandwidth_out,
 365                     pi->bandwidth_in,
 366                     &prop);
 367 }
 368
 369
 370 /**
 371  * We received a reservation result message.  Validate and process it.
 372  *
 373  * @param cls our context with the callback
 374  * @param rr the message
 375  */
 376 static void
 377 handle_reservation_result (void *cls,
 378                            const struct ReservationResultMessage *rr)
 379 {
 380   struct GNUNET_ATS_PerformanceHandle *ph = cls;
 381   struct GNUNET_ATS_ReservationContext *rc;
 382   int32_t amount;
 383
 384   amount = ntohl (rr->amount);
 385   rc = ph->reservation_head;
 386   if (0 != GNUNET_memcmp (&rr->peer,
 387                    &rc->peer))
 388   {
 389     GNUNET_break(0);
 390     reconnect (ph);
 391     return;
 392   }
 393   GNUNET_CONTAINER_DLL_remove (ph->reservation_head,
 394                                ph->reservation_tail,
 395                                rc);
 396   if ( (0 == amount) ||
 397        (NULL != rc->rcb) )
 398   {
 399     /* tell client if not cancelled */
 400     if (NULL != rc->rcb)
 401       rc->rcb (rc->rcb_cls,
 402                &rr->peer,
 403                amount,
 404                GNUNET_TIME_relative_ntoh (rr->res_delay));
 405     GNUNET_free (rc);
 406     return;
 407   }
 408   /* amount non-zero, but client cancelled, consider undo! */
 409   if (GNUNET_YES != rc->undo)
 410   {
 411     GNUNET_free (rc);
 412     return; /* do not try to undo failed undos or negative amounts */
 413   }
 414   GNUNET_free (rc);
 415   (void) GNUNET_ATS_reserve_bandwidth (ph,
 416                                        &rr->peer,
 417                                        -amount,
 418                                        NULL, NULL);
 419 }
 420
 421
 422 /**
 423  * We received a PeerInformationMessage.  Validate it.
 424  *
 425  * @param cls our context with the callback
 426  * @param pi the message
 427  * @return #GNUNET_OK if the message was well-formed
 428  */
 429 static int
 430 check_address_list (void *cls,
 431                     const struct PeerInformationMessage *pi)
 432 {
 433   const char *plugin_address;
 434   const char *plugin_name;
 435   uint16_t plugin_address_length;
 436   uint16_t plugin_name_length;
 437
 438   plugin_address_length = ntohs (pi->address_length);
 439   plugin_name_length = ntohs (pi->plugin_name_length);
 440   plugin_address = (const char *) &pi[1];
 441   plugin_name = &plugin_address[plugin_address_length];
 442   if ( (plugin_address_length + plugin_name_length
 443         + sizeof (struct PeerInformationMessage) != ntohs (pi->header.size)) ||
 444        (plugin_name[plugin_name_length - 1] != '\0') )
 445   {
 446     GNUNET_break(0);
 447     return GNUNET_SYSERR;
 448   }
 449   return GNUNET_OK;
 450 }
 451
 452
 453 /**
 454  * We received a #GNUNET_MESSAGE_TYPE_ATS_ADDRESSLIST_RESPONSE.
 455  * Process it.
 456  *
 457  * @param cls our context with the callback
 458  * @param pi the message
 459  */
 460 static void
 461 handle_address_list (void *cls,
 462                      const struct PeerInformationMessage *pi)
 463 {
 464   struct GNUNET_ATS_PerformanceHandle *ph = cls;
 465   struct GNUNET_ATS_AddressListHandle *alh;
 466   struct GNUNET_ATS_AddressListHandle *next;
 467   const char *plugin_address;
 468   const char *plugin_name;
 469   struct GNUNET_HELLO_Address address;
 470   struct GNUNET_PeerIdentity allzeros;
 471   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_zero;
 472   struct GNUNET_ATS_Properties prop;
 473   uint16_t plugin_address_length;
 474   uint16_t plugin_name_length;
 475   uint32_t active;
 476   uint32_t id;
 477
 478   id = ntohl (pi->id);
 479   active = ntohl (pi->address_active);
 480   plugin_address_length = ntohs (pi->address_length);
 481   plugin_name_length = ntohs (pi->plugin_name_length);
 482   plugin_address = (const char *) &pi[1];
 483   plugin_name = &plugin_address[plugin_address_length];
 484   LOG (GNUNET_ERROR_TYPE_DEBUG,
 485        "Received ATS_ADDRESSLIST_RESPONSE message for peer %s and plugin %s\n",
 486        GNUNET_i2s (&pi->peer),
 487        plugin_name);
 488
 489   next = ph->addresslist_head;
 490   while (NULL != (alh = next))
 491   {
 492     next = alh->next;
 493     if (alh->id == id)
 494       break;
 495   }
 496   if (NULL == alh)
 497     return; /* was canceled */
 498
 499   memset (&allzeros, '\0', sizeof (allzeros));
 500   if ( (0 == GNUNET_is_zero (&pi->peer)) &&
 501        (0 == plugin_name_length) &&
 502        (0 == plugin_address_length) )
 503   {
 504     /* Done */
 505     LOG (GNUNET_ERROR_TYPE_DEBUG,
 506          "Received last message for ATS_ADDRESSLIST_RESPONSE\n");
 507     bandwidth_zero.value__ = htonl (0);
 508     GNUNET_CONTAINER_DLL_remove (ph->addresslist_head,
 509                                  ph->addresslist_tail,
 510                                  alh);
 511     if (NULL != alh->cb)
 512       alh->cb (alh->cb_cls,
 513                NULL,
 514                GNUNET_NO,
 515                bandwidth_zero,
 516                bandwidth_zero,
 517                NULL);
 518     GNUNET_free (alh);
 519     return;
 520   }
 521
 522   address.peer = pi->peer;
 523   address.address = plugin_address;
 524   address.address_length = plugin_address_length;
 525   address.transport_name = plugin_name;
 526   if ( ( (GNUNET_YES == alh->all_addresses) ||
 527          (GNUNET_YES == active) ) &&
 528        (NULL != alh->cb) )
 529   {
 530     GNUNET_ATS_properties_ntoh (&prop,
 531                                 &pi->properties);
 532     alh->cb (alh->cb_cls,
 533              &address,
 534              active,
 535              pi->bandwidth_out,
 536              pi->bandwidth_in,
 537              &prop);
 538   }
 539 }
 540
 541
 542 /**
 543  * Generic error handler, called with the appropriate error code and
 544  * the same closure specified at the creation of the message queue.
 545  * Not every message queue implementation supports an error handler.
 546  *
 547  * @param cls closure with the `struct GNUNET_ATS_PerformanceHandle *`
 548  * @param error error code
 549  */
 550 static void
 551 mq_error_handler (void *cls,
 552                   enum GNUNET_MQ_Error error)
 553 {
 554   struct GNUNET_ATS_PerformanceHandle *ph = cls;
 555
 556   do_reconnect (ph);
 557 }
 558
 559
 560 /**
 561  * Re-establish the connection to the ATS service.
 562  *
 563  * @param ph handle to use to re-connect.
 564  */
 565 static void
 566 reconnect (struct GNUNET_ATS_PerformanceHandle *ph)
 567 {
 568   struct GNUNET_MQ_MessageHandler handlers[] = {
 569     GNUNET_MQ_hd_var_size (peer_information,
 570                            GNUNET_MESSAGE_TYPE_ATS_PEER_INFORMATION,
 571                            struct PeerInformationMessage,
 572                            ph),
 573     GNUNET_MQ_hd_fixed_size (reservation_result,
 574                              GNUNET_MESSAGE_TYPE_ATS_RESERVATION_RESULT,
 575                              struct ReservationResultMessage,
 576                              ph),
 577     GNUNET_MQ_hd_var_size (address_list,
 578                            GNUNET_MESSAGE_TYPE_ATS_ADDRESSLIST_RESPONSE,
 579                            struct PeerInformationMessage,
 580                            ph),
 581     GNUNET_MQ_handler_end ()
 582   };
 583   struct GNUNET_MQ_Envelope *env;
 584   struct ClientStartMessage *init;
 585
 586   GNUNET_assert (NULL == ph->mq);
 587   ph->mq = GNUNET_CLIENT_connect (ph->cfg,
 588                                   "ats",
 589                                   handlers,
 590                                   &mq_error_handler,
 591                                   ph);
 592   if (NULL == ph->mq)
 593     return;
 594   env = GNUNET_MQ_msg (init,
 595                        GNUNET_MESSAGE_TYPE_ATS_START);
 596   init->start_flag = htonl ( (NULL == ph->addr_info_cb)
 597                              ? START_FLAG_PERFORMANCE_NO_PIC
 598                              : START_FLAG_PERFORMANCE_WITH_PIC);
 599   GNUNET_MQ_send (ph->mq,
 600                   env);
 601 }
 602
 603
 604 /**
 605  * Get handle to access performance API of the ATS subsystem.
 606  *
 607  * @param cfg configuration to use
 608  * @param addr_info_cb callback called when performance characteristics for
 609  *      an address change
 610  * @param addr_info_cb_cls closure for @a addr_info_cb
 611  * @return ats performance context
 612  */
 613 struct GNUNET_ATS_PerformanceHandle *
 614 GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 615                              GNUNET_ATS_AddressInformationCallback addr_info_cb,
 616                              void *addr_info_cb_cls)
 617 {
 618   struct GNUNET_ATS_PerformanceHandle *ph;
 619
 620   ph = GNUNET_new (struct GNUNET_ATS_PerformanceHandle);
 621   ph->cfg = cfg;
 622   ph->addr_info_cb = addr_info_cb;
 623   ph->addr_info_cb_cls = addr_info_cb_cls;
 624   reconnect (ph);
 625   if (NULL == ph->mq)
 626   {
 627     GNUNET_free (ph);
 628     return NULL;
 629   }
 630   return ph;
 631 }
 632
 633
 634 /**
 635  * Client is done using the ATS performance subsystem, release resources.
 636  *
 637  * @param ph handle
 638  */
 639 void
 640 GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph)
 641 {
 642   struct GNUNET_ATS_ReservationContext *rc;
 643   struct GNUNET_ATS_AddressListHandle *alh;
 644
 645   while (NULL != (alh = ph->addresslist_head))
 646   {
 647     GNUNET_CONTAINER_DLL_remove (ph->addresslist_head,
 648                                  ph->addresslist_tail,
 649                                  alh);
 650     GNUNET_free (alh);
 651   }
 652   while (NULL != (rc = ph->reservation_head))
 653   {
 654     GNUNET_CONTAINER_DLL_remove (ph->reservation_head,
 655                                  ph->reservation_tail,
 656                                  rc);
 657     GNUNET_break (NULL == rc->rcb);
 658     GNUNET_free (rc);
 659   }
 660   if (NULL != ph->task)
 661   {
 662     GNUNET_SCHEDULER_cancel (ph->task);
 663     ph->task = NULL;
 664   }
 665   if (NULL != ph->mq)
 666   {
 667     GNUNET_MQ_destroy (ph->mq);
 668     ph->mq = NULL;
 669   }
 670   GNUNET_free (ph);
 671 }
 672
 673
 674 /**
 675  * Reserve inbound bandwidth from the given peer.  ATS will look at
 676  * the current amount of traffic we receive from the peer and ensure
 677  * that the peer could add @a amount of data to its stream.
 678  *
 679  * @param ph performance handle
 680  * @param peer identifies the peer
 681  * @param amount reserve N bytes for receiving, negative
 682  *                amounts can be used to undo a (recent) reservation;
 683  * @param rcb function to call with the resulting reservation information
 684  * @param rcb_cls closure for @a rcb
 685  * @return NULL on error
 686  * @deprecated will be replaced soon
 687  */
 688 struct GNUNET_ATS_ReservationContext *
 689 GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph,
 690                               const struct GNUNET_PeerIdentity *peer,
 691                               int32_t amount,
 692                               GNUNET_ATS_ReservationCallback rcb,
 693                               void *rcb_cls)
 694 {
 695   struct GNUNET_ATS_ReservationContext *rc;
 696   struct GNUNET_MQ_Envelope *env;
 697   struct ReservationRequestMessage *m;
 698
 699   if (NULL == ph->mq)
 700     return NULL;
 701   rc = GNUNET_new (struct GNUNET_ATS_ReservationContext);
 702   rc->size = amount;
 703   rc->peer = *peer;
 704   rc->rcb = rcb;
 705   rc->rcb_cls = rcb_cls;
 706   if ( (NULL != rcb) &&
 707        (amount > 0) )
 708     rc->undo = GNUNET_YES;
 709   GNUNET_CONTAINER_DLL_insert_tail (ph->reservation_head,
 710                                     ph->reservation_tail,
 711                                     rc);
 712   env = GNUNET_MQ_msg (m,
 713                        GNUNET_MESSAGE_TYPE_ATS_RESERVATION_REQUEST);
 714   m->amount = htonl (amount);
 715   m->peer = *peer;
 716   GNUNET_MQ_send (ph->mq,
 717                   env);
 718   return rc;
 719 }
 720
 721
 722 /**
 723  * Cancel request for reserving bandwidth.
 724  *
 725  * @param rc context returned by the original #GNUNET_ATS_reserve_bandwidth() call
 726  */
 727 void
 728 GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc)
 729 {
 730   rc->rcb = NULL;
 731 }
 732
 733
 734 /**
 735  * Get information about addresses known to the ATS subsystem.
 736  *
 737  * @param ph the performance handle to use
 738  * @param peer peer idm can be NULL for all peers
 739  * @param all #GNUNET_YES to get information about all addresses or #GNUNET_NO to
 740  *        get only address currently used
 741  * @param infocb callback to call with the addresses,
 742  *        will callback with address == NULL when done
 743  * @param infocb_cls closure for @a infocb
 744  * @return ats performance context
 745  */
 746 struct GNUNET_ATS_AddressListHandle*
 747 GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *ph,
 748                                        const struct GNUNET_PeerIdentity *peer,
 749                                        int all,
 750                                        GNUNET_ATS_AddressInformationCallback infocb,
 751                                        void *infocb_cls)
 752 {
 753   struct GNUNET_ATS_AddressListHandle *alh;
 754   struct GNUNET_MQ_Envelope *env;
 755   struct AddressListRequestMessage *m;
 756
 757   if (NULL == ph->mq)
 758     return NULL;
 759   if (NULL == infocb)
 760   {
 761     GNUNET_break (0);
 762     return NULL;
 763   }
 764   alh = GNUNET_new (struct GNUNET_ATS_AddressListHandle);
 765   alh->id = ph->id++;
 766   alh->cb = infocb;
 767   alh->cb_cls = infocb_cls;
 768   alh->ph = ph;
 769   alh->all_addresses = all;
 770   if (NULL == peer)
 771   {
 772     alh->all_peers = GNUNET_YES;
 773   }
 774   else
 775   {
 776     alh->all_peers = GNUNET_NO;
 777     alh->peer = *peer;
 778   }
 779   GNUNET_CONTAINER_DLL_insert (ph->addresslist_head,
 780                                ph->addresslist_tail,
 781                                alh);
 782   env = GNUNET_MQ_msg (m,
 783                        GNUNET_MESSAGE_TYPE_ATS_ADDRESSLIST_REQUEST);
 784   m->all = htonl (all);
 785   m->id = htonl (alh->id);
 786   if (NULL != peer)
 787     m->peer = *peer;
 788   GNUNET_MQ_send (ph->mq,
 789                   env);
 790   return alh;
 791 }
 792
 793
 794 /**
 795  * Cancel a pending address listing operation
 796  *
 797  * @param alh the handle of the request to cancel
 798  */
 799 void
 800 GNUNET_ATS_performance_list_addresses_cancel (struct GNUNET_ATS_AddressListHandle *alh)
 801 {
 802   struct GNUNET_ATS_PerformanceHandle *ph = alh->ph;
 803
 804   GNUNET_CONTAINER_DLL_remove (ph->addresslist_head,
 805                                ph->addresslist_tail,
 806                                alh);
 807   GNUNET_free (alh);
 808 }
 809
 810
 811 /**
 812  * Convert a `enum GNUNET_ATS_PreferenceType` to a string
 813  *
 814  * @param type the preference type
 815  * @return a string or NULL if invalid
 816  */
 817 const char *
 818 GNUNET_ATS_print_preference_type (enum GNUNET_ATS_PreferenceKind type)
 819 {
 820   const char *prefs[] = GNUNET_ATS_PreferenceTypeString;
 821
 822   if (type < GNUNET_ATS_PREFERENCE_END)
 823     return prefs[type];
 824   return NULL;
 825 }
 826
 827
 828 /**
 829  * Change preferences for the given peer. Preference changes are forgotten if peers
 830  * disconnect.
 831  *
 832  * @param ph performance handle
 833  * @param peer identifies the peer
 834  * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the desired changes
 835  */
 836 void
 837 GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *ph,
 838                                           const struct GNUNET_PeerIdentity *peer,
 839                                           ...)
 840 {
 841   struct GNUNET_MQ_Envelope *env;
 842   struct ChangePreferenceMessage *m;
 843   uint32_t count;
 844   struct PreferenceInformation *pi;
 845   va_list ap;
 846   enum GNUNET_ATS_PreferenceKind kind;
 847
 848   if (NULL == ph->mq)
 849     return;
 850   count = 0;
 851   va_start(ap, peer);
 852   while (GNUNET_ATS_PREFERENCE_END !=
 853          (kind = GNUNET_VA_ARG_ENUM (ap, GNUNET_ATS_PreferenceKind) ))
 854   {
 855     switch (kind)
 856     {
 857     case GNUNET_ATS_PREFERENCE_BANDWIDTH:
 858       count++;
 859       (void) va_arg (ap, double);
 860       break;
 861     case GNUNET_ATS_PREFERENCE_LATENCY:
 862       count++;
 863       (void) va_arg (ap, double);
 864       break;
 865     default:
 866       GNUNET_assert(0);
 867     }
 868   }
 869   va_end(ap);
 870   env = GNUNET_MQ_msg_extra (m,
 871                              count * sizeof(struct PreferenceInformation),
 872                              GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_CHANGE);
 873   m->num_preferences = htonl (count);
 874   m->peer = *peer;
 875   pi = (struct PreferenceInformation *) &m[1];
 876   count = 0;
 877   va_start(ap, peer);
 878   while (GNUNET_ATS_PREFERENCE_END != (kind =
 879       GNUNET_VA_ARG_ENUM (ap, GNUNET_ATS_PreferenceKind) ))
 880   {
 881     pi[count].preference_kind = htonl (kind);
 882     switch (kind)
 883     {
 884     case GNUNET_ATS_PREFERENCE_BANDWIDTH:
 885       pi[count].preference_value = (float) va_arg (ap, double);
 886
 887       count++;
 888       break;
 889     case GNUNET_ATS_PREFERENCE_LATENCY:
 890       pi[count].preference_value = (float) va_arg (ap, double);
 891
 892       count++;
 893       break;
 894     default:
 895       GNUNET_assert(0);
 896     }
 897   }
 898   va_end(ap);
 899   GNUNET_MQ_send (ph->mq,
 900                   env);
 901 }
 902
 903
 904 /**
 905  * Send feedback to ATS on how good a the requirements for a peer and a
 906  * preference is satisfied by ATS
 907  *
 908  * @param ph performance handle
 909  * @param scope the time interval this valid for: [now - scope .. now]
 910  * @param peer identifies the peer
 911  * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the desired changes
 912  */
 913 void
 914 GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph,
 915                                       const struct GNUNET_PeerIdentity *peer,
 916                                       const struct GNUNET_TIME_Relative scope,
 917                                       ...)
 918 {
 919   struct GNUNET_MQ_Envelope *env;
 920   struct FeedbackPreferenceMessage *m;
 921   uint32_t count;
 922   struct PreferenceInformation *pi;
 923   va_list ap;
 924   enum GNUNET_ATS_PreferenceKind kind;
 925
 926   if (NULL == ph->mq)
 927     return;
 928   count = 0;
 929   va_start(ap, scope);
 930   while (GNUNET_ATS_PREFERENCE_END !=
 931          (kind = GNUNET_VA_ARG_ENUM (ap, GNUNET_ATS_PreferenceKind) ))
 932   {
 933     switch (kind)
 934     {
 935     case GNUNET_ATS_PREFERENCE_BANDWIDTH:
 936       count++;
 937       (void) va_arg (ap, double);
 938       break;
 939     case GNUNET_ATS_PREFERENCE_LATENCY:
 940       count++;
 941       (void) va_arg (ap, double);
 942       break;
 943     default:
 944       GNUNET_assert(0);
 945     }
 946   }
 947   va_end(ap);
 948   env = GNUNET_MQ_msg_extra (m,
 949                              count * sizeof(struct PreferenceInformation),
 950                              GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_FEEDBACK);
 951   m->scope = GNUNET_TIME_relative_hton (scope);
 952   m->num_feedback = htonl (count);
 953   m->peer = *peer;
 954   pi = (struct PreferenceInformation *) &m[1];
 955   count = 0;
 956   va_start(ap, scope);
 957   while (GNUNET_ATS_PREFERENCE_END != (kind =
 958       GNUNET_VA_ARG_ENUM (ap, GNUNET_ATS_PreferenceKind) ))
 959   {
 960     pi[count].preference_kind = htonl (kind);
 961     switch (kind)
 962     {
 963     case GNUNET_ATS_PREFERENCE_BANDWIDTH:
 964       pi[count].preference_value = (float) va_arg (ap, double);
 965
 966       count++;
 967       break;
 968     case GNUNET_ATS_PREFERENCE_LATENCY:
 969       pi[count].preference_value = (float) va_arg (ap, double);
 970
 971       count++;
 972       break;
 973     default:
 974       GNUNET_assert(0);
 975     }
 976   }
 977   va_end(ap);
 978   GNUNET_MQ_send (ph->mq,
 979                   env);
 980 }
 981
 982 /* end of ats_api_performance.c */