void* bucket_root;
size_t rowsize, bucketsize;
}* ston_dht;
-
+/* STON DHT API
+ Primary functions for creating hashtables, retrieving pointers to values,
+ iterating over all keys and values, and destroying hashtables. */
STON_FUNC
ston_dht ston_dht_new(uint16_t,uint8_t,void*(*)(size_t),void(*)(void*));
STON_FUNC
+void* ston_dht_val(ston_dht,void*);
+STON_FUNC
ston_dht ston_dht_free(ston_dht);
STON_FUNC
-void* ston_dht_val(ston_dht,void*);
+void ston_dht_iterate(ston_dht,void(*)(void*,void*,void*),void*);
+/* Recursive functions intended to be called by other functions, above */
STON_FUNC_STATIC
STON_FUNC_NOINLINE
void ston_dht_free_bucket(ston_dht,void*);
-STON_FUNC
-void ston_dht_iterate(ston_dht,void(*)(void*,void*,void*),void*);
STON_FUNC_STATIC
STON_FUNC_NOINLINE
void ston_dht_iterate_r(ston_dht,void*);
-
-// Compatibility macros
+// Compatibility macros - Deprecated
#define ston_dht32_new(_COL,_ALOC,_FRE) (ston_dht_new(4 * _COL, 4, _ALOC, _FRE))
#define ston_dht32_row(_HT,_K) ((uint32_t*)((uint8_t*)ston_dht_val(_HT,&(_K)) - 4))
#define ston_dht32_insertx(_HT,_K,_VP,_OFFS,_N) \
memcpy((uint32_t*)((uint8_t*)ston_dht_val(_HT,&(_K)) + ((_OFFS - 1) * 4)),_VP,_N * 4)
-/* Creates a new bucketted hash table, provided a memory allocation function
- that takes a single size_t bytes, a memory free function, a column count, and
- a row count which determines the size of the buckets.
-*/
+/* New dynamic hashtable, provided value bytes, key bytes, allocator function,
+ and free function. Value bytes and key bytes are respectively constrained to
+ uint16 and uint8 so they can be aligned to hashtables encoded for
+ streaming */
STON_FUNC
ston_dht ston_dht_new
( uint16_t val_bytes,
return (void*) row + sizeof(void*) + key_bytes;
}
-/* Free the dynamic hash table */
+/* Recursively frees all memory stored in the hashtable, and the hashtable
+ itself */
STON_FUNC
struct ston_dht_t* ston_dht_free
( struct ston_dht_t* ht )
return ht;
}
-/* Recursively free pages by lookup */
+/* Recursive free function for nested buckets */
STON_FUNC_STATIC
STON_FUNC_NOINLINE
void ston_dht_free_bucket
ht->ht_free(bucket);
}
-/* Iterate over each key/value pair and execut 'fn' with key and value as
- arguments */
+/* Iterate over each key/value pair and execut 'fn' with key, value and
+ user_data as its arguments. user_data may be anything, even NULL, and is
+ expected to be referenced inside the body of 'fn' as the third argument of
+ 'fn' */
STON_FUNC
void ston_dht_iterate
( struct ston_dht_t* ht,