src/ats/gnunet-service-ats_plugins.h

   1 /*
   2  This file is part of GNUnet.
   3  Copyright (C) 2011-2014 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_plugins.h
  23  * @brief ats service plugin management
  24  * @author Matthias Wachs
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_SERVICE_ATS_PLUGINS_H
  28 #define GNUNET_SERVICE_ATS_PLUGINS_H
  29
  30 #include "gnunet-service-ats_addresses.h"
  31
  32
  33 /**
  34  * Initialize address subsystem. The addresses subsystem manages the addresses
  35  * known and current performance information. It has a solver component
  36  * responsible for the resource allocation. It tells the solver about changes
  37  * and receives updates when the solver changes the ressource allocation.
  38  *
  39  * @param cfg configuration to use
  40  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (failed to load
  41  *         solver plugin)
  42  */
  43 int
  44 GAS_plugin_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
  45
  46
  47 /**
  48  * Shutdown address subsystem.
  49  */
  50 void
  51 GAS_plugin_done (void);
  52
  53
  54 /**
  55  * The preference changed for a peer, update solver.
  56  *
  57  * @param peer the peer
  58  * @param kind the ATS kind
  59  * @param pref_rel the new relative preference value
  60  */
  61 void
  62 GAS_plugin_notify_preference_changed (const struct GNUNET_PeerIdentity *peer,
  63                                       enum GNUNET_ATS_PreferenceKind kind,
  64                                       double pref_rel);
  65
  66
  67 /**
  68  * The relative value for a property changed
  69  *
  70  * @param address the peer
  71  * @param type the ATS type
  72  * @param prop_rel the new relative property value
  73  */
  74 void
  75 GAS_plugin_notify_property_changed (struct ATS_Address *address,
  76                                     enum GNUNET_ATS_Property type,
  77                                     double prop_rel);
  78
  79
  80 /**
  81  * Tell the solver that the given address can now be used
  82  * for talking to the respective peer.
  83  *
  84  * @param new_address the new address
  85  * @param addr_net network scope the address is in
  86  * @param atsi performance data for the address
  87  * @param atsi_count size of the @a atsi array
  88  */
  89 void
  90 GAS_plugin_new_address (struct ATS_Address *new_address,
  91                         enum GNUNET_ATS_Network_Type addr_net,
  92                         const struct GNUNET_ATS_Information *atsi,
  93                         uint32_t atsi_count);
  94
  95
  96 /**
  97  * Tell the solver that the given address is no longer valid
  98  * can cannot be used any longer.
  99  *
 100  * @param address address that was deleted
 101  */
 102 void
 103 GAS_plugin_delete_address (struct ATS_Address *address);
 104
 105
 106 /**
 107  * Tell the solver that the given client has expressed its
 108  * appreciation for the past performance of a given connection.
 109  *
 110  * @param application client providing the feedback
 111  * @param peer peer the feedback is about
 112  * @param scope timeframe the feedback applies to
 113  * @param kind performance property the feedback relates to
 114  * @param score_abs degree of the appreciation
 115  */
 116 void
 117 GAS_plugin_notify_feedback (struct GNUNET_SERVER_Client *application,
 118                             const struct GNUNET_PeerIdentity *peer,
 119                             const struct GNUNET_TIME_Relative scope,
 120                             enum GNUNET_ATS_PreferenceKind kind,
 121                             float score_abs);
 122
 123
 124 /**
 125  * Stop instant solving, there are many state updates
 126  * happening in bulk right now.
 127  */
 128 void
 129 GAS_plugin_solver_lock (void);
 130
 131
 132 /**
 133  * Resume instant solving, we are done with the bulk state updates.
 134  */
 135 void
 136 GAS_plugin_solver_unlock (void);
 137
 138
 139 /**
 140  * Notify the plugin that a request to connect to
 141  * a particular peer was given to us.
 142  *
 143  * @param pid identity of peer we now care about
 144  */
 145 void
 146 GAS_plugin_request_connect_start (const struct GNUNET_PeerIdentity *pid);
 147
 148
 149 /**
 150  * Notify the plugin that a request to connect to
 151  * a particular peer was dropped.
 152  *
 153  * @param pid identity of peer we care now less about
 154  */
 155 void
 156 GAS_plugin_request_connect_stop (const struct GNUNET_PeerIdentity *pid);
 157
 158
 159 #endif