From: Michael Wallner Date: Wed, 27 May 2020 12:23:27 +0000 (+0200) Subject: docs: libhashkit X-Git-Tag: 1.1.0-beta1~250^2~3 X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=d55b8d845388672d97fdeab8bf91066ba79b3103;p=m6w6%2Flibmemcached docs: libhashkit --- diff --git a/docs/source/libhashkit.rst b/docs/source/libhashkit.rst index e23c9248..9bda5cb7 100644 --- a/docs/source/libhashkit.rst +++ b/docs/source/libhashkit.rst @@ -11,7 +11,7 @@ DESCRIPTION ----------- `libhashkit` is a small and thread-safe client library that provides a collection -of useful hashing algorithm. +of useful hashing algorithms. `libhashkit` is distributed with `libmemcached`. diff --git a/docs/source/libhashkit/hashkit_create.rst b/docs/source/libhashkit/hashkit_create.rst index e74550f5..670bdd9c 100644 --- a/docs/source/libhashkit/hashkit_create.rst +++ b/docs/source/libhashkit/hashkit_create.rst @@ -11,17 +11,31 @@ SYNOPSIS .. function:: hashkit_st *hashkit_create(hashkit_st *hash) + :param 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 + .. function:: hashkit_st *hashkit_clone(hashkit_st *destination, const hashkit_st *ptr) + :param destination: memory address of a `hashkit_st` struct; + if a nullptr is passed, the struct will be dynamically allocated by libhashkit + :param ptr: pointer of the `hashkit_st` struct to copy + :returns: pointer to a `hashkit_st` structure (`destination`, if not nullptr), initialized from `ptr` + .. function:: void hashkit_free(hashkit_st *hash) + :param hash: pointer to an initialized `hashkit_st` struct + .. function:: bool hashkit_is_allocated(const hashkit_st *hash) + :param 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 NULL argument for hash, then the memory for the object is allocated. If you +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 @@ -31,14 +45,14 @@ 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 where the memory was allocated for a hashkit +The `hashkit_is_allocated` reports whether the memory was allocated for a hashkit object. RETURN VALUE ------------ -`hashkit_create` and `hashkit_clone` will return NULL on failure or non-NULL on -success. +`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 diff --git a/docs/source/libhashkit/hashkit_function.rst b/docs/source/libhashkit/hashkit_function.rst index 79b1efea..b55f3fb9 100644 --- a/docs/source/libhashkit/hashkit_function.rst +++ b/docs/source/libhashkit/hashkit_function.rst @@ -9,17 +9,100 @@ SYNOPSIS .. type:: uint32_t (*hashkit_hash_fn)(const char *key, size_t key_length, void *context) + :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 + +.. c:type:: enum hashkit_return_t hashkit_return_t + +.. enum:: hashkit_return_t + + .. 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. + +.. c:type:: enum hashkit_hash_algorithm_t hashkit_hash_algorithm_t + +.. enum:: hashkit_hash_algorithm_t + + .. enumerator:: HASHKIT_HASH_DEFAULT + + Default hash algorithm (one_at_a_time). + + .. enumerator:: HASHKIT_HASH_MD5 + .. enumerator:: HASHKIT_HASH_CRC + .. enumerator:: HASHKIT_HASH_FNV1_64 + .. enumerator:: HASHKIT_HASH_FNV1A_64 + .. enumerator:: HASHKIT_HASH_FNV1_32 + .. enumerator:: HASHKIT_HASH_FNV1A_32 + .. 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_JENKINS + .. enumerator:: HASHKIT_HASH_CUSTOM + + Use custom `hashkit_hash_fn` function set through `hashkit_set_custom_function` or `hashkit_set_custom_distribution_function`. + .. function:: hashkit_return_t hashkit_set_function(hashkit_st *hash, hashkit_hash_algorithm_t hash_algorithm) + :param hash: pointer to an initialized `hashkit_st` struct + :param hash_algorithm: valid `hashkit_hash_algorithm_t` constant + :returns: `hashkit_return_t` indicating success or failure + .. function:: hashkit_return_t hashkit_set_custom_function(hashkit_st *hash, hashkit_hash_fn function, void *context) + :param hash: pointer to initialized `hashkit_st` struct + :param function: `hashkit_hash_fn` function pointer to use as hash function for `HASHKIT_HASH_CUSTOM` + :param context: pointer to an opaque user managed context for the custom hash function + :returns: `hashkit_return_t` indicating success or failure + .. function:: hashkit_hash_algorithm_t hashkit_get_function(const hashkit_st *hash) + :param hash: pointer to an initialized `hashkit_st` struct + :returns: `hashkit_hash_algorithm_t` indicating the currently set hash algorithm to use + .. function:: hashkit_return_t hashkit_set_distribution_function(hashkit_st *hash, hashkit_hash_algorithm_t hash_algorithm) -.. function:: hashkit_return_t hashkit_set_custom_distribution_function(hashkit_st *self, hashkit_hash_fn function, void *context) + :param hash: pointer to an initialized `hashkit_st` struct + :param hash_algorithm: valid `hashkit_hash_algrothm_t` constant + :returns: `hashkit_return_t` indicating success or failure + +.. function:: hashkit_return_t hashkit_set_custom_distribution_function(hashkit_st *hash, hashkit_hash_fn function, void *context) + + :param hash: pointer to initialized `hashkit_st` struct + :param function: `hashkit_hash_fn` function pointer to use as distribution hash function for `HASHKIT_HASH_CUSTOM` + :param context: pointer to an opaque user managed context for the custom distribution hash function + +.. function:: hashkit_hash_algorithm_t hashkit_get_distribution_function(const hashkit_st *hash) -.. function:: hashkit_hash_algorithm_t hashkit_get_distribution_function(const hashkit_st *self) + :param hash: pointer to an initialized `hashkit_st` struct + :returns: `hashkit_hash_algorithm_t` indicating the currently set distribution hash algorithm to use DESCRIPTION ----------- @@ -30,7 +113,7 @@ RETURN VALUE ------------ `hashkit_set_function`, `hashkit_set_custom_function` and the distribution -equivalents return `hashkit_return_t` `HASHKIT_SUCCESS` on success. +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. diff --git a/docs/source/libhashkit/hashkit_functions.rst b/docs/source/libhashkit/hashkit_functions.rst index 04f6ba2b..9eccb060 100644 --- a/docs/source/libhashkit/hashkit_functions.rst +++ b/docs/source/libhashkit/hashkit_functions.rst @@ -33,11 +33,12 @@ DESCRIPTION ----------- These functions generate hash values from a key using a variety of -algorithms. These functions can be used standalone, or as arguments -to :func:`hashkit_set_hash_fn` or :func:`hashkit_set_continuum_hash_fn`. +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 :func:`hashkit_hsieh` is only available if the library is built with -the appropriate flag enabled. +The `hashkit_hsieh`, `hashkit_murmur` and `hashkit_murmur3` functions are +only available if the library is built with the appropriate flag enabled. RETURN VALUE ------------ diff --git a/docs/source/libhashkit/hashkit_value.rst b/docs/source/libhashkit/hashkit_value.rst index 1522b440..101630c7 100644 --- a/docs/source/libhashkit/hashkit_value.rst +++ b/docs/source/libhashkit/hashkit_value.rst @@ -9,6 +9,10 @@ SYNOPSIS .. function:: uint32_t hashkit_value(hashkit_st *hash, const char *key, size_t key_length) + :param hash: pointer to an initialized `hashkit_st` struct + :param key: the key to genereate a hash of + :param key_length: the length of the `key` without any terminating zero byte + DESCRIPTION -----------