From 9e35e7119c7244e8fae94c3fa0cd90809539696d Mon Sep 17 00:00:00 2001 From: James Coleman Date: Thu, 30 Apr 2020 21:39:04 -0400 Subject: [PATCH v2 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 b0472a3fc7..884a2baf2b 100644 --- a/src/include/lib/simplehash.h +++ b/src/include/lib/simplehash.h @@ -51,6 +51,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 + * that 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.20.1 (Apple Git-117)