Fix potential NULL dereference warning.

[oweals/gnunet.git] / src / set / ibf.h

diff --git a/src/set/ibf.h b/src/set/ibf.h
index c5a979bfed941d55ce304f11ed6de3a2cc40d7ac..92ae2c0f3762c80c9c2b71d1626b251d39445332 100644 (file)
--- a/src/set/ibf.h
+++ b/src/set/ibf.h
@@ -1,6 +1,6 @@
 /*
       This file is part of GNUnet
-      (C) 2012 Christian Grothoff (and other contributing authors)
+      Copyright (C) 2012 GNUnet e.V.
 
       GNUnet is free software; you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published
@@ -14,8 +14,8 @@
 
       You should have received a copy of the GNU General Public License
       along with GNUnet; see the file COPYING.  If not, write to the
-      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-      Boston, MA 02111-1307, USA.
+      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+      Boston, MA 02110-1301, USA.
 */
 
 /**
@@ -28,7 +28,6 @@
 #define GNUNET_CONSENSUS_IBF_H
 
 #include "platform.h"
-#include "gnunet_common.h"
 #include "gnunet_util_lib.h"
 
 #ifdef __cplusplus
@@ -40,27 +39,40 @@ extern "C"
 #endif
 
 
+/**
+ * Keys that can be inserted into and removed from an IBF.
+ */
 struct IBF_Key
 {
   uint64_t key_val;
 };
 
+
+/**
+ * Hash of an IBF key.
+ */
 struct IBF_KeyHash
 {
   uint32_t key_hash_val;
 };
 
+
+/**
+ * Type of the count field of IBF buckets.
+ */
 struct IBF_Count
 {
   int8_t count_val;
 };
 
+
 /**
  * Size of one ibf bucket in bytes
  */
 #define IBF_BUCKET_SIZE (sizeof (struct IBF_Count) + sizeof (struct IBF_Key) + \
     sizeof (struct IBF_KeyHash))
 
+
 /**
  * Invertible bloom filter (IBF).
  *
@@ -104,14 +116,17 @@ struct InvertibleBloomFilter
 /**
  * Write buckets from an ibf to a buffer.
  * Exactly (IBF_BUCKET_SIZE*ibf->size) bytes are written to buf.
- * 
+ *
  * @param ibf the ibf to write
  * @param start with which bucket to start
  * @param count how many buckets to write
  * @param buf buffer to write the data to
  */
 void
-ibf_write_slice (const struct InvertibleBloomFilter *ibf, uint32_t start, uint32_t count, void *buf);
+ibf_write_slice (const struct InvertibleBloomFilter *ibf,
+                 uint32_t start,
+                 uint32_t count,
+                 void *buf);
 
 
 /**
@@ -120,10 +135,13 @@ ibf_write_slice (const struct InvertibleBloomFilter *ibf, uint32_t start, uint32
  * @param buf pointer to the buffer to read from
  * @param start which bucket to start at
  * @param count how many buckets to read
- * @param ibf the ibf to read from
+ * @param ibf the ibf to write to
  */
 void
-ibf_read_slice (const void *buf, uint32_t start, uint32_t count, struct InvertibleBloomFilter *ibf);
+ibf_read_slice (const void *buf,
+                uint32_t start,
+                uint32_t count,
+                struct InvertibleBloomFilter *ibf);
 
 
 /**
@@ -152,14 +170,14 @@ ibf_hashcode_from_key (struct IBF_Key key, struct GNUNET_HashCode *dst);
  *
  * @param size number of IBF buckets
  * @param hash_num number of buckets one element is hashed in, usually 3 or 4
- * @return the newly created invertible bloom filter
+ * @return the newly created invertible bloom filter, NULL on error
  */
 struct InvertibleBloomFilter *
 ibf_create (uint32_t size, uint8_t hash_num);
 
 
 /**
- * Insert an element into an IBF.
+ * Insert a key into an IBF.
  *
  * @param ibf the IBF
  * @param key the element's hash code
@@ -168,6 +186,16 @@ void
 ibf_insert (struct InvertibleBloomFilter *ibf, struct IBF_Key key);
 
 
+/**
+ * Remove a key from an IBF.
+ *
+ * @param ibf the IBF
+ * @param key the element's hash code
+ */
+void
+ibf_remove (struct InvertibleBloomFilter *ibf, struct IBF_Key key);
+
+
 /**
  * Subtract ibf2 from ibf1, storing the result in ibf1.
  * The two IBF's must have the same parameters size and hash_num.
@@ -176,7 +204,8 @@ ibf_insert (struct InvertibleBloomFilter *ibf, struct IBF_Key key);
  * @param ibf2 IBF that will be subtracted from ibf1
  */
 void
-ibf_subtract (struct InvertibleBloomFilter *ibf1, const struct InvertibleBloomFilter *ibf2);
+ibf_subtract (struct InvertibleBloomFilter *ibf1,
+              const struct InvertibleBloomFilter *ibf2);
 
 
 /**
@@ -187,12 +216,14 @@ ibf_subtract (struct InvertibleBloomFilter *ibf1, const struct InvertibleBloomFi
  *                 A negative sign indicates that the element was recovered
  *                 resides in an IBF that was previously subtracted from.
  * @param ret_id receives the hash code of the decoded element, if successful
- * @return GNUNET_YES if decoding an element was successful,
- *         GNUNET_NO if the IBF is empty,
- *         GNUNET_SYSERR if the decoding has failed
+ * @return #GNUNET_YES if decoding an element was successful,
+ *         #GNUNET_NO if the IBF is empty,
+ *         #GNUNET_SYSERR if the decoding has failed
  */
 int
-ibf_decode (struct InvertibleBloomFilter *ibf, int *ret_side, struct IBF_Key *ret_id);
+ibf_decode (struct InvertibleBloomFilter *ibf,
+            int *ret_side,
+            struct IBF_Key *ret_id);
 
 
 /**
@@ -203,6 +234,7 @@ ibf_decode (struct InvertibleBloomFilter *ibf, int *ret_side, struct IBF_Key *re
 struct InvertibleBloomFilter *
 ibf_dup (const struct InvertibleBloomFilter *ibf);
 
+
 /**
  * Destroy all resources associated with the invertible bloom filter.
  * No more ibf_*-functions may be called on ibf after calling destroy.
@@ -221,4 +253,3 @@ ibf_destroy (struct InvertibleBloomFilter *ibf);
 #endif
 
 #endif
-