Man page - libhashkit(3)

Packages contains this manual

Package: libhashkit-dev
apt-get install libhashkit-dev

Manuals in package:

Documentations in package:

libhashkit-dev

Manual

LIBHASHKIT

NAME
SYNOPSIS
DESCRIPTION
Creating a hashkit structure
SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO
Set Hash Function
SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO
Available Hashes
SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO
Generate hash value
SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO
SEE ALSO

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

typedef struct hashkit_st hashkit_st
hashkit_st *hashkit_create( hashkit_st *hash)

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

hashkit_st *hashkit_clone( hashkit_st *destination, const hashkit_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 ptr

void hashkit_free( hashkit_st *hash)

Parameters

hash -- pointer to an initialized hashkit_st struct

bool hashkit_is_allocated(const hashkit_st *hash)

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.

Set Hash Function

SYNOPSIS

#include <libhashkit-1.0/hashkit.h>

Compile and link with -lhashkit

typedef 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

typedef 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.

typedef 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() .

hashkit_return_t hashkit_set_function( hashkit_st *hash,
hashkit_hash_algorithm_t hash_algorithm)

Parameters

	•		hash -- pointer to an initialized hashkit_st struct
	•		hash_algorithm -- valid hashkit_hash_algorithm_t constant

Returns

hashkit_return_t indicating success or failure

hashkit_return_t hashkit_set_custom_function( hashkit_st *hash,
hashkit_hash_fn function, 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

Returns

hashkit_return_t indicating success or failure

hashkit_hash_algorithm_t hashkit_get_function(const hashkit_st *hash)

Parameters

hash -- pointer to an initialized hashkit_st struct

Returns

hashkit_hash_algorithm_t indicating the currently set hash algorithm to use

hashkit_return_t hashkit_set_distribution_function( hashkit_st *hash,
hashkit_hash_algorithm_t hash_algorithm)

Parameters

	•		hash -- pointer to an initialized hashkit_st struct
	•		hash_algorithm -- valid hashkit_hash_algrothm_t constant

Returns

hashkit_return_t indicating success or failure

hashkit_return_t hashkit_set_custom_distribution_function( hashkit_st
*hash, hashkit_hash_fn function, 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_t hashkit_get_distribution_function(const
hashkit_st *hash)

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.

Available Hashes

SYNOPSIS

#include <libhashkit-1.0/hashkit.h>

Compile and link with -lhashkit

uint32_t hashkit_default(const char *key, size_t key_length)
uint32_t hashkit_fnv1_64(const char *key, size_t key_length)
uint32_t hashkit_fnv1a_64(const char *key, size_t key_length)
uint32_t hashkit_fnv1_32(const char *key, size_t key_length)
uint32_t hashkit_fnv1a_32(const char *key, size_t key_length)
uint32_t hashkit_crc32(const char *key, size_t key_length)
uint32_t hashkit_hsieh(const char *key, size_t key_length)
uint32_t hashkit_murmur(const char *key, size_t key_length)
uint32_t hashkit_murmur3(const char *key, size_t key_length)
uint32_t hashkit_jenkins(const char *key, size_t key_length)
uint32_t hashkit_md5(const char *key, size_t key_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.

RETURN VALUE

A 32-bit hash value.

Generate hash value

SYNOPSIS

#include <libhashkit-1.0/hashkit.h>

Compile and link with -lhashkit

uint32_t hashkit_value( hashkit_st *hash, const char *key, size_t
key_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.

RETURN VALUE

A 32-bit hash value.