src/set/gnunet-service-set_union_strata_estimator.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2012 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
  16 /**
  17  * @file set/gnunet-service-set_union_strata_estimator.h
  18  * @brief estimator of set difference
  19  * @author Florian Dold
  20  */
  21
  22 #ifndef GNUNET_CONSENSUS_STRATA_ESTIMATOR_H
  23 #define GNUNET_CONSENSUS_STRATA_ESTIMATOR_H
  24
  25 #include "platform.h"
  26 #include "gnunet_common.h"
  27 #include "gnunet_util_lib.h"
  28
  29 #ifdef __cplusplus
  30 extern "C"
  31 {
  32 #if 0                           /* keep Emacsens' auto-indent happy */
  33 }
  34 #endif
  35 #endif
  36
  37
  38 /**
  39  * A handle to a strata estimator.
  40  */
  41 struct StrataEstimator
  42 {
  43   /**
  44    * The IBFs of this strata estimator.
  45    */
  46   struct InvertibleBloomFilter **strata;
  47
  48   /**
  49    * Size of the IBF array in @e strata
  50    */
  51   unsigned int strata_count;
  52
  53   /**
  54    * Size of each IBF stratum (in bytes)
  55    */
  56   unsigned int ibf_size;
  57 };
  58
  59
  60 /**
  61  * Write the given strata estimator to the buffer.
  62  *
  63  * @param se strata estimator to serialize
  64  * @param[out] buf buffer to write to, must be of appropriate size
  65  * @return number of bytes written to @a buf
  66  */
  67 size_t
  68 strata_estimator_write (const struct StrataEstimator *se,
  69                         void *buf);
  70
  71
  72 /**
  73  * Read strata from the buffer into the given strata
  74  * estimator.  The strata estimator must already be allocated.
  75  *
  76  * @param buf buffer to read from
  77  * @param buf_len number of bytes in @a buf
  78  * @param is_compressed is the data compressed?
  79  * @param[out] se strata estimator to write to
  80  * @return #GNUNET_OK on success
  81  */
  82 int
  83 strata_estimator_read (const void *buf,
  84                        size_t buf_len,
  85                        int is_compressed,
  86                        struct StrataEstimator *se);
  87
  88
  89 /**
  90  * Create a new strata estimator with the given parameters.
  91  *
  92  * @param strata_count number of stratas, that is, number of ibfs in the estimator
  93  * @param ibf_size size of each ibf stratum
  94  * @param ibf_hashnum hashnum parameter of each ibf
  95  * @return a freshly allocated, empty strata estimator, NULL on error
  96  */
  97 struct StrataEstimator *
  98 strata_estimator_create (unsigned int strata_count,
  99                          uint32_t ibf_size,
 100                          uint8_t ibf_hashnum);
 101
 102
 103 /**
 104  * Get an estimation of the symmetric difference of the elements
 105  * contained in both strata estimators.
 106  *
 107  * @param se1 first strata estimator
 108  * @param se2 second strata estimator
 109  * @return abs(|se1| - |se2|)
 110  */
 111 unsigned int
 112 strata_estimator_difference (const struct StrataEstimator *se1,
 113                              const struct StrataEstimator *se2);
 114
 115
 116 /**
 117  * Add a key to the strata estimator.
 118  *
 119  * @param se strata estimator to add the key to
 120  * @param key key to add
 121  */
 122 void
 123 strata_estimator_insert (struct StrataEstimator *se,
 124                          struct IBF_Key key);
 125
 126
 127 /**
 128  * Remove a key from the strata estimator.
 129  *
 130  * @param se strata estimator to remove the key from
 131  * @param key key to remove
 132  */
 133 void
 134 strata_estimator_remove (struct StrataEstimator *se,
 135                          struct IBF_Key key);
 136
 137
 138 /**
 139  * Destroy a strata estimator, free all of its resources.
 140  *
 141  * @param se strata estimator to destroy.
 142  */
 143 void
 144 strata_estimator_destroy (struct StrataEstimator *se);
 145
 146
 147 /**
 148  * Make a copy of a strata estimator.
 149  *
 150  * @param se the strata estimator to copy
 151  * @return the copy
 152  */
 153 struct StrataEstimator *
 154 strata_estimator_dup (struct StrataEstimator *se);
 155
 156
 157 #if 0                           /* keep Emacsens' auto-indent happy */
 158 {
 159 #endif
 160 #ifdef __cplusplus
 161 }
 162 #endif
 163
 164 #endif