src/ats/plugin_ats_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/plugin_ats_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_ats_plugin.h"
  30 #include "gnunet-service-ats_addresses.h"
  31
  32 /**
  33  * ATS proportional solver
  34  *
  35  * General description
  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_proportional_address_change_preference (void *solver,
  48     const struct GNUNET_PeerIdentity *peer, enum GNUNET_ATS_PreferenceKind kind,
  49     double pref_rel);
  50
  51 /**
  52  * Get application feedback for a peer
  53  *
  54  * @param solver the solver handle
  55  * @param application the application
  56  * @param peer the peer to change the preference for
  57  * @param scope the time interval for this feedback: [now - scope .. now]
  58  * @param kind the kind to change the preference
  59  * @param score the score
  60  */
  61 void
  62 GAS_proportional_address_preference_feedback (void *solver, void *application,
  63     const struct GNUNET_PeerIdentity *peer,
  64     const struct GNUNET_TIME_Relative scope,
  65     enum GNUNET_ATS_PreferenceKind kind, double score);
  66
  67 /**
  68  * Shutdown the proportional problem solver
  69  *
  70  * @param solver the respective handle to shutdown
  71  */
  72 void
  73 GAS_proportional_done (void * solver);
  74
  75 /**
  76  * Add a single address within a network to the solver
  77  *
  78  * @param solver the solver Handle
  79  * @param address the address to add
  80  * @param network network type of this address
  81  */
  82 void
  83 GAS_proportional_address_add (void *solver, struct ATS_Address *address,
  84     uint32_t network);
  85
  86 /**
  87  * Transport properties for this address have changed
  88  *
  89  * @param solver solver handle
  90  * @param address the address
  91  * @param type the ATSI type in HBO
  92  * @param abs_value the absolute value of the property
  93  * @param rel_value the normalized value
  94  */
  95 void
  96 GAS_proportional_address_property_changed (void *solver,
  97     struct ATS_Address *address, uint32_t type, uint32_t abs_value,
  98     double rel_value);
  99
 100 /**
 101  * Transport session for this address has changed
 102  *
 103  * NOTE: values in addresses are already updated
 104  *
 105  * @param solver solver handle
 106  * @param address the address
 107  * @param cur_session the current session
 108  * @param new_session the new session
 109  */
 110 void
 111 GAS_proportional_address_session_changed (void *solver,
 112     struct ATS_Address *address, uint32_t cur_session, uint32_t new_session);
 113
 114 /**
 115  * Usage for this address has changed
 116  *
 117  * NOTE: values in addresses are already updated
 118  *
 119  * @param solver solver handle
 120  * @param address the address
 121  * @param in_use usage state
 122  */
 123 void
 124 GAS_proportional_address_inuse_changed (void *solver,
 125     struct ATS_Address *address, int in_use);
 126
 127 /**
 128  * Network scope for this address has changed
 129  *
 130  * NOTE: values in addresses are already updated
 131  *
 132  * @param solver solver handle
 133  * @param address the address
 134  * @param current_network the current network
 135  * @param new_network the new network
 136  */
 137 void
 138 GAS_proportional_address_change_network (void *solver,
 139     struct ATS_Address *address, uint32_t current_network, uint32_t new_network);
 140
 141 /**
 142  * Remove an address from the solver
 143  *
 144  * @param solver the solver handle
 145  * @param address the address to remove
 146  * @param session_only delete only session not whole address
 147  */
 148 void
 149 GAS_proportional_address_delete (void *solver, struct ATS_Address *address,
 150     int session_only);
 151
 152 /**
 153  * Start a bulk operation
 154  *
 155  * @param solver the solver
 156  */
 157 void
 158 GAS_proportional_bulk_start (void *solver);
 159
 160 /**
 161  * Bulk operation done
 162  */
 163 void
 164 GAS_proportional_bulk_stop (void *solver);
 165
 166 /**
 167  * Stop notifying about address and bandwidth changes for this peer
 168  *
 169  * @param solver the proportional handle
 170  * @param peer the peer
 171  */
 172 void
 173 GAS_proportional_stop_get_preferred_address (void *solver,
 174     const struct GNUNET_PeerIdentity *peer);
 175
 176 /**
 177  * Get the prefered address for a specific peer
 178  *
 179  * @param solver the solver handle
 180  * @param peer the identity of the peer
 181  */
 182 const struct ATS_Address *
 183 GAS_proportional_get_preferred_address (void *solver,
 184     const struct GNUNET_PeerIdentity *peer);
 185
 186 /* end of plugin_ats_proportional.h */