1LIBHASHKIT(3) libmemcached-awesome LIBHASHKIT(3)
2
3
4
6 libhashkit - libhashkit Documentation
7
9 #include <libhashkit-1.0/hashkit.h>
10 Compile and link with -lhashkit.
11
13 libhashkit is a small and thread-safe client library that provides a
14 collection of useful hashing algorithms.
15
16 libhashkit is distributed with libmemcached.
17
18 Creating a hashkit structure
19 SYNOPSIS
20 #include <libhashkit-1.0/hashkit.h>
21 Compile and link with -lhashkit
22
23 typedef struct hashkit_st hashkit_st
24
25 hashkit_st *hashkit_create(hashkit_st *hash)
26
27 Parameters
28 hash -- memory address of a hashkit_st struct; if a
29 nullptr is passed, the struct will be dynamically allo‐
30 cated by libhashkit
31
32 Returns
33 pointer to initialized hashkit_st structure
34
35 hashkit_st *hashkit_clone(hashkit_st *destination, const hashkit_st
36 *ptr)
37
38 Parameters
39
40 • destination -- memory address of a hashkit_st struct;
41 if a nullptr is passed, the struct will be dynamically
42 allocated by libhashkit
43
44 • ptr -- pointer of the hashkit_st struct to copy
45
46 Returns
47 pointer to a hashkit_st structure (destination, if not
48 nullptr), initialized from ptr
49
50 void hashkit_free(hashkit_st *hash)
51
52 Parameters
53 hash -- pointer to an initialized hashkit_st struct
54
55 bool hashkit_is_allocated(const hashkit_st *hash)
56
57 Parameters
58 hash -- pointer to an initialized hashkit_st struct
59
60 Returns
61 bool, whether the hash struct was dynamically allocated
62
63 DESCRIPTION
64 The hashkit_create() function initializes a hashkit object for use. If
65 you pass a nullptr argument for hash, then the memory for the object is
66 allocated. If you specify a pre-allocated piece of memory, that is ini‐
67 tialized for use.
68
69 The hashkit_clone() function initializes a hashkit object much like
70 hashkit_create(), but instead of using default settings it will use the
71 settings of the ptr hashkit object.
72
73 The hashkit_free() frees any resources being consumed by the hashkit
74 objects that were initialized with hashkit_create() or hashkit_clone().
75
76 The hashkit_is_allocated() reports whether the memory was allocated for
77 a hashkit object.
78
79 RETURN VALUE
80 hashkit_create() and hashkit_clone() will return nullptr on failure or
81 pointer to hashkit_st on success.
82
83 hashkit_is_allocated() returns true if the memory for the hashkit ob‐
84 ject was allocated inside of hashkit_create() or hashkit_clone(), oth‐
85 erwise it is false and was user-supplied memory.
86
87 SEE ALSO
88 libhashkit(3) hashkit_value(3) hashkit_function3)
89
90 Set Hash Function
91 SYNOPSIS
92 #include <libhashkit-1.0/hashkit.h>
93 Compile and link with -lhashkit
94
95 typedef uint32_t (*hashkit_hash_fn)(const char *key, size_t key_length,
96 void *context)
97
98 Param key
99 the key to generate a hash of
100
101 Param key_length
102 the length of the key without any terminating zero byte
103
104 Param context
105 the custom hash function context set through
106 hashkit_set_custom_function() or
107 hashkit_set_custom_distribution_function()
108
109 Returns
110 the custom hash function should return a hash value for
111 key as an unsigned 32bit integer
112
113 typedef enum hashkit_return_t hashkit_return_t
114
115 enum hashkit_return_t
116
117 enumerator HASHKIT_SUCCESS
118 Operation succeeded.
119
120 enumerator HASHKIT_FAILURE
121 Operation failed.
122
123 enumerator HASHKIT_MEMORY_ALLOCATION_FAILURE
124 Memory allocation failed.
125
126 enumerator HASHKIT_INVALID_HASH
127 Invalid hashkit_hash_algorithm_t passed.
128
129 enumerator HASHKIT_INVALID_ARGUMENT
130 Invalid argument passed.
131
132 typedef enum hashkit_hash_algorithm_t hashkit_hash_algorithm_t
133
134 enum hashkit_hash_algorithm_t
135
136 enumerator HASHKIT_HASH_DEFAULT
137 Default hash algorithm (one_at_a_time).
138
139 enumerator HASHKIT_HASH_MD5
140
141 enumerator HASHKIT_HASH_CRC
142
143 enumerator HASHKIT_HASH_FNV1_64
144
145 enumerator HASHKIT_HASH_FNV1A_64
146
147 enumerator HASHKIT_HASH_FNV1_32
148
149 enumerator HASHKIT_HASH_FNV1A_32
150
151 enumerator HASHKIT_HASH_HSIEH
152 Only available if libhashkit hash been built with HSIEH
153 support.
154
155 enumerator HASHKIT_HASH_MURMUR
156 Only available if libhashkit has been built with MURMUR
157 support.
158
159 enumerator HASHKIT_HASH_MURMUR3
160 Only available if libhashkit has been built with MURMUR
161 support.
162
163 enumerator HASHKIT_HASH_JENKINS
164
165 enumerator HASHKIT_HASH_CUSTOM
166 Use custom hashkit_hash_fn function set through
167 hashkit_set_custom_function() or
168 hashkit_set_custom_distribution_function().
169
170 hashkit_return_t hashkit_set_function(hashkit_st *hash,
171 hashkit_hash_algorithm_t hash_algorithm)
172
173 Parameters
174
175 • hash -- pointer to an initialized hashkit_st struct
176
177 • hash_algorithm -- valid hashkit_hash_algorithm_t con‐
178 stant
179
180 Returns
181 hashkit_return_t indicating success or failure
182
183 hashkit_return_t hashkit_set_custom_function(hashkit_st *hash,
184 hashkit_hash_fn function, void *context)
185
186 Parameters
187
188 • hash -- pointer to initialized hashkit_st struct
189
190 • function -- hashkit_hash_fn function pointer to use as
191 hash function for HASHKIT_HASH_CUSTOM
192
193 • context -- pointer to an opaque user managed context
194 for the custom hash function
195
196 Returns
197 hashkit_return_t indicating success or failure
198
199 hashkit_hash_algorithm_t hashkit_get_function(const hashkit_st *hash)
200
201 Parameters
202 hash -- pointer to an initialized hashkit_st struct
203
204 Returns
205 hashkit_hash_algorithm_t indicating the currently set
206 hash algorithm to use
207
208 hashkit_return_t hashkit_set_distribution_function(hashkit_st *hash,
209 hashkit_hash_algorithm_t hash_algorithm)
210
211 Parameters
212
213 • hash -- pointer to an initialized hashkit_st struct
214
215 • hash_algorithm -- valid hashkit_hash_algrothm_t con‐
216 stant
217
218 Returns
219 hashkit_return_t indicating success or failure
220
221 hashkit_return_t hashkit_set_custom_distribution_function(hashkit_st
222 *hash, hashkit_hash_fn function, void *context)
223
224 Parameters
225
226 • hash -- pointer to initialized hashkit_st struct
227
228 • function -- hashkit_hash_fn function pointer to use as
229 distribution hash function for HASHKIT_HASH_CUSTOM
230
231 • context -- pointer to an opaque user managed context
232 for the custom distribution hash function
233
234 hashkit_hash_algorithm_t hashkit_get_distribution_function(const
235 hashkit_st *hash)
236
237 Parameters
238 hash -- pointer to an initialized hashkit_st struct
239
240 Returns
241 hashkit_hash_algorithm_t indicating the currently set
242 distribution hash algorithm to use
243
244 DESCRIPTION
245 These functions are used to set and retrieve the key and distribution
246 hash functions.
247
248 RETURN VALUE
249 hashkit_set_function(), hashkit_set_custom_function() and the distribu‐
250 tion equivalents return hashkit_return_t::HASHKIT_SUCCESS on success.
251
252 hashkit_get_function() and hashkit_get_distribution_function() return
253 hashkit_hash_algorithm_t indicating the hash function used.
254
255 SEE ALSO
256 libhashkit(3) hashkit_create(3) hashkit_functions(3)
257
258 Available Hashes
259 SYNOPSIS
260 #include <libhashkit-1.0/hashkit.h>
261 Compile and link with -lhashkit
262
263 uint32_t hashkit_default(const char *key, size_t key_length)
264
265 uint32_t hashkit_fnv1_64(const char *key, size_t key_length)
266
267 uint32_t hashkit_fnv1a_64(const char *key, size_t key_length)
268
269 uint32_t hashkit_fnv1_32(const char *key, size_t key_length)
270
271 uint32_t hashkit_fnv1a_32(const char *key, size_t key_length)
272
273 uint32_t hashkit_crc32(const char *key, size_t key_length)
274
275 uint32_t hashkit_hsieh(const char *key, size_t key_length)
276
277 uint32_t hashkit_murmur(const char *key, size_t key_length)
278
279 uint32_t hashkit_murmur3(const char *key, size_t key_length)
280
281 uint32_t hashkit_jenkins(const char *key, size_t key_length)
282
283 uint32_t hashkit_md5(const char *key, size_t key_length)
284
285 DESCRIPTION
286 These functions generate hash values from a key using a variety of al‐
287 gorithms. These functions can be used standalone, or will be used ac‐
288 cording to the algorithm set with hashkit_set_function() or
289 hashkit_set_distribution_function().
290
291 The hashkit_hsieh(), hashkit_murmur() and hashkit_murmur3() functions
292 are only available if the library is built with the appropriate flag
293 enabled.
294
295 RETURN VALUE
296 A 32-bit hash value.
297
298 SEE ALSO
299 libhashkit(3) hashkit_create(3) hashkit_function(3)
300
301 Generate hash value
302 SYNOPSIS
303 #include <libhashkit-1.0/hashkit.h>
304 Compile and link with -lhashkit
305
306 uint32_t hashkit_value(hashkit_st *hash, const char *key, size_t
307 key_length)
308
309 Parameters
310
311 • hash -- pointer to an initialized hashkit_st struct
312
313 • key -- the key to genereate a hash of
314
315 • key_length -- the length of the key without any termi‐
316 nating zero byte
317
318 DESCRIPTION
319 The hashkit_value() function generates a 32-bit hash value from the
320 given key and key_length. The hash argument is an initialized hashkit
321 object, and distribution type and hash function is used from this ob‐
322 ject while generating the value.
323
324 RETURN VALUE
325 A 32-bit hash value.
326
327 SEE ALSO
328 libhashkit(3) hashkit_create(3) hashkit_function(3) hashkit_func‐
329 tions(3)
330
332 libmemcached(3) hashkit_create(3) hashkit_function(3) hashkit_func‐
333 tions(3) hashkit_value(3)
334
335
336
337
3381.1 Jul 20, 2023 LIBHASHKIT(3)