src/ats/gnunet-service-ats-solver_proportional.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2011 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 ats/gnunet-service-ats-solver_proportional.h
  23  * @brief ATS proportional solver
  24  * @author Matthias Wachs
  25  * @author Christian Grothoff
  26  */
  27 #include "platform.h"
  28 #include "gnunet_statistics_service.h"
  29 #include "gnunet-service-ats_addresses.h"
  30
  31 /**
  32  * ATS proportional solver
  33  *
  34  * General description
  35  */
  36
  37 /**
  38  * Changes the preferences for a peer in the problem
  39  *
  40  * @param solver the solver handle
  41  * @param peer the peer to change the preference for
  42  * @param kind the kind to change the preference
  43  * @param pref_rel the normalized preference value for this kind over all clients
  44  */
  45 void
  46 GAS_proportional_address_change_preference (void *solver,
  47                                                                                         const struct GNUNET_PeerIdentity *peer,
  48                                                                                         enum GNUNET_ATS_PreferenceKind kind,
  49                                                                                         double pref_rel);
  50
  51
  52 /**
  53  * Get application feedback for a peer
  54  *
  55  * @param solver the solver handle
  56  * @param application the application
  57  * @param peer the peer to change the preference for
  58  * @param scope the time interval for this feedback: [now - scope .. now]
  59  * @param kind the kind to change the preference
  60  * @param score the score
  61  */
  62 void
  63 GAS_proportional_address_preference_feedback (void *solver,
  64                                                                                         void *application,
  65                                                                                         const struct GNUNET_PeerIdentity *peer,
  66                                                                                   const struct GNUNET_TIME_Relative scope,
  67                                                                                         enum GNUNET_ATS_PreferenceKind kind,
  68                                                                                         double score);
  69
  70
  71 /**
  72  * Init the proportional problem solver
  73  *
  74  * Quotas:
  75  * network[i] contains the network type as type GNUNET_ATS_NetworkType[i]
  76  * out_quota[i] contains outbound quota for network type i
  77  * in_quota[i] contains inbound quota for network type i
  78  *
  79  * Example
  80  * network = {GNUNET_ATS_NET_UNSPECIFIED, GNUNET_ATS_NET_LOOPBACK, GNUNET_ATS_NET_LAN, GNUNET_ATS_NET_WAN, GNUNET_ATS_NET_WLAN}
  81  * network[2]   == GNUNET_ATS_NET_LAN
  82  * out_quota[2] == 65353
  83  * in_quota[2]  == 65353
  84  *
  85  * @param cfg configuration handle
  86  * @param stats the GNUNET_STATISTICS handle
  87  * @param network array of GNUNET_ATS_NetworkType with length dest_length
  88  * @param addresses hashmap containing all addresses
  89  * @param out_quota array of outbound quotas
  90  * @param in_quota array of outbound quota
  91  * @param dest_length array length for quota arrays
  92  * @param bw_changed_cb callback for changed bandwidth amounts
  93  * @param bw_changed_cb_cls cls for callback
  94  * @param get_preference callback to get relative preferences for a peer
  95  * @param get_preference_cls cls for callback to get relative preferences
  96  * @param get_properties_cls for callback to get relative properties
  97  * @param get_properties_cls cls for callback to get relative properties
  98  * @return handle for the solver on success, NULL on fail
  99  */
 100 void *
 101 GAS_proportional_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 102                      const struct GNUNET_STATISTICS_Handle *stats,
 103                      const struct GNUNET_CONTAINER_MultiHashMap *addresses,
 104                      int *network,
 105                      unsigned long long *out_quota,
 106                      unsigned long long *in_quota,
 107                      int dest_length,
 108                      GAS_bandwidth_changed_cb bw_changed_cb,
 109                      void *bw_changed_cb_cls,
 110                      GAS_get_preferences get_preference,
 111                      void *get_preference_cls,
 112                      GAS_get_properties get_properties,
 113                      void *get_properties_cls);
 114
 115 /**
 116  * Shutdown the proportional problem solver
 117  *
 118  * @param solver the respective handle to shutdown
 119  */
 120 void
 121 GAS_proportional_done (void * solver);
 122
 123
 124 /**
 125  * Add a single address within a network to the solver
 126  *
 127  * @param solver the solver Handle
 128  * @param address the address to add
 129  * @param network network type of this address
 130  */
 131 void
 132 GAS_proportional_address_add (void *solver,
 133                                                         struct ATS_Address *address,
 134                                                         uint32_t network);
 135
 136
 137 /**
 138  * Transport properties for this address have changed
 139  *
 140  * @param solver solver handle
 141  * @param address the address
 142  * @param type the ATSI type in HBO
 143  * @param abs_value the absolute value of the property
 144  * @param rel_value the normalized value
 145  */
 146 void
 147 GAS_proportional_address_property_changed (void *solver,
 148                                                                                                                         struct ATS_Address *address,
 149                                                                                                                         uint32_t type,
 150                                                                                                                         uint32_t abs_value,
 151                                                                                                                         double rel_value);
 152
 153
 154 /**
 155  * Transport session for this address has changed
 156  *
 157  * NOTE: values in addresses are already updated
 158  *
 159  * @param solver solver handle
 160  * @param address the address
 161  * @param cur_session the current session
 162  * @param new_session the new session
 163  */
 164 void
 165 GAS_proportional_address_session_changed (void *solver,
 166                                                                                                                         struct ATS_Address *address,
 167                                                                                                                         uint32_t cur_session,
 168                                                                                                                         uint32_t new_session);
 169
 170
 171 /**
 172  * Usage for this address has changed
 173  *
 174  * NOTE: values in addresses are already updated
 175  *
 176  * @param solver solver handle
 177  * @param address the address
 178  * @param in_use usage state
 179  */
 180 void
 181 GAS_proportional_address_inuse_changed (void *solver,
 182                                                                                                                         struct ATS_Address *address,
 183                                                                                                                         int in_use);
 184
 185 /**
 186  * Network scope for this address has changed
 187  *
 188  * NOTE: values in addresses are already updated
 189  *
 190  * @param solver solver handle
 191  * @param address the address
 192  * @param current_network the current network
 193  * @param new_network the new network
 194  */
 195 void
 196 GAS_proportional_address_change_network (void *solver,
 197                                                                                                                                            struct ATS_Address *address,
 198                                                                                                                                            uint32_t current_network,
 199                                                                                                                                            uint32_t new_network);
 200
 201 /**
 202  * Remove an address from the solver
 203  *
 204  * @param solver the solver handle
 205  * @param address the address to remove
 206  * @param session_only delete only session not whole address
 207  */
 208 void
 209 GAS_proportional_address_delete (void *solver,
 210     struct ATS_Address *address, int session_only);
 211
 212
 213 /**
 214  * Start a bulk operation
 215  *
 216  * @param solver the solver
 217  */
 218 void
 219 GAS_proportional_bulk_start (void *solver);
 220
 221
 222 /**
 223  * Bulk operation done
 224  */
 225 void
 226 GAS_proportional_bulk_stop (void *solver);
 227
 228 /**
 229  * Stop notifying about address and bandwidth changes for this peer
 230  *
 231  * @param solver the proportional handle
 232  * @param peer the peer
 233  */
 234 void
 235 GAS_proportional_stop_get_preferred_address (void *solver,
 236                                      const struct GNUNET_PeerIdentity *peer);
 237
 238
 239 /**
 240  * Get the prefered address for a specific peer
 241  *
 242  * @param solver the solver handle
 243  * @param peer the identity of the peer
 244  */
 245 const struct ATS_Address *
 246 GAS_proportional_get_preferred_address (void *solver,
 247                                const struct GNUNET_PeerIdentity *peer);
 248
 249 /* end of gnunet-service-ats-solver_proportional.c */