lib: Update hash.h documentation

The hash_get function when called and the alloc_func returns
a NULL value, we do not create a backet nor do we insert
anything into the hash.  As such backet->data must always
be non-NULL.

Modify the description in hash_get to inform of this.
Additionally indicate that hash_walk and hash_iterate
cannot have a NULL backet->data value.

Signed-off-by: Donald Sharp <sharpd@cumulusnetworks.com>

diff --git a/lib/hash.h b/lib/hash.h
index 12c214e469571d10f1360b9f9adba736c27a4d15..2b4ea48f3812d6297da3fc3269c1d930ed4940a5 100644 (file)
--- a/lib/hash.h
+++ b/lib/hash.h
@@ -167,7 +167,9 @@ hash_create_size(unsigned int size, unsigned int (*hash_key)(void *),
  *    hash table to operate on
  *
  * data
- *    data to insert or retrieve
+ *    data to insert or retrieve - A hash backet will not be created if
+ *    the alloc_func returns a NULL pointer and nothing will be added to
+ *    the hash.  As such backet->data will always be non-NULL.
  *
  * alloc_func
  *    function to call if the item is not found in the hash table. This
@@ -236,6 +238,8 @@ extern void *hash_release(struct hash *hash, void *data);
  * during the walk will cause undefined behavior in that some new entries
  * will be walked and some will not.  So do not do this.
  *
+ * The backet passed to func will have a non-NULL data pointer.
+ *
  * hash
  *    hash table to operate on
  *
@@ -256,6 +260,8 @@ extern void hash_iterate(struct hash *hash,
  * during the walk will cause undefined behavior in that some new entries
  * will be walked and some will not.  So do not do this.
  *
+ * The backet passed to func will have a non-NULL data pointer.
+ *
  * hash
  *    hash table to operate on
  *