src/rps/rps-sampler_common.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C)
   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
  19 /**
  20  * @file rps/rps-sampler_common.h
  21  * @brief Code common to client and service sampler
  22  * @author Julius Bünger
  23  */
  24
  25 #ifndef RPS_SAMPLER_COMMON_H
  26 #define RPS_SAMPLER_COMMON_H
  27
  28 #include "platform.h"
  29 #include "gnunet_util_lib.h"
  30 #include "gnunet_statistics_service.h"
  31
  32 #include "gnunet-service-rps_sampler_elem.h"
  33
  34 #include <math.h>
  35 #include <inttypes.h>
  36
  37 #include "rps-test_util.h"
  38
  39
  40 /**
  41  * Callback that is called from _get_rand_peer() when the PeerID is ready.
  42  *
  43  * @param cls the closure given alongside this function.
  44  * @param id the PeerID that was returned
  45  */
  46 typedef void
  47 (*RPS_sampler_rand_peer_ready_cont) (void *cls,
  48                                      const struct GNUNET_PeerIdentity *id);
  49
  50
  51 /**
  52  * Type of function used to differentiate between modified and not modified
  53  * Sampler.
  54  */
  55 typedef void
  56 (*RPS_get_peers_type) (void *cls);
  57
  58
  59 /**
  60  * Callback that is called from _get_n_rand_peers() when the PeerIDs are ready.
  61  *
  62  * @param cls the closure given alongside this function.
  63  * @param ids the PeerIDs that were returned
  64  *        to be freed
  65  */
  66   typedef void
  67 (*RPS_sampler_n_rand_peers_ready_cb) (const struct GNUNET_PeerIdentity *ids,
  68                                       uint32_t num_peers,
  69                                       void *cls);
  70
  71
  72 /**
  73  * @brief Callback called each time a new peer was put into the sampler
  74  *
  75  * @param cls A possibly given closure
  76  */
  77 typedef void
  78 (*SamplerNotifyUpdateCB) (void *cls);
  79
  80
  81 /**
  82  * Closure for #sampler_mod_get_rand_peer() and #sampler_get_rand_peer
  83  */
  84 struct GetPeerCls
  85 {
  86   /**
  87    * DLL
  88    */
  89   struct GetPeerCls *next;
  90   struct GetPeerCls *prev;
  91
  92   /**
  93    * The #RPS_SamplerRequestHandle this single request belongs to.
  94    */
  95   struct RPS_SamplerRequestHandle *req_handle;
  96
  97   /**
  98    * The task for this function.
  99    */
 100   struct GNUNET_SCHEDULER_Task *get_peer_task;
 101
 102   /**
 103    * @brief Context to the given callback.
 104    */
 105   struct SamplerNotifyUpdateCTX *notify_ctx;
 106
 107   /**
 108    * The callback
 109    */
 110   RPS_sampler_rand_peer_ready_cont cont;
 111
 112   /**
 113    * The closure to the callback @e cont
 114    */
 115   void *cont_cls;
 116
 117   /**
 118    * The address of the id to be stored at
 119    */
 120   struct GNUNET_PeerIdentity *id;
 121 };
 122
 123
 124 /**
 125  * Sampler with its own array of SamplerElements
 126  */
 127 struct RPS_Sampler
 128 {
 129   /**
 130    * Number of sampler elements we hold.
 131    */
 132   unsigned int sampler_size;
 133   //size_t size;
 134
 135   /**
 136    * All sampler elements in one array.
 137    */
 138   struct RPS_SamplerElement **sampler_elements;
 139
 140   /**
 141    * Maximum time a round takes
 142    *
 143    * Used in the context of RPS
 144    */
 145   struct GNUNET_TIME_Relative max_round_interval;
 146
 147   /**
 148    * Stores the function to return peers. Which one it is depends on whether
 149    * the Sampler is the modified one or not.
 150    */
 151   RPS_get_peers_type get_peers;
 152
 153   /**
 154    * Head and tail for the DLL to store the #RPS_SamplerRequestHandle
 155    */
 156   struct RPS_SamplerRequestHandle *req_handle_head;
 157   struct RPS_SamplerRequestHandle *req_handle_tail;
 158
 159   struct SamplerNotifyUpdateCTX *notify_ctx_head;
 160   struct SamplerNotifyUpdateCTX *notify_ctx_tail;
 161 };
 162
 163
 164 /**
 165  * @brief Add a callback that will be called when the next peer is inserted
 166  * into the sampler
 167  *
 168  * @param sampler The sampler on which update it will be called
 169  * @param notify_cb The callback
 170  * @param cls Closure given to the callback
 171  *
 172  * @return The context containing callback and closure
 173  */
 174 struct SamplerNotifyUpdateCTX *
 175 sampler_notify_on_update (struct RPS_Sampler *sampler,
 176                           SamplerNotifyUpdateCB notify_cb,
 177                           void *cls);
 178
 179
 180 /**
 181  * Update every sampler element of this sampler with given peer
 182  *
 183  * @param sampler the sampler to update.
 184  * @param id the PeerID that is put in the sampler
 185  */
 186   void
 187 RPS_sampler_update (struct RPS_Sampler *sampler,
 188                     const struct GNUNET_PeerIdentity *id);
 189
 190
 191 /**
 192  * Reinitialise all previously initialised sampler elements with the given value.
 193  *
 194  * Used to get rid of a PeerID.
 195  *
 196  * @param sampler the sampler to reinitialise a sampler element in.
 197  * @param id the id of the sampler elements to update.
 198  */
 199   void
 200 RPS_sampler_reinitialise_by_value (struct RPS_Sampler *sampler,
 201                                    const struct GNUNET_PeerIdentity *id);
 202
 203
 204 /**
 205  * Get the size of the sampler.
 206  *
 207  * @param sampler the sampler to return the size of.
 208  * @return the size of the sampler
 209  */
 210 unsigned int
 211 RPS_sampler_get_size (struct RPS_Sampler *sampler);
 212
 213
 214 /**
 215  * Grow or shrink the size of the sampler.
 216  *
 217  * @param sampler the sampler to resize.
 218  * @param new_size the new size of the sampler
 219  */
 220 void
 221 RPS_sampler_resize (struct RPS_Sampler *sampler, unsigned int new_size);
 222
 223
 224 /**
 225  * Get n random peers out of the sampled peers.
 226  *
 227  * We might want to reinitialise this sampler after giving the
 228  * corrsponding peer to the client.
 229  * Random with or without consumption?
 230  *
 231  * @param sampler the sampler to get peers from.
 232  * @param cb callback that will be called once the ids are ready.
 233  * @param cls closure given to @a cb
 234  * @param for_client #GNUNET_YES if result is used for client,
 235  *                   #GNUNET_NO if used internally
 236  * @param num_peers the number of peers requested
 237  */
 238 struct RPS_SamplerRequestHandle *
 239 RPS_sampler_get_n_rand_peers (struct RPS_Sampler *sampler,
 240                               uint32_t num_peers,
 241                               RPS_sampler_n_rand_peers_ready_cb cb,
 242                               void *cls);
 243
 244
 245 /**
 246  * Counts how many Samplers currently hold a given PeerID.
 247  *
 248  * @param sampler the sampler to count ids in.
 249  * @param id the PeerID to count.
 250  *
 251  * @return the number of occurrences of id.
 252  */
 253   uint32_t
 254 RPS_sampler_count_id (struct RPS_Sampler *sampler,
 255                       const struct GNUNET_PeerIdentity *id);
 256
 257
 258 /**
 259  * Cancle a request issued through #RPS_sampler_n_rand_peers_ready_cb.
 260  *
 261  * @param req_handle the handle to the request
 262  */
 263 void
 264 RPS_sampler_request_cancel (struct RPS_SamplerRequestHandle *req_handle);
 265
 266
 267 /**
 268  * Cleans the sampler.
 269  */
 270   void
 271 RPS_sampler_destroy (struct RPS_Sampler *sampler);
 272
 273 #endif /* RPS_SAMPLER_COMMON_H */
 274 /* end of rps-sampler_common.h */