Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CK_HT_INIT(3)		 BSD Library Functions Manual		 CK_HT_INIT(3)

NAME
     ck_ht_init	-- initialize a	hash table

LIBRARY
     Concurrency Kit (libck, -lck)

SYNOPSIS
     #include <ck_ht.h>

     typedef void
     ck_ht_hash_cb_t(ck_ht_hash_t *h, const void *key, size_t key_length,
	 uint64_t seed);

     bool
     ck_ht_init(ck_ht_t	*ht, enum ck_ht_mode mode,
	 ck_ht_hash_cb_t *hash_function, struct	ck_malloc *allocator,
	 uint64_t capacity, uint64_t seed);

DESCRIPTION
     The ck_ht_init() function initializes the hash table pointed to by	the ht
     pointer.

     The argument mode specifies the type of key-value pairs to	be stored in
     the hash table. The value of mode may be one of:

     CK_HT_MODE_BYTESTRING
	     The hash table is meant to	store key-value	pointers where key is
	     a region of memory	that is	up to 65536 bytes long.	 This pointer
	     will be dereferenced during hash table operations for key compar-
	     ison. Entries of this hash	table are expected to be interacted
	     with using	the ck_ht_entry_empty(3), ck_ht_entry_key(3),
	     ck_ht_entry_key_length(3),	ck_ht_entry_value(3), and
	     ck_ht_entry_set(3)	functions. Attempting a	hash table operation
	     with a key	of value NULL or (void *)UINTPTR_MAX will result in
	     undefined behavior.

     CK_HT_MODE_DIRECT
	     The hash table is meant to	store key-value	pointers where the key
	     is	of fixed width field compatible	with the uintptr_t type. The
	     key will be directly compared with	other keys for equality. En-
	     tries of this hash	table are expected to be interacted with using
	     the ck_ht_entry_empty(3), ck_ht_entry_key_direct(3),
	     ck_ht_entry_value_direct(3) and ck_ht_entry_set_direct(3) func-
	     tions. Attempting a hash table operation with a key of value of 0
	     or	UINTPTR_MAX will result	in undefined behavior.

     In	addition to this, the user may bitwise OR the mode flag	with
     CK_HT_WORKLOAD_DELETE to indicate that the	hash table will	have to	handle
     a delete heavy workload, in which case stronger bounds on latency can be
     provided at the cost of approximately 13% higher memory usage.  The argu-
     ment hash_function	is a pointer to	a user-specified hash function.	It is
     optional, if NULL is specified, then the default hash function implemen-
     tation will be used ( ck_ht_hash(3) ). A user-specified hash function
     takes four	arguments. The h argument is a pointer to a hash value object.
     The hash function is expected to update the value object of type uint64_t
     contained with-in the object pointed to by	h.  The	key argument is	a
     pointer to	a key, the key_length argument is the length of	the key	and
     the seed argument is the initial seed associated with the hash table.
     This initial seed is specified by the user	in ck_ht_init(3).

     The allocator argument is a pointer to a structure	containing malloc and
     free function pointers which respectively define the memory allocation
     and destruction functions to be used by the hash table being initialized.

     The argument capacity represents the initial number of key-value pairs
     the hash table is expected	to contain. This argument is simply a hint and
     the underlying implementation is free to allocate more or less memory
     than necessary to contain the number of entries capacity specifies.

     The argument seed specifies the initial seed used by the underlying hash
     function.	The user is free to choose a value of their choice.

     The hash table is safe to access by multiple readers in the presence of
     one concurrent writer. Behavior is	undefined in the presence of concur-
     rent writers.

RETURN VALUES
     Upon successful completion	ck_ht_init() returns a value of	true and oth-
     erwise returns a value of false to	indicate an error.

ERRORS
     The behavior of ck_ht_init() is undefined if ht is	not a pointer to a
     ck_ht_t object.

SEE ALSO
     ck_ht_stat(3), ck_ht_destroy(3), ck_ht_hash(3), ck_ht_hash_direct(3),
     ck_ht_set_spmc(3),	ck_ht_put_spmc(3), ck_ht_gc(3),	ck_ht_get_spmc(3),
     ck_ht_grow_spmc(3), ck_ht_remove_spmc(3), ck_ht_reset_spmc(3),
     ck_ht_reset_size_spmc(3), ck_ht_count(3), ck_ht_entry_empty(3),
     ck_ht_entry_key_set(3), ck_ht_entry_key_set_direct(3),
     ck_ht_entry_key(3), ck_ht_entry_key_length(3), ck_ht_entry_value(3),
     ck_ht_entry_set(3), ck_ht_entry_set_direct(3), ck_ht_entry_key_direct(3),
     ck_ht_entry_value_direct(3), ck_ht_iterator_init(3), ck_ht_next(3)

     Additional	information available at http://concurrencykit.org/

				March 28, 2012

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ck_ht_init&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help