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