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   #ifdef TO_FILE
 162   /**
 163    * File name to log to
 164    */
 165   char *file_name;
 166   #endif /* TO_FILE */
 167 };
 168
 169
 170 /**
 171  * @brief Add a callback that will be called when the next peer is inserted
 172  * into the sampler
 173  *
 174  * @param sampler The sampler on which update it will be called
 175  * @param notify_cb The callback
 176  * @param cls Closure given to the callback
 177  *
 178  * @return The context containing callback and closure
 179  */
 180 struct SamplerNotifyUpdateCTX *
 181 sampler_notify_on_update (struct RPS_Sampler *sampler,
 182                           SamplerNotifyUpdateCB notify_cb,
 183                           void *cls);
 184
 185
 186 /**
 187  * Update every sampler element of this sampler with given peer
 188  *
 189  * @param sampler the sampler to update.
 190  * @param id the PeerID that is put in the sampler
 191  */
 192   void
 193 RPS_sampler_update (struct RPS_Sampler *sampler,
 194                     const struct GNUNET_PeerIdentity *id);
 195
 196
 197 /**
 198  * Reinitialise all previously initialised sampler elements with the given value.
 199  *
 200  * Used to get rid of a PeerID.
 201  *
 202  * @param sampler the sampler to reinitialise a sampler element in.
 203  * @param id the id of the sampler elements to update.
 204  */
 205   void
 206 RPS_sampler_reinitialise_by_value (struct RPS_Sampler *sampler,
 207                                    const struct GNUNET_PeerIdentity *id);
 208
 209
 210 /**
 211  * Get the size of the sampler.
 212  *
 213  * @param sampler the sampler to return the size of.
 214  * @return the size of the sampler
 215  */
 216 unsigned int
 217 RPS_sampler_get_size (struct RPS_Sampler *sampler);
 218
 219
 220 /**
 221  * Grow or shrink the size of the sampler.
 222  *
 223  * @param sampler the sampler to resize.
 224  * @param new_size the new size of the sampler
 225  */
 226 void
 227 RPS_sampler_resize (struct RPS_Sampler *sampler, unsigned int new_size);
 228
 229
 230 /**
 231  * Get n random peers out of the sampled peers.
 232  *
 233  * We might want to reinitialise this sampler after giving the
 234  * corrsponding peer to the client.
 235  * Random with or without consumption?
 236  *
 237  * @param sampler the sampler to get peers from.
 238  * @param cb callback that will be called once the ids are ready.
 239  * @param cls closure given to @a cb
 240  * @param for_client #GNUNET_YES if result is used for client,
 241  *                   #GNUNET_NO if used internally
 242  * @param num_peers the number of peers requested
 243  */
 244 struct RPS_SamplerRequestHandle *
 245 RPS_sampler_get_n_rand_peers (struct RPS_Sampler *sampler,
 246                               uint32_t num_peers,
 247                               RPS_sampler_n_rand_peers_ready_cb cb,
 248                               void *cls);
 249
 250
 251 /**
 252  * Counts how many Samplers currently hold a given PeerID.
 253  *
 254  * @param sampler the sampler to count ids in.
 255  * @param id the PeerID to count.
 256  *
 257  * @return the number of occurrences of id.
 258  */
 259   uint32_t
 260 RPS_sampler_count_id (struct RPS_Sampler *sampler,
 261                       const struct GNUNET_PeerIdentity *id);
 262
 263
 264 /**
 265  * Cancle a request issued through #RPS_sampler_n_rand_peers_ready_cb.
 266  *
 267  * @param req_handle the handle to the request
 268  */
 269 void
 270 RPS_sampler_request_cancel (struct RPS_SamplerRequestHandle *req_handle);
 271
 272
 273 /**
 274  * Cleans the sampler.
 275  */
 276   void
 277 RPS_sampler_destroy (struct RPS_Sampler *sampler);
 278
 279 #endif /* RPS_SAMPLER_COMMON_H */
 280 /* end of rps-sampler_common.h */