diff options
Diffstat (limited to 'doc/ck_rhs_init')
| -rw-r--r-- | doc/ck_rhs_init | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/doc/ck_rhs_init b/doc/ck_rhs_init new file mode 100644 index 0000000..17c5097 --- /dev/null +++ b/doc/ck_rhs_init @@ -0,0 +1,166 @@ +.\" +.\" Copyright 2012-2013 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 September 17, 2012 +.Dt CK_RHS_INIT 3 +.Sh NAME +.Nm ck_rhs_init +.Nd initialize a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft typedef unsigned long +.Fn ck_rhs_hash_cb_t "const void *key" "unsigned long seed" +.Ft typedef bool +.Fn ck_rhs_compare_cb_t "const void *c1" "const void *c2" +.Ft bool +.Fn ck_rhs_init "ck_rhs_t *hs" "unsigned int mode" "ck_rhs_hash_cb_t *hash_function" "ck_rhs_compare_cb_t *compare" "struct ck_malloc *allocator" "unsigned long capacity" "unsigned long seed" +.Sh DESCRIPTION +The +.Fn ck_rhs_init +function initializes the hash set pointed to by the +.Fa hs +pointer. +.Pp +The argument +.Fa mode +specifies the type of key-value pairs to be stored in the +hash set as well as the expected concurrent access model. +The value of +.Fa mode +consists of a bitfield of one of the following: +.Bl -tag -width indent +.It CK_RHS_MODE_OBJECT +The hash set is meant to store pointers to objects. This provides +a hint that only CK_MD_VMA_BITS are necessary to encode the key +argument. Any unused pointer bits are leveraged for internal +optimizations. +.It CK_RHS_MODE_DIRECT +The hash set is meant to directly store key values and that all +bits of the key are used to encode values. +.It CK_RHS_MODE_READ_MOSTLY +Optimize read operations over put/delete. +.El +.Pp +The concurrent access model is specified by: +.Bl -tag -width indent +.It CK_RHS_MODE_SPMC +The hash set should allow for concurrent readers in the +presence of a single writer. +.It CK_RHS_MODE_MPMC +The hash set should allow for concurrent readers in the +presence of concurrent writers. This is currently unsupported. +.El +.Pp +The developer is free to specify additional workload hints. +These hints are one of: +.Bl -tag -width indent +.El +.Pp +The argument +.Fa hash_function +is a mandatory pointer to a user-specified hash function. +A user-specified hash function takes two arguments. The +.Fa key +argument is a pointer to a key. The +.Fa seed +argument is the initial seed associated with the hash set. +This initial seed is specified by the user in +.Xr ck_rhs_init 3 . +.Pp +The +.Fa compare +argument is an optional pointer to a user-specified +key comparison function. If NULL is specified in this +argument, then pointer equality will be used to determine +key equality. A user-specified comparison function takes +two arguments representing pointers to the objects being +compared for equality. It is expected to return true +if the keys are of equal value and false otherwise. +.Pp +The +.Fa allocator +argument is a pointer to a structure containing +.Fa malloc +and +.Fa free +function pointers which respectively define the memory allocation and +destruction functions to be used by the hash set being initialized. +.Pp +The argument +.Fa capacity +represents the initial number of keys the hash +set 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. +.Sh RETURN VALUES +Upon successful completion +.Fn ck_rhs_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_rhs_init +is undefined if +.Fa hs +is not a pointer to a +.Tn ck_rhs_t +object. +.El +.Sh SEE ALSO +.Xr ck_rhs_move 3 , +.Xr ck_rhs_destroy 3 , +.Xr CK_RHS_HASH 3 , +.Xr ck_rhs_iterator_init 3 , +.Xr ck_rhs_next 3 , +.Xr ck_rhs_get 3 , +.Xr ck_rhs_put 3 , +.Xr ck_rhs_put_unique 3 , +.Xr ck_rhs_set 3 , +.Xr ck_rhs_fas 3 , +.Xr ck_rhs_remove 3 , +.Xr ck_rhs_grow 3 , +.Xr ck_rhs_rebuild 3 , +.Xr ck_rhs_gc 3 , +.Xr ck_rhs_count 3 , +.Xr ck_rhs_reset 3 , +.Xr ck_rhs_reset_size 3 , +.Xr ck_rhs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ |