From 36f6b670b30194efb4b7d0e622afc3085ecd49b6 Mon Sep 17 00:00:00 2001
From: James Coleman <jtc331@gmail.com>
Date: Thu, 30 Apr 2020 21:39:04 -0400
Subject: [PATCH v1 2/3] Improve simplehash usage notes

---
 src/include/lib/simplehash.h | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/include/lib/simplehash.h b/src/include/lib/simplehash.h
index e5101f2f1d..8daf7c4d1a 100644
--- a/src/include/lib/simplehash.h
+++ b/src/include/lib/simplehash.h
@@ -48,6 +48,19 @@
  *	  - SH_STORE_HASH - if defined the hash is stored in the elements
  *	  - SH_GET_HASH(tb, a) - return the field to store the hash in
  *
+ *    The element type is required to contain a "uint32 status" member.
+ *
+ *    While SH_STORE_HASH (and subsequently SH_GET_HASH) are optional, because
+ *    the hash table implementation needs to compare hashes to move elements
+ *    (particularly when growing the hash), it's preferable, if possible, to
+ *    store the element's hash in the element's data type. If the hash is so
+ *    stored, the hash table will also compare hashes before calling SH_EQUAL
+ *    when comparing two keys.
+ *
+ *    For convenience the hash table create functions accept a void pointer
+ *    will be stored in the hash table type's member private_data. This allows
+ *    callbacks to reference caller provided data.
+ *
  *	  For examples of usage look at tidbitmap.c (file local definition) and
  *	  execnodes.h/execGrouping.c (exposed declaration, file local
  *	  implementation).
-- 
2.17.1

