table of contents
LIBHASHKIT(3) | libmemcached-awesome | LIBHASHKIT(3) |
NAME¶
libhashkit - libhashkit Documentation
SYNOPSIS¶
- #include <libhashkit-1.0/hashkit.h>
- Compile and link with -lhashkit.
DESCRIPTION¶
libhashkit is a small and thread-safe client library that provides a collection of useful hashing algorithms.
libhashkit is distributed with libmemcached.
Creating a hashkit structure¶
SYNOPSIS¶
- #include <libhashkit-1.0/hashkit.h>
- Compile and link with -lhashkit
- Parameters
- hash -- memory address of a hashkit_st struct; if a nullptr is passed, the struct will be dynamically allocated by libhashkit
- Returns
- pointer to initialized hashkit_st structure
- destination -- memory address of a hashkit_st struct; if a nullptr is passed, the struct will be dynamically allocated by libhashkit
- ptr -- pointer of the hashkit_st struct to copy
- Returns
- pointer to a hashkit_st structure (destination, if not nullptr), initialized from ptr
- Parameters
- hash -- pointer to an initialized hashkit_st struct
- Returns
- bool, whether the hash struct was dynamically allocated
DESCRIPTION¶
The hashkit_create() function initializes a hashkit object for use. If you pass a nullptr argument for hash, then the memory for the object is allocated. If you specify a pre-allocated piece of memory, that is initialized for use.
The hashkit_clone() function initializes a hashkit object much like hashkit_create(), but instead of using default settings it will use the settings of the ptr hashkit object.
The hashkit_free() frees any resources being consumed by the hashkit objects that were initialized with hashkit_create() or hashkit_clone().
The hashkit_is_allocated() reports whether the memory was allocated for a hashkit object.
RETURN VALUE¶
hashkit_create() and hashkit_clone() will return nullptr on failure or pointer to hashkit_st on success.
hashkit_is_allocated() returns true if the memory for the hashkit object was allocated inside of hashkit_create() or hashkit_clone(), otherwise it is false and was user-supplied memory.
SEE ALSO¶
libhashkit(3) hashkit_value(3) hashkit_function3)
Set Hash Function¶
SYNOPSIS¶
- #include <libhashkit-1.0/hashkit.h>
- Compile and link with -lhashkit
- Param key
- the key to generate a hash of
- Param key_length
- the length of the key without any terminating zero byte
- Param context
- the custom hash function context set through hashkit_set_custom_function() or hashkit_set_custom_distribution_function()
- Returns
- the custom hash function should return a hash value for key as an unsigned 32bit integer
- enumerator HASHKIT_SUCCESS
- Operation succeeded.
- enumerator HASHKIT_FAILURE
- Operation failed.
- enumerator HASHKIT_MEMORY_ALLOCATION_FAILURE
- Memory allocation failed.
- enumerator HASHKIT_INVALID_HASH
- Invalid hashkit_hash_algorithm_t passed.
- enumerator HASHKIT_INVALID_ARGUMENT
- Invalid argument passed.
- enumerator HASHKIT_HASH_DEFAULT
- Default hash algorithm (one_at_a_time).
- enumerator HASHKIT_HASH_HSIEH
- Only available if libhashkit hash been built with HSIEH support.
- enumerator HASHKIT_HASH_MURMUR
- Only available if libhashkit has been built with MURMUR support.
- enumerator HASHKIT_HASH_MURMUR3
- Only available if libhashkit has been built with MURMUR support.
- enumerator HASHKIT_HASH_CUSTOM
- Use custom hashkit_hash_fn function set through hashkit_set_custom_function() or hashkit_set_custom_distribution_function().
- hash -- pointer to an initialized hashkit_st struct
- hash_algorithm -- valid hashkit_hash_algorithm_t constant
- Returns
- hashkit_return_t indicating success or failure
- hash -- pointer to initialized hashkit_st struct
- function -- hashkit_hash_fn function pointer to use as hash function for HASHKIT_HASH_CUSTOM
- context -- pointer to an opaque user managed context for the custom hash function
- Returns
- hashkit_return_t indicating success or failure
- Parameters
- hash -- pointer to an initialized hashkit_st struct
- Returns
- hashkit_hash_algorithm_t indicating the currently set hash algorithm to use
- hash -- pointer to an initialized hashkit_st struct
- hash_algorithm -- valid hashkit_hash_algrothm_t constant
- Returns
- hashkit_return_t indicating success or failure
- hash -- pointer to initialized hashkit_st struct
- function -- hashkit_hash_fn function pointer to use as distribution hash function for HASHKIT_HASH_CUSTOM
- context -- pointer to an opaque user managed context for the custom distribution hash function
- Parameters
- hash -- pointer to an initialized hashkit_st struct
- Returns
- hashkit_hash_algorithm_t indicating the currently set distribution hash algorithm to use
DESCRIPTION¶
These functions are used to set and retrieve the key and distribution hash functions.
RETURN VALUE¶
hashkit_set_function(), hashkit_set_custom_function() and the distribution equivalents return hashkit_return_t::HASHKIT_SUCCESS on success.
hashkit_get_function() and hashkit_get_distribution_function() return hashkit_hash_algorithm_t indicating the hash function used.
SEE ALSO¶
Available Hashes¶
SYNOPSIS¶
- #include <libhashkit-1.0/hashkit.h>
- Compile and link with -lhashkit
DESCRIPTION¶
These functions generate hash values from a key using a variety of algorithms. These functions can be used standalone, or will be used according to the algorithm set with hashkit_set_function() or hashkit_set_distribution_function().
The hashkit_hsieh(), hashkit_murmur() and hashkit_murmur3() functions are only available if the library is built with the appropriate flag enabled.
RETURN VALUE¶
A 32-bit hash value.
SEE ALSO¶
Generate hash value¶
SYNOPSIS¶
- #include <libhashkit-1.0/hashkit.h>
- Compile and link with -lhashkit
- hash -- pointer to an initialized hashkit_st struct
- key -- the key to genereate a hash of
- key_length -- the length of the key without any terminating zero byte
DESCRIPTION¶
The hashkit_value() function generates a 32-bit hash value from the given key and key_length. The hash argument is an initialized hashkit object, and distribution type and hash function is used from this object while generating the value.
RETURN VALUE¶
A 32-bit hash value.
SEE ALSO¶
libhashkit(3) hashkit_create(3) hashkit_function(3) hashkit_functions(3)
SEE ALSO¶
libmemcached(3) hashkit_create(3) hashkit_function(3) hashkit_functions(3) hashkit_value(3)
February 5, 2024 | 1.1 |