git.m6w6.name Git - awesomized/libmemcached/blob - docs/source/libhashkit/hashkit_function.rst

   1 Set Hash Function
   2 =================
   3
   4 SYNOPSIS
   5 --------
   6
   7 #include <libhashkit-|libhashkit_version|/hashkit.h>
   8   Compile and link with -lhashkit
   9
  10 .. type:: uint32_t (*hashkit_hash_fn)(const char *key, size_t key_length, void *context)
  11
  12     :param key: the key to generate a hash of
  13     :param key_length: the length of the `key` without any terminating zero byte
  14     :param context: the custom hash function context set through `hashkit_set_custom_function` or `hashkit_set_custom_distribution_function`
  15     :returns: the custom hash function should return a hash value for `key` as an unsigned 32bit integer
  16
  17 .. c:type:: enum hashkit_return_t hashkit_return_t
  18
  19 .. enum:: hashkit_return_t
  20
  21     .. enumerator:: HASHKIT_SUCCESS
  22
  23         Operation succeeded.
  24
  25     .. enumerator:: HASHKIT_FAILURE
  26
  27         Operation failed.
  28
  29     .. enumerator:: HASHKIT_MEMORY_ALLOCATION_FAILURE
  30
  31         Memory allocation failed.
  32
  33     .. enumerator:: HASHKIT_INVALID_HASH
  34
  35         Invalid `hashkit_hash_algorithm_t` passed.
  36
  37     .. enumerator:: HASHKIT_INVALID_ARGUMENT
  38
  39         Invalid argument passed.
  40
  41 .. c:type:: enum hashkit_hash_algorithm_t hashkit_hash_algorithm_t
  42
  43 .. enum:: hashkit_hash_algorithm_t
  44
  45     .. enumerator:: HASHKIT_HASH_DEFAULT
  46
  47         Default hash algorithm (one_at_a_time).
  48
  49     .. enumerator:: HASHKIT_HASH_MD5
  50     .. enumerator:: HASHKIT_HASH_CRC
  51     .. enumerator:: HASHKIT_HASH_FNV1_64
  52     .. enumerator:: HASHKIT_HASH_FNV1A_64
  53     .. enumerator:: HASHKIT_HASH_FNV1_32
  54     .. enumerator:: HASHKIT_HASH_FNV1A_32
  55     .. enumerator:: HASHKIT_HASH_HSIEH
  56
  57         Only available if `libhashkit` hash been built with HSIEH support.
  58
  59     .. enumerator:: HASHKIT_HASH_MURMUR
  60
  61         Only available if `libhashkit` has been built with MURMUR support.
  62
  63     .. enumerator:: HASHKIT_HASH_MURMUR3
  64
  65         Only available if `libhashkit` has been built with MURMUR support.
  66
  67     .. enumerator:: HASHKIT_HASH_JENKINS
  68     .. enumerator:: HASHKIT_HASH_CUSTOM
  69
  70         Use custom `hashkit_hash_fn` function set through `hashkit_set_custom_function` or `hashkit_set_custom_distribution_function`.
  71
  72 .. function:: hashkit_return_t hashkit_set_function(hashkit_st *hash, hashkit_hash_algorithm_t hash_algorithm)
  73
  74     :param hash: pointer to an initialized `hashkit_st` struct
  75     :param hash_algorithm: valid `hashkit_hash_algorithm_t` constant
  76     :returns: `hashkit_return_t` indicating success or failure
  77
  78 .. function:: hashkit_return_t hashkit_set_custom_function(hashkit_st *hash, hashkit_hash_fn function, void *context)
  79
  80     :param hash: pointer to initialized `hashkit_st` struct
  81     :param function: `hashkit_hash_fn` function pointer to use as hash function for `HASHKIT_HASH_CUSTOM`
  82     :param context: pointer to an opaque user managed context for the custom hash function
  83     :returns: `hashkit_return_t` indicating success or failure
  84
  85 .. function:: hashkit_hash_algorithm_t hashkit_get_function(const hashkit_st *hash)
  86
  87     :param hash: pointer to an initialized `hashkit_st` struct
  88     :returns: `hashkit_hash_algorithm_t` indicating the currently set hash algorithm to use
  89
  90 .. function:: hashkit_return_t hashkit_set_distribution_function(hashkit_st *hash, hashkit_hash_algorithm_t hash_algorithm)
  91
  92     :param hash: pointer to an initialized `hashkit_st` struct
  93     :param hash_algorithm: valid `hashkit_hash_algrothm_t` constant
  94     :returns: `hashkit_return_t` indicating success or failure
  95
  96 .. function:: hashkit_return_t hashkit_set_custom_distribution_function(hashkit_st *hash, hashkit_hash_fn function, void *context)
  97
  98     :param hash: pointer to initialized `hashkit_st` struct
  99     :param function: `hashkit_hash_fn` function pointer to use as distribution hash function for `HASHKIT_HASH_CUSTOM`
 100     :param context: pointer to an opaque user managed context for the custom distribution hash function
 101
 102 .. function:: hashkit_hash_algorithm_t hashkit_get_distribution_function(const hashkit_st *hash)
 103
 104     :param hash: pointer to an initialized `hashkit_st` struct
 105     :returns: `hashkit_hash_algorithm_t` indicating the currently set distribution hash algorithm to use
 106
 107 DESCRIPTION
 108 -----------
 109
 110 These functions are used to set and retrieve the key and distribution hash functions.
 111
 112 RETURN VALUE
 113 ------------
 114
 115 `hashkit_set_function`, `hashkit_set_custom_function` and the distribution
 116 equivalents return `hashkit_return_t::HASHKIT_SUCCESS` on success.
 117
 118 `hashkit_get_function` and `hashkit_get_distribution_function` return
 119 `hashkit_hash_algorithm_t` indicating the hash function used.
 120
 121 SEE ALSO
 122 --------
 123
 124 .. only:: man
 125
 126     :manpage:`libhashkit(3)`
 127     :manpage:`hashkit_create(3)`
 128     :manpage:`hashkit_functions(3)`
 129
 130 .. only:: html
 131
 132     * :doc:`../libhashkit`
 133     * :doc:`hashkit_create`
 134     * :doc:`hashkit_functions`
 135