.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "LIBHASHKIT" "3" "Feb 01, 2024" "1.1" "libmemcached-awesome" .SH NAME libhashkit \- libhashkit Documentation .SH SYNOPSIS .INDENT 0.0 .TP .B #include Compile and link with \-lhashkit. .UNINDENT .SH DESCRIPTION .sp \fBlibhashkit\fP is a small and thread\-safe client library that provides a collection of useful hashing algorithms. .sp \fBlibhashkit\fP is distributed with \fBlibmemcached\fP\&. .SS Creating a hashkit structure .SS SYNOPSIS .INDENT 0.0 .TP .B #include Compile and link with \-lhashkit .UNINDENT .INDENT 0.0 .TP .B typedef struct \fI\%hashkit_st\fP hashkit_st .UNINDENT .INDENT 0.0 .TP .B \fI\%hashkit_st\fP *hashkit_create(\fI\%hashkit_st\fP *hash) .INDENT 7.0 .TP .B Parameters \fBhash\fP \-\- memory address of a \fI\%hashkit_st\fP struct; if a nullptr is passed, the struct will be dynamically allocated by libhashkit .TP .B Returns pointer to initialized \fI\%hashkit_st\fP structure .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fI\%hashkit_st\fP *hashkit_clone(\fI\%hashkit_st\fP *destination, const \fI\%hashkit_st\fP *ptr) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdestination\fP \-\- memory address of a \fI\%hashkit_st\fP struct; if a nullptr is passed, the struct will be dynamically allocated by libhashkit .IP \(bu 2 \fBptr\fP \-\- pointer of the \fI\%hashkit_st\fP struct to copy .UNINDENT .TP .B Returns pointer to a \fI\%hashkit_st\fP structure (\fI\%destination\fP, if not nullptr), initialized from \fI\%ptr\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B void hashkit_free(\fI\%hashkit_st\fP *hash) .INDENT 7.0 .TP .B Parameters \fBhash\fP \-\- pointer to an initialized \fI\%hashkit_st\fP struct .UNINDENT .UNINDENT .INDENT 0.0 .TP .B bool hashkit_is_allocated(const \fI\%hashkit_st\fP *hash) .INDENT 7.0 .TP .B Parameters \fBhash\fP \-\- pointer to an initialized \fI\%hashkit_st\fP struct .TP .B Returns bool, whether the \fI\%hash\fP struct was dynamically allocated .UNINDENT .UNINDENT .SS DESCRIPTION .sp The \fI\%hashkit_create()\fP 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. .sp The \fI\%hashkit_clone()\fP function initializes a hashkit object much like \fI\%hashkit_create()\fP, but instead of using default settings it will use the settings of the ptr hashkit object. .sp The \fI\%hashkit_free()\fP frees any resources being consumed by the hashkit objects that were initialized with \fI\%hashkit_create()\fP or \fI\%hashkit_clone()\fP\&. .sp The \fI\%hashkit_is_allocated()\fP reports whether the memory was allocated for a hashkit object. .SS RETURN VALUE .sp \fI\%hashkit_create()\fP and \fI\%hashkit_clone()\fP will return nullptr on failure or pointer to \fI\%hashkit_st\fP on success. .sp \fI\%hashkit_is_allocated()\fP returns true if the memory for the hashkit object was allocated inside of \fI\%hashkit_create()\fP or \fI\%hashkit_clone()\fP, otherwise it is false and was user\-supplied memory. .SS SEE ALSO .sp \fBlibhashkit(3)\fP \fBhashkit_value(3)\fP \fBhashkit_function3)\fP .SS Set Hash Function .SS SYNOPSIS .INDENT 0.0 .TP .B #include Compile and link with \-lhashkit .UNINDENT .INDENT 0.0 .TP .B typedef uint32_t (*hashkit_hash_fn)(const char *key, size_t key_length, void *context) .INDENT 7.0 .TP .B Param key the key to generate a hash of .TP .B Param key_length the length of the \fBkey\fP without any terminating zero byte .TP .B Param context the custom hash function context set through \fI\%hashkit_set_custom_function()\fP or \fI\%hashkit_set_custom_distribution_function()\fP .TP .B Returns the custom hash function should return a hash value for \fBkey\fP as an unsigned 32bit integer .UNINDENT .UNINDENT .INDENT 0.0 .TP .B typedef enum \fI\%hashkit_return_t\fP hashkit_return_t .UNINDENT .INDENT 0.0 .TP .B enum hashkit_return_t .INDENT 7.0 .TP .B enumerator HASHKIT_SUCCESS Operation succeeded. .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_FAILURE Operation failed. .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_MEMORY_ALLOCATION_FAILURE Memory allocation failed. .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_INVALID_HASH Invalid \fI\%hashkit_hash_algorithm_t\fP passed. .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_INVALID_ARGUMENT Invalid argument passed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B typedef enum \fI\%hashkit_hash_algorithm_t\fP hashkit_hash_algorithm_t .UNINDENT .INDENT 0.0 .TP .B enum hashkit_hash_algorithm_t .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_DEFAULT Default hash algorithm (one_at_a_time). .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_MD5 .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_CRC .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_FNV1_64 .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_FNV1A_64 .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_FNV1_32 .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_FNV1A_32 .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_HSIEH Only available if \fBlibhashkit\fP hash been built with HSIEH support. .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_MURMUR Only available if \fBlibhashkit\fP has been built with MURMUR support. .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_MURMUR3 Only available if \fBlibhashkit\fP has been built with MURMUR support. .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_JENKINS .UNINDENT .INDENT 7.0 .TP .B enumerator HASHKIT_HASH_CUSTOM Use custom \fI\%hashkit_hash_fn\fP function set through \fI\%hashkit_set_custom_function()\fP or \fI\%hashkit_set_custom_distribution_function()\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fI\%hashkit_return_t\fP hashkit_set_function(\fI\%hashkit_st\fP *hash, \fI\%hashkit_hash_algorithm_t\fP hash_algorithm) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhash\fP \-\- pointer to an initialized \fI\%hashkit_st\fP struct .IP \(bu 2 \fBhash_algorithm\fP \-\- valid \fI\%hashkit_hash_algorithm_t\fP constant .UNINDENT .TP .B Returns \fI\%hashkit_return_t\fP indicating success or failure .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fI\%hashkit_return_t\fP hashkit_set_custom_function(\fI\%hashkit_st\fP *hash, \fI\%hashkit_hash_fn\fP function, void *context) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhash\fP \-\- pointer to initialized \fI\%hashkit_st\fP struct .IP \(bu 2 \fBfunction\fP \-\- \fI\%hashkit_hash_fn\fP function pointer to use as hash function for \fI\%HASHKIT_HASH_CUSTOM\fP .IP \(bu 2 \fBcontext\fP \-\- pointer to an opaque user managed context for the custom hash function .UNINDENT .TP .B Returns \fI\%hashkit_return_t\fP indicating success or failure .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fI\%hashkit_hash_algorithm_t\fP hashkit_get_function(const \fI\%hashkit_st\fP *hash) .INDENT 7.0 .TP .B Parameters \fBhash\fP \-\- pointer to an initialized \fI\%hashkit_st\fP struct .TP .B Returns \fI\%hashkit_hash_algorithm_t\fP indicating the currently set hash algorithm to use .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fI\%hashkit_return_t\fP hashkit_set_distribution_function(\fI\%hashkit_st\fP *hash, \fI\%hashkit_hash_algorithm_t\fP hash_algorithm) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhash\fP \-\- pointer to an initialized \fI\%hashkit_st\fP struct .IP \(bu 2 \fBhash_algorithm\fP \-\- valid \fBhashkit_hash_algrothm_t\fP constant .UNINDENT .TP .B Returns \fI\%hashkit_return_t\fP indicating success or failure .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fI\%hashkit_return_t\fP hashkit_set_custom_distribution_function(\fI\%hashkit_st\fP *hash, \fI\%hashkit_hash_fn\fP function, void *context) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhash\fP \-\- pointer to initialized \fI\%hashkit_st\fP struct .IP \(bu 2 \fBfunction\fP \-\- \fI\%hashkit_hash_fn\fP function pointer to use as distribution hash function for \fI\%HASHKIT_HASH_CUSTOM\fP .IP \(bu 2 \fBcontext\fP \-\- pointer to an opaque user managed context for the custom distribution hash function .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fI\%hashkit_hash_algorithm_t\fP hashkit_get_distribution_function(const \fI\%hashkit_st\fP *hash) .INDENT 7.0 .TP .B Parameters \fBhash\fP \-\- pointer to an initialized \fI\%hashkit_st\fP struct .TP .B Returns \fI\%hashkit_hash_algorithm_t\fP indicating the currently set distribution hash algorithm to use .UNINDENT .UNINDENT .SS DESCRIPTION .sp These functions are used to set and retrieve the key and distribution hash functions. .SS RETURN VALUE .sp \fI\%hashkit_set_function()\fP, \fI\%hashkit_set_custom_function()\fP and the distribution equivalents return \fI\%hashkit_return_t::HASHKIT_SUCCESS\fP on success. .sp \fI\%hashkit_get_function()\fP and \fI\%hashkit_get_distribution_function()\fP return \fI\%hashkit_hash_algorithm_t\fP indicating the hash function used. .SS SEE ALSO .sp \fBlibhashkit(3)\fP \fBhashkit_create(3)\fP \fBhashkit_functions(3)\fP .SS Available Hashes .SS SYNOPSIS .INDENT 0.0 .TP .B #include Compile and link with \-lhashkit .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_default(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_fnv1_64(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_fnv1a_64(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_fnv1_32(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_fnv1a_32(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_crc32(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_hsieh(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_murmur(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_murmur3(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_jenkins(const char *key, size_t key_length) .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_md5(const char *key, size_t key_length) .UNINDENT .SS DESCRIPTION .sp 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 \fI\%hashkit_set_function()\fP or \fI\%hashkit_set_distribution_function()\fP\&. .sp The \fI\%hashkit_hsieh()\fP, \fI\%hashkit_murmur()\fP and \fI\%hashkit_murmur3()\fP functions are only available if the library is built with the appropriate flag enabled. .SS RETURN VALUE .sp A 32\-bit hash value. .SS SEE ALSO .sp \fBlibhashkit(3)\fP \fBhashkit_create(3)\fP \fBhashkit_function(3)\fP .SS Generate hash value .SS SYNOPSIS .INDENT 0.0 .TP .B #include Compile and link with \-lhashkit .UNINDENT .INDENT 0.0 .TP .B uint32_t hashkit_value(\fI\%hashkit_st\fP *hash, const char *key, size_t key_length) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhash\fP \-\- pointer to an initialized \fI\%hashkit_st\fP struct .IP \(bu 2 \fBkey\fP \-\- the key to genereate a hash of .IP \(bu 2 \fBkey_length\fP \-\- the length of the \fI\%key\fP without any terminating zero byte .UNINDENT .UNINDENT .UNINDENT .SS DESCRIPTION .sp The \fI\%hashkit_value()\fP 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. .SS RETURN VALUE .sp A 32\-bit hash value. .SS SEE ALSO .sp \fBlibhashkit(3)\fP \fBhashkit_create(3)\fP \fBhashkit_function(3)\fP \fBhashkit_functions(3)\fP .SH SEE ALSO .sp \fBlibmemcached(3)\fP \fBhashkit_create(3)\fP \fBhashkit_function(3)\fP \fBhashkit_functions(3)\fP \fBhashkit_value(3)\fP .\" Generated by docutils manpage writer. .