src/ats/gnunet-service-ats_plugins.h

   1 /*
   2    This file is part of GNUnet.
   3    Copyright (C) 2011-2014 GNUnet e.V.
   4
   5    GNUnet is free software: you can redistribute it and/or modify it
   6    under the terms of the GNU Affero General Public License as published
   7    by the Free Software Foundation, either version 3 of the License,
   8    or (at your 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    Affero General Public License for more details.
  14
  15    You should have received a copy of the GNU Affero General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  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  */
  72 void
  73 GAS_plugin_notify_property_changed(struct ATS_Address *address);
  74
  75
  76 /**
  77  * Tell the solver that the given address can now be used
  78  * for talking to the respective peer.
  79  *
  80  * @param new_address the new address
  81  * @param addr_net network scope the address is in
  82  */
  83 void
  84 GAS_plugin_new_address(struct ATS_Address *new_address);
  85
  86
  87 /**
  88  * Tell the solver that the given address is no longer valid
  89  * can cannot be used any longer.
  90  *
  91  * @param address address that was deleted
  92  */
  93 void
  94 GAS_plugin_delete_address(struct ATS_Address *address);
  95
  96
  97 /**
  98  * Tell the solver that the given client has expressed its
  99  * appreciation for the past performance of a given connection.
 100  *
 101  * @param application client providing the feedback
 102  * @param peer peer the feedback is about
 103  * @param scope timeframe the feedback applies to
 104  * @param kind performance property the feedback relates to
 105  * @param score_abs degree of the appreciation
 106  */
 107 void
 108 GAS_plugin_notify_feedback(struct GNUNET_SERVICE_Client *application,
 109                            const struct GNUNET_PeerIdentity *peer,
 110                            const struct GNUNET_TIME_Relative scope,
 111                            enum GNUNET_ATS_PreferenceKind kind,
 112                            float score_abs);
 113
 114
 115 /**
 116  * Stop instant solving, there are many state updates
 117  * happening in bulk right now.
 118  */
 119 void
 120 GAS_plugin_solver_lock(void);
 121
 122
 123 /**
 124  * Resume instant solving, we are done with the bulk state updates.
 125  */
 126 void
 127 GAS_plugin_solver_unlock(void);
 128
 129
 130 /**
 131  * Notify the plugin that a request to connect to
 132  * a particular peer was given to us.
 133  *
 134  * @param pid identity of peer we now care about
 135  */
 136 void
 137 GAS_plugin_request_connect_start(const struct GNUNET_PeerIdentity *pid);
 138
 139
 140 /**
 141  * Notify the plugin that a request to connect to
 142  * a particular peer was dropped.
 143  *
 144  * @param pid identity of peer we care now less about
 145  */
 146 void
 147 GAS_plugin_request_connect_stop(const struct GNUNET_PeerIdentity *pid);
 148
 149
 150 #endif