libhashkit - libhashkit Documentation

Description

libhashkit is a small and thread-safe client library that provides a collection of useful hashing algorithms. libhashkit is distributed with libmemcached. CreatingahashkitstructureSYNOPSIS#include<libhashkit-1.0/hashkit.h> Compile and link with -lhashkit typedefstructhashkit_sthashkit_sthashkit_st*hashkit_create(hashkit_st*hash)Parametershash -- 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 hashkit_st*hashkit_clone(hashkit_st*destination,consthashkit_st*ptr)Parameters • 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 ptrvoidhashkit_free(hashkit_st*hash)Parametershash -- pointer to an initialized hashkit_st struct boolhashkit_is_allocated(consthashkit_st*hash)Parametershash -- 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. RETURNVALUEhashkit_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. SEEALSOlibhashkit(3)hashkit_value(3)hashkit_function3)SetHashFunctionSYNOPSIS#include<libhashkit-1.0/hashkit.h> Compile and link with -lhashkit typedefuint32_t(*hashkit_hash_fn)(constchar*key,size_tkey_length,void*context)Paramkey the key to generate a hash of Paramkey_length the length of the key without any terminating zero byte Paramcontext 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 typedefenumhashkit_return_thashkit_return_tenumhashkit_return_tenumeratorHASHKIT_SUCCESS Operation succeeded. enumeratorHASHKIT_FAILURE Operation failed. enumeratorHASHKIT_MEMORY_ALLOCATION_FAILURE Memory allocation failed. enumeratorHASHKIT_INVALID_HASH Invalid hashkit_hash_algorithm_t passed. enumeratorHASHKIT_INVALID_ARGUMENT Invalid argument passed. typedefenumhashkit_hash_algorithm_thashkit_hash_algorithm_tenumhashkit_hash_algorithm_tenumeratorHASHKIT_HASH_DEFAULT Default hash algorithm (one_at_a_time). enumeratorHASHKIT_HASH_MD5enumeratorHASHKIT_HASH_CRCenumeratorHASHKIT_HASH_FNV1_64enumeratorHASHKIT_HASH_FNV1A_64enumeratorHASHKIT_HASH_FNV1_32enumeratorHASHKIT_HASH_FNV1A_32enumeratorHASHKIT_HASH_HSIEH Only available if libhashkit hash been built with HSIEH support. enumeratorHASHKIT_HASH_MURMUR Only available if libhashkit has been built with MURMUR support. enumeratorHASHKIT_HASH_MURMUR3 Only available if libhashkit has been built with MURMUR support. enumeratorHASHKIT_HASH_JENKINSenumeratorHASHKIT_HASH_CUSTOM Use custom hashkit_hash_fn function set through hashkit_set_custom_function() or hashkit_set_custom_distribution_function(). hashkit_return_thashkit_set_function(hashkit_st*hash,hashkit_hash_algorithm_thash_algorithm)Parameters • hash -- pointer to an initialized hashkit_st struct • hash_algorithm -- valid hashkit_hash_algorithm_t constant Returnshashkit_return_t indicating success or failure hashkit_return_thashkit_set_custom_function(hashkit_st*hash,hashkit_hash_fnfunction,void*context)Parameters • 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 Returnshashkit_return_t indicating success or failure hashkit_hash_algorithm_thashkit_get_function(consthashkit_st*hash)Parametershash -- pointer to an initialized hashkit_st struct Returnshashkit_hash_algorithm_t indicating the currently set hash algorithm to use hashkit_return_thashkit_set_distribution_function(hashkit_st*hash,hashkit_hash_algorithm_thash_algorithm)Parameters • hash -- pointer to an initialized hashkit_st struct • hash_algorithm -- valid hashkit_hash_algrothm_t constant Returnshashkit_return_t indicating success or failure hashkit_return_thashkit_set_custom_distribution_function(hashkit_st*hash,hashkit_hash_fnfunction,void*context)Parameters • 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 hashkit_hash_algorithm_thashkit_get_distribution_function(consthashkit_st*hash)Parametershash -- pointer to an initialized hashkit_st struct Returnshashkit_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. RETURNVALUEhashkit_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. SEEALSOlibhashkit(3)hashkit_create(3)hashkit_functions(3)AvailableHashesSYNOPSIS#include<libhashkit-1.0/hashkit.h> Compile and link with -lhashkit uint32_thashkit_default(constchar*key,size_tkey_length)uint32_thashkit_fnv1_64(constchar*key,size_tkey_length)uint32_thashkit_fnv1a_64(constchar*key,size_tkey_length)uint32_thashkit_fnv1_32(constchar*key,size_tkey_length)uint32_thashkit_fnv1a_32(constchar*key,size_tkey_length)uint32_thashkit_crc32(constchar*key,size_tkey_length)uint32_thashkit_hsieh(constchar*key,size_tkey_length)uint32_thashkit_murmur(constchar*key,size_tkey_length)uint32_thashkit_murmur3(constchar*key,size_tkey_length)uint32_thashkit_jenkins(constchar*key,size_tkey_length)uint32_thashkit_md5(constchar*key,size_tkey_length)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. RETURNVALUE A 32-bit hash value. SEEALSOlibhashkit(3)hashkit_create(3)hashkit_function(3)GeneratehashvalueSYNOPSIS#include<libhashkit-1.0/hashkit.h> Compile and link with -lhashkit uint32_thashkit_value(hashkit_st*hash,constchar*key,size_tkey_length)Parameters • 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. RETURNVALUE A 32-bit hash value. SEEALSOlibhashkit(3)hashkit_create(3)hashkit_function(3)hashkit_functions(3)