src/include/gnunet_block_group_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010 GNUnet e.V.
   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., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Library for creating block groups (to be used by block plugins)
  26  *
  27  * @defgroup block  Block group library
  28  * Library for data group management
  29  * @{
  30  */
  31 #ifndef GNUNET_BLOCK_GROUP_LIB_H
  32 #define GNUNET_BLOCK_GROUP_LIB_H
  33
  34 #include "gnunet_util_lib.h"
  35 #include "gnunet_block_lib.h"
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #if 0                           /* keep Emacsens' auto-indent happy */
  41 }
  42 #endif
  43 #endif
  44
  45
  46 /**
  47  * How many bytes should a bloomfilter be if we have already seen
  48  * entry_count responses?  Sized so that do not have to
  49  * re-size the filter too often (to keep it cheap).
  50  *
  51  * Since other peers will also add entries but not resize the filter,
  52  * we should generally pick a slightly larger size than what the
  53  * strict math would suggest.
  54  *
  55  * @param entry_count expected number of entries in the Bloom filter
  56  * @param k number of bits set per entry
  57  * @return must be a power of two and smaller or equal to 2^15.
  58  */
  59 size_t
  60 GNUNET_BLOCK_GROUP_compute_bloomfilter_size (unsigned int entry_count,
  61                                              unsigned int k);
  62
  63
  64 /**
  65  * Create a new block group that filters duplicates using a Bloom filter.
  66  *
  67  * @param ctx block context in which the block group is created
  68  * @param bf_size size of the Bloom filter
  69  * @param bf_k K-value for the Bloom filter
  70  * @param type block type
  71  * @param nonce random value used to seed the group creation
  72  * @param raw_data optional serialized prior state of the group, NULL if unavailable/fresh
  73  * @param raw_data_size number of bytes in @a raw_data, 0 if unavailable/fresh
  74  * @return block group handle, NULL if block groups are not supported
  75  *         by this @a type of block (this is not an error)
  76  */
  77 struct GNUNET_BLOCK_Group *
  78 GNUNET_BLOCK_GROUP_bf_create (void *cls,
  79                               size_t bf_size,
  80                               unsigned int bf_k,
  81                               enum GNUNET_BLOCK_Type type,
  82                               uint32_t nonce,
  83                               const void *raw_data,
  84                               size_t raw_data_size);
  85
  86
  87 /**
  88  * Test if @a hc is contained in the Bloom filter of @a bg.  If so,
  89  * return #GNUNET_YES.  If not, add @a hc to the Bloom filter and
  90  * return #GNUNET_NO.
  91  *
  92  * @param bg block group to use for testing
  93  * @param hc hash of element to evaluate
  94  * @return #GNUNET_YES if @a hc is (likely) a duplicate
  95  *         #GNUNET_NO if @a hc was definitively not in @bg (but now is)
  96  */
  97 int
  98 GNUNET_BLOCK_GROUP_bf_test_and_set (struct GNUNET_BLOCK_Group *bg,
  99                                     const struct GNUNET_HashCode *hc);
 100
 101
 102 #if 0                           /* keep Emacsens' auto-indent happy */
 103 {
 104 #endif
 105 #ifdef __cplusplus
 106 }
 107 #endif
 108
 109 /* ifndef GNUNET_BLOCK_GROUP_LIB_H */
 110 #endif
 111
 112 /** @} */  /* end of group */
 113
 114 /* end of gnunet_block_group_lib.h */