.\"
.\" Copyright 2012 Samy Al Bahra.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"
.Dd March 28, 2012
.Dt CK_HT_INIT 3
.Sh NAME
.Nm ck_ht_init
.Nd initialize a hash table
.Sh LIBRARY
Concurrency Kit (libck, \-lck)
.Sh SYNOPSIS
.In ck_ht.h
.Ft bool
.Fn ck_ht_init "ck_ht_t *ht" "enum ck_ht_mode mode" "uint64_t capacity" "uint64_t seed"
.Sh DESCRIPTION
The 
.Fn ck_ht_init
function initializes the hash table pointed to by the
.Fa ht
pointer.
.Pp
The argument
.Fa mode
specifies the type of key-value pairs to be stored in the
hash table. The value of
.Fa mode
may be one of:
.Bl -tag -width indent
.It 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 comparison. Entries of this hash table are expected
to be interacted with using the
.Xr ck_ht_entry_empty 3 ,
.Xr ck_ht_entry_key 3 ,
.Xr ck_ht_entry_key_length 3 ,
.Xr ck_ht_entry_value 3 ,
and
.Xr ck_ht_entry_set 3
functions.
.It 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
.Tn uintptr_t
type. The key will be directly compared with other keys for
equality.
.El
.Pp
The argument
.Fa 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
.Fa capacity
specifies.
.Pp
The argument
.Fa seed
specifies the initial seed used by the underlying hash function.
The user is free to choose a value of their choice.
.Pp
The hash table is safe to access by multiple readers in the presence
of one concurrent writer. Behavior is undefined in the presence of
concurrent writers.
.Sh RETURN VALUES
Upon successful completion
.Fn ck_ht_init
returns a value of
.Dv true
and otherwise returns a value of
.Dv false
to indicate an error.
.Sh ERRORS
.Bl -tag -width Er
.Pp
The behavior of
.Fn ck_ht_init
is undefined if
.Fa ht
is not a pointer to a
.Tn ck_ht_t
object. The behavior is undefined if there is not exactly one preceding and successful
call made to the
.Xr ck_ht_allocator_set 3
function.
.El
.Sh SEE ALSO
.Xr ck_ht_allocator_set 3 ,
.Xr ck_ht_destroy 3 ,
.Xr ck_ht_hash 3 ,
.Xr ck_ht_hash_direct 3 ,
.Xr ck_ht_set_spmc 3 ,
.Xr ck_ht_put_spmc 3 ,
.Xr ck_ht_get_spmc 3 ,
.Xr ck_ht_grow_spmc 3 ,
.Xr ck_ht_remove_spmc 3 ,
.Xr ck_ht_reset_spmc 3 ,
.Xr ck_ht_count 3 ,
.Xr ck_ht_entry_empty 3 ,
.Xr ck_ht_entry_key_set 3 ,
.Xr ck_ht_entry_key_set_direct 3 ,
.Xr ck_ht_entry_key 3 ,
.Xr ck_ht_entry_key_length 3 ,
.Xr ck_ht_entry_value 3 ,
.Xr ck_ht_entry_set 3 ,
.Xr ck_ht_entry_set_direct 3 ,
.Xr ck_ht_entry_key_direct 3 ,
.Xr ck_ht_entry_value_direct 3 ,
.Xr ck_ht_iterator_init 3 ,
.Xr ck_ht_next 3
.Pp
Additional information available at http://concurrencykit.org/