libhashkit(3)

1LIBHASHKIT(3)                libmemcached-awesome                LIBHASHKIT(3)
2
3
4

NAME

6       libhashkit - libhashkit Documentation
7

SYNOPSIS

9       #include <libhashkit-1.0/hashkit.h>
10              Compile and link with -lhashkit.
11

DESCRIPTION

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