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