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