diff --git a/doc/Makefile.in b/doc/Makefile.in index 0c2dc26..dbd9daa 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -89,6 +89,25 @@ OBJECTS=CK_ARRAY_FOREACH \ ck_hs_reset \ ck_hs_reset_size \ ck_hs_stat \ + ck_rhs_gc \ + ck_rhs_init \ + ck_rhs_destroy \ + CK_RHS_HASH \ + ck_rhs_apply \ + ck_rhs_iterator_init \ + ck_rhs_next \ + ck_rhs_get \ + ck_rhs_put \ + ck_rhs_set \ + ck_rhs_fas \ + ck_rhs_remove \ + ck_rhs_move \ + ck_rhs_grow \ + ck_rhs_rebuild \ + ck_rhs_count \ + ck_rhs_reset \ + ck_rhs_reset_size \ + ck_rhs_stat \ ck_rwcohort \ CK_RWCOHORT_INIT \ CK_RWCOHORT_INSTANCE \ diff --git a/doc/ck_rhs_apply b/doc/ck_rhs_apply new file mode 100644 index 0000000..80b1da7 --- /dev/null +++ b/doc/ck_rhs_apply @@ -0,0 +1,86 @@ +.\" +.\" Copyright 2014 Samy Al Bahra. +.\" Copyright 2014 Backtrace I/O, Inc. +.\" 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 1, 2014 +.Dt CK_RHS_APPLY 3 +.Sh NAME +.Nm ck_rhs_apply +.Nd apply a function to hash set value +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft void * +.Fn ck_rhs_apply_fn_t "void *key" "void *closure" +.Ft bool +.Fn ck_rhs_apply "ck_rhs_t *hs" "unsigned long hash" "const void *key" "ck_rhs_apply_fn_t *function" "void *argument" +.Sh DESCRIPTION +The +.Fn ck_rhs_apply 3 +function will lookup the hash set slot associated with +.Fa key +and pass it to function pointed to by +.Fa function +for further action. This callback may remove or replace +the value by respectively returning NULL or a pointer to +another object with an identical key. The first argument +passed to +.Fa function +is a pointer to the object found in the hash set and +the second argument is the +.Fa argument +pointer passed to +.Fn ck_rhs_apply 3 . +If the pointer returned by +.Fa function +is equivalent to the first argument then no modification +is made to the hash set. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_rhs_apply 3 +returns true and otherwise returns false on failure. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.Xr ck_rhs_move 3 , +.Xr ck_rhs_destroy 3 , +.Xr ck_rhs_fas 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_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/ diff --git a/doc/ck_rhs_count b/doc/ck_rhs_count new file mode 100644 index 0000000..3a42b12 --- /dev/null +++ b/doc/ck_rhs_count @@ -0,0 +1,70 @@ +.\" +.\" 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_COUNT 3 +.Sh NAME +.Nm ck_rhs_count +.Nd returns number of entries in hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft unsigned long +.Fn ck_rhs_count "ck_rhs_t *hs" +.Sh DESCRIPTION +The +.Fn ck_rhs_count 3 +function returns the number of keys currently +stored in +.Fa hs . +.Sh ERRORS +Behavior is undefined if +.Fa hs +is uninitialized. Behavior is +undefined if this function is called by a non-writer +thread. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_reset 3 , +.Xr ck_rhs_reset_size 3 , +.Xr ck_rhs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_rhs_destroy b/doc/ck_rhs_destroy new file mode 100644 index 0000000..68de27e --- /dev/null +++ b/doc/ck_rhs_destroy @@ -0,0 +1,77 @@ +.\" +.\" 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_DESTROY 3 +.Sh NAME +.Nm ck_rhs_destroy +.Nd destroy hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft void +.Fn ck_rhs_destroy "ck_rhs_t *hs" +.Sh DESCRIPTION +The +.Fn ck_rhs_destroy 3 +function will request that the underlying allocator, as specified by the +.Xr ck_rhs_init 3 +function, immediately destroy the object pointed to by the +.Fa hs +argument. +The user must guarantee that no threads are accessing the object pointed to +by +.Fa hs +when +.Fn ck_rhs_destroy 3 +is called. +.Sh RETURN VALUES +.Fn ck_rhs_destroy 3 +has no return value. +.Sh ERRORS +This function is guaranteed not to fail. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.Xr ck_rhs_move 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/ diff --git a/doc/ck_rhs_fas b/doc/ck_rhs_fas new file mode 100644 index 0000000..453c40b --- /dev/null +++ b/doc/ck_rhs_fas @@ -0,0 +1,98 @@ +.\" +.\" Copyright 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 June 20, 2013 +.Dt CK_RHS_FAS 3 +.Sh NAME +.Nm ck_rhs_fas +.Nd fetch and store key in hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_fas "ck_rhs_t *hs" "unsigned long hash" "const void *key" "void **previous" +.Sh DESCRIPTION +The +.Fn ck_rhs_fas 3 +function will fetch and store the key specified by the +.Fa key +argument in the hash set pointed to by the +.Fa hs +argument. The key specified by +.Fa key +is expected to have the hash value specified by the +.Fa hash +argument (which was previously generated using the +.Xr CK_RHS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_rhs_fas 3 +was successful then the key specified by +.Fa key +was successfully stored in the hash set pointed to by +.Fa hs . +The key must already exist in the hash set, and is +replaced by +.Fa key +and the previous value is stored into the void pointer +pointed to by the +.Fa previous +argument. If the key does not exist in the hash set +then the function will return false and the hash set +is unchanged. This function +is guaranteed to be stable with respect to memory usage. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_rhs_fas 3 +returns true and otherwise returns false on failure. +.Sh ERRORS +Behavior is undefined if +.Fa key +or +.Fa hs +are uninitialized. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_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/ diff --git a/doc/ck_rhs_gc b/doc/ck_rhs_gc new file mode 100644 index 0000000..0ad5324 --- /dev/null +++ b/doc/ck_rhs_gc @@ -0,0 +1,73 @@ +.\" +.\" Copyright 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 December 17, 2013 +.Dt CK_RHS_GC 3 +.Sh NAME +.Nm ck_rhs_gc +.Nd perform maintenance on a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_gc "ck_rhs_t *hs" +.Sh DESCRIPTION +The +.Fn ck_rhs_gc 3 +function will perform various maintenance routines on the hash set +pointed to by +.Fa hs , +including recalculating the maximum number of probes. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_rhs_gc 3 +returns true and otherwise returns false on failure due to memory allocation +failure. +.Sh ERRORS +This function will only return false if there are internal memory allocation +failures. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_grow 3 , +.Xr ck_rhs_rebuild 3 , +.Xr ck_rhs_set 3 , +.Xr ck_rhs_fas 3 , +.Xr ck_rhs_remove 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/ diff --git a/doc/ck_rhs_get b/doc/ck_rhs_get new file mode 100644 index 0000000..51c6e2f --- /dev/null +++ b/doc/ck_rhs_get @@ -0,0 +1,88 @@ +.\" +.\" 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_GET 3 +.Sh NAME +.Nm ck_rhs_get +.Nd load a key from a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft void * +.Fn ck_rhs_get "ck_rhs_t *hs" "unsigned long hash" "const void *key" +.Sh DESCRIPTION +The +.Fn ck_rhs_get 3 +function will return a pointer to a key in the hash set +.Fa hs +that is of equivalent value to the object pointed to by +.Fa key . +The key specified by +.Fa key +is expected to have the hash value specified by the +.Fa hash +argument (which is to have been previously generated using the +.Xr CK_RHS_HASH 3 +macro). +.Sh RETURN VALUES +If the provided key is a member of +.Fa hs +then a pointer to the key as stored in +.Fa hs +is returned. If the key was not found in +.Fa hs +then a value of +.Dv NULL +is returned. +.Sh ERRORS +Behavior is undefined if +.Fa entry +or +.Fa hs +are uninitialized. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_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/ diff --git a/doc/ck_rhs_grow b/doc/ck_rhs_grow new file mode 100644 index 0000000..f1cac26 --- /dev/null +++ b/doc/ck_rhs_grow @@ -0,0 +1,81 @@ +.\" +.\" 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_GROW 3 +.Sh NAME +.Nm ck_rhs_grow +.Nd enlarge hash set capacity +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_grow "ck_rhs_t *hs" "unsigned long capacity" +.Sh DESCRIPTION +The +.Fn ck_rhs_grow 3 +function will resize the hash set in order to be +able to store at least the number of entries specified by +.Fa capacity +at a load factor of one. The default hash set load factor +is 0.5. If you wish to minimize the likelihood of memory allocations +for a hash set meant to store n entries, then specify a +.Fa capacity +of 2n. The default behavior of ck_rhs is to round +.Fa capacity +to the next power of two if it is not already a power of two. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_rhs_grow 3 +returns true and otherwise returns false on failure. +.Sh ERRORS +Behavior is undefined if +.Fa hs +is uninitialized. This function will only +return false if there are internal memory allocation +failures. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_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/ 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/ diff --git a/doc/ck_rhs_iterator_init b/doc/ck_rhs_iterator_init new file mode 100644 index 0000000..4cfd083 --- /dev/null +++ b/doc/ck_rhs_iterator_init @@ -0,0 +1,78 @@ +.\" +.\" 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_ITERATOR_INIT 3 +.Sh NAME +.Nm ck_rhs_iterator_init +.Nd initialize hash set iterator +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Pp +.Dv ck_rhs_iterator_t iterator = CK_RHS_ITERATOR_INITIALIZER +.Pp +.Ft void +.Fn ck_rhs_iterator_init "ck_rhs_iterator_t *iterator" +.Sh DESCRIPTION +The +.Fn ck_rhs_iterator_init 3 +function will initialize the object pointed to +by the +.Fa iterator +argument. Alternatively, an iterator may be statically +initialized by assigning it to the CK_RHS_ITERATOR_INITIALIZER value. +.Pp +An iterator is used to iterate through hash set entries with the +.Xr ck_rhs_next 3 +function. +.Sh RETURN VALUES +.Fn ck_rhs_iterator_init 3 +has no return value. +.Sh ERRORS +This function will not fail. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.Xr ck_rhs_move 3 , +.Xr ck_rhs_destroy 3 , +.Xr CK_RHS_HASH 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/ diff --git a/doc/ck_rhs_move b/doc/ck_rhs_move new file mode 100644 index 0000000..45e38e7 --- /dev/null +++ b/doc/ck_rhs_move @@ -0,0 +1,90 @@ +.\" +.\" Copyright 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 July 18, 2013 +.Dt CK_RHS_MOVE 3 +.Sh NAME +.Nm ck_rhs_move +.Nd move one from hash set to another +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_move "ck_rhs_t *destination" "ck_rhs_t *source" "ck_rhs_hash_cb_t *hash_cb" "ck_rhs_compare_cb_t *compare_cb" "struct ck_malloc *m" +.Sh DESCRIPTION +The +.Fn ck_rhs_move 3 +function will initialize +.Fa source +from +.Fa destination . +The hash function is set to +.Fa hash_cb , +comparison function to +.Fa compare_cb +and the allocator callbacks to +.Fa m . +Further modifications to +.Fa source +will result in undefined behavior. Concurrent +.Xr ck_rhs_get 3 +and +.Xr ck_rhs_fas 3 +operations to +.Fa source +are legal until the next write operation to +.Fa destination . +.Pp +This operation moves ownership from one hash set object +to another and re-assigns callback functions to developer-specified +values. This allows for dynamic configuration of allocation +callbacks and is necessary for use-cases involving executable code +which may be unmapped underneath the hash set. +.Sh RETURN VALUES +Upon successful completion +.Fn ck_rhs_move 3 +returns true and otherwise returns false to indicate an error. +.Sh SEE ALSO +.Xr ck_rhs_init 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_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/ diff --git a/doc/ck_rhs_next b/doc/ck_rhs_next new file mode 100644 index 0000000..c90a7d6 --- /dev/null +++ b/doc/ck_rhs_next @@ -0,0 +1,92 @@ +.\" +.\" 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_NEXT 3 +.Sh NAME +.Nm ck_rhs_next +.Nd iterate to next entry in hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_next "ck_rhs_t *hs" "ck_rhs_iterator_t *iterator" "void **entry" +.Sh DESCRIPTION +The +.Fn ck_rhs_next 3 +function will increment the iterator object pointed to by +.Fa iterator +to point to the next non-empty hash set entry. If +.Fn ck_rhs_next 3 +returns true then the pointer pointed to by +.Fa entry +is initialized to the current hash set key pointed to by the +.Fa iterator +object. +.Pp +It is expected that +.Fa iterator +has been initialized using the +.Xr ck_rhs_iterator_init 3 +function or statically initialized using CK_RHS_ITERATOR_INITIALIZER. +.Sh RETURN VALUES +If +.Fn ck_rhs_next 3 +returns true then the object pointed to by +.Fa entry +points to a valid hash set key. If +.Fn ck_rhs_next 3 +returns false then the value of the object pointed to by +.Fa entry +is undefined. +.Sh ERRORS +Behavior is undefined if +.Fa iterator +or +.Fa hs +are uninitialized. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.Xr ck_rhs_move 3 , +.Xr ck_rhs_destroy 3 , +.Xr CK_RHS_HASH 3 , +.Xr ck_rhs_iterator_init 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/ diff --git a/doc/ck_rhs_put b/doc/ck_rhs_put new file mode 100644 index 0000000..8df9b65 --- /dev/null +++ b/doc/ck_rhs_put @@ -0,0 +1,98 @@ +.\" +.\" 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_PUT 3 +.Sh NAME +.Nm ck_rhs_put +.Nd store unique key into a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_put "ck_rhs_t *hs" "unsigned long hash" "const void *key" +.Sh DESCRIPTION +The +.Fn ck_rhs_put 3 +function will store the key specified by the +.Fa key +argument in the hash set pointed to by the +.Fa hs +argument. The key specified by +.Fa key +is expected to have the hash value specified by the +.Fa hash +argument (which was previously generated using the +.Xr CK_RHS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_rhs_put 3 +was successful then the key specified by +.Fa key +was successfully stored in the hash set pointed to by +.Fa hs . +The function will fail if a key with an +equivalent value to +.Fa key +is already present in the hash set. For replacement +semantics, please see the +.Xr ck_rhs_set 3 +function. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_rhs_put 3 +returns true and otherwise returns false on failure. +.Sh ERRORS +Behavior is undefined if +.Fa key +or +.Fa hs +are uninitialized. The function will also +return false if the hash set could not be enlarged +to accomodate key insertion. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_put_unique 3 , +.Xr ck_rhs_get 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/ diff --git a/doc/ck_rhs_put_unique b/doc/ck_rhs_put_unique new file mode 100644 index 0000000..4f941ab --- /dev/null +++ b/doc/ck_rhs_put_unique @@ -0,0 +1,98 @@ +.\" +.\" Copyright 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 December 7, 2013 +.Dt CK_RHS_PUT_UNIQUE 3 +.Sh NAME +.Nm ck_rhs_put_unique +.Nd unconditionally store unique key into a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_put_unique "ck_rhs_t *hs" "unsigned long hash" "const void *key" +.Sh DESCRIPTION +The +.Fn ck_rhs_put_unique 3 +function will store the key specified by the +.Fa key +argument in the hash set pointed to by the +.Fa hs +argument. The key specified by +.Fa key +is expected to have the hash value specified by the +.Fa hash +argument (which was previously generated using the +.Xr CK_RHS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_rhs_put 3 +was successful then the key specified by +.Fa key +was successfully stored in the hash set pointed to by +.Fa hs . +The function will cause undefined behavior if a key with an +equivalent value is already present in the hash set. For replacement +semantics, please see the +.Xr ck_rhs_set 3 +function. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_rhs_put_unique 3 +returns true and otherwise returns false on failure. +.Sh ERRORS +Behavior is undefined if +.Fa key +or +.Fa hs +are uninitialized. The function will also +return false if the hash set could not be enlarged +to accomodate key insertion. The function will +result in undefined behavior if called for an +already inserted key value. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_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/ diff --git a/doc/ck_rhs_rebuild b/doc/ck_rhs_rebuild new file mode 100644 index 0000000..8ab9b50 --- /dev/null +++ b/doc/ck_rhs_rebuild @@ -0,0 +1,76 @@ +.\" +.\" Copyright 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 December 7, 2013 +.Dt CK_RHS_REBUILD 3 +.Sh NAME +.Nm ck_rhs_rebuild +.Nd rebuild a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_rebuild "ck_rhs_t *hs" +.Sh DESCRIPTION +The +.Fn ck_rhs_rebuild 3 +function will regenerate the hash set pointed to by +.Fa hs . +This has the side-effect of pruning degradatory side-effects +of workloads that are delete heavy. The regenerated hash +set should have shorter probe sequences on average. This +operation will require a significant amount of memory +and is free to allocate a duplicate hash set in the +rebuild process. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_rhs_rebuild 3 +returns true and otherwise returns false on failure. +.Sh ERRORS +This function will only return false if there are internal memory allocation +failures. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_gc 3 , +.Xr ck_rhs_grow 3 , +.Xr ck_rhs_remove 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/ diff --git a/doc/ck_rhs_remove b/doc/ck_rhs_remove new file mode 100644 index 0000000..c83bf38 --- /dev/null +++ b/doc/ck_rhs_remove @@ -0,0 +1,92 @@ +.\" +.\" 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_REMOVE 3 +.Sh NAME +.Nm ck_rhs_remove +.Nd remove key from a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft void * +.Fn ck_rhs_remove "ck_rhs_t *hs" "unsigned long hash" "const void *key" +.Sh DESCRIPTION +The +.Fn ck_rhs_remove 3 +function will attempt to remove the key specified by the +.Fa key +argument in the hash set pointed to by the +.Fa hs +argument. The key specified by +.Fa key +is expected to have the hash value specified by the +.Fa hash +argument (which was previously generated using the +.Xr CK_RHS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_rhs_remove 3 +was successful then the key contained in the hash +set is returned. If the key was not a member of the hash +set then +.Dv NULL +is returned. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_rhs_remove 3 +returns a pointer to a key and otherwise returns +.Dv NULL +on failure. +.Sh ERRORS +Behavior is undefined if +.Fa key +or +.Fa hs +are uninitialized. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_grow 3 , +.Xr ck_rhs_gc 3 , +.Xr ck_rhs_rebuild 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/ diff --git a/doc/ck_rhs_reset b/doc/ck_rhs_reset new file mode 100644 index 0000000..a750d85 --- /dev/null +++ b/doc/ck_rhs_reset @@ -0,0 +1,77 @@ +.\" +.\" 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_RESET 3 +.Sh NAME +.Nm ck_rhs_reset +.Nd remove all keys from a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_reset "ck_rhs_t *hs" +.Sh DESCRIPTION +The +.Fn ck_rhs_reset 3 +function will remove all keys stored in the hash +set pointed to by the +.Fa hs +argument. +.Sh RETURN VALUES +If successful, +.Fn ck_rhs_reset 3 +will return true and will otherwise return false on failure. This +function will only fail if a replacement hash set could not be +allocated internally. +.Sh ERRORS +Behavior is undefined if +.Fa hs +is uninitialized. Behavior is +undefined if this function is called by a non-writer +thread. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_reset_size 3 , +.Xr ck_rhs_grow 3 , +.Xr ck_rhs_gc 3 , +.Xr ck_rhs_rebuild 3 , +.Xr ck_rhs_count 3 , +.Xr ck_rhs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_rhs_reset_size b/doc/ck_rhs_reset_size new file mode 100644 index 0000000..6e9913e --- /dev/null +++ b/doc/ck_rhs_reset_size @@ -0,0 +1,80 @@ +.\" +.\" 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 May 5, 2013 +.Dt CK_RHS_RESET_SIZE 3 +.Sh NAME +.Nm ck_rhs_reset_size +.Nd remove all keys from a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_reset_size "ck_rhs_t *hs" "unsigned long size" +.Sh DESCRIPTION +The +.Fn ck_rhs_reset_size 3 +function will remove all keys stored in the hash +set pointed to by the +.Fa hs +argument and create a new generation of the hash set that +is preallocated for +.Fa size +entries. +.Sh RETURN VALUES +If successful, +.Fn ck_rhs_reset_size 3 +will return true and will otherwise return false on failure. This +function will only fail if a replacement hash set could not be +allocated internally. +.Sh ERRORS +Behavior is undefined if +.Fa hs +is uninitialized. Behavior is +undefined if this function is called by a non-writer +thread. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_gc 3 , +.Xr ck_rhs_rebuild 3 , +.Xr ck_rhs_count 3 , +.Xr ck_rhs_reset 3 , +.Xr ck_rhs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_rhs_set b/doc/ck_rhs_set new file mode 100644 index 0000000..6f3e280 --- /dev/null +++ b/doc/ck_rhs_set @@ -0,0 +1,102 @@ +.\" +.\" 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_SET 3 +.Sh NAME +.Nm ck_rhs_set +.Nd store key into a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_set "ck_rhs_t *hs" "unsigned long hash" "const void *key" "void **previous" +.Sh DESCRIPTION +The +.Fn ck_rhs_set 3 +function will store the key specified by the +.Fa key +argument in the hash set pointed to by the +.Fa hs +argument. The key specified by +.Fa key +is expected to have the hash value specified by the +.Fa hash +argument (which was previously generated using the +.Xr CK_RHS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_rhs_set 3 +was successful then the key specified by +.Fa key +was successfully stored in the hash set pointed to by +.Fa hs . +If the key already exists in the hash set, then it is +replaced by +.Fa key +and the previous value is stored into the void pointer +pointed to by the +.Fa previous +argument. If previous is set to +.Dv NULL +then +.Fa key +was not a replacement for an existing entry in the hash set. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_rhs_set 3 +returns true and otherwise returns false on failure. +.Sh ERRORS +Behavior is undefined if +.Fa key +or +.Fa hs +are uninitialized. The function will also +return false if the hash set could not be enlarged +to accomodate key insertion. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_fas 3 , +.Xr ck_rhs_remove 3 , +.Xr ck_rhs_grow 3 , +.Xr ck_rhs_gc 3 , +.Xr ck_rhs_rebuild 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/ diff --git a/doc/ck_rhs_stat b/doc/ck_rhs_stat new file mode 100644 index 0000000..df45672 --- /dev/null +++ b/doc/ck_rhs_stat @@ -0,0 +1,80 @@ +.\" +.\" 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_STAT 3 +.Sh NAME +.Nm ck_rhs_stat +.Nd get hash set status +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft void +.Fn ck_rhs_stat "ck_rhs_t *hs" "struct ck_rhs_stat *st" +.Sh DESCRIPTION +The +.Fn ck_rhs_stat 3 +function will store various hash set statistics in +the object pointed to by +.Fa st . +The ck_rhs_stat structure is defined as follows: +.Bd -literal -offset indent +struct ck_rhs_stat { + unsigned long n_entries; /* Current number of keys in hash set. */ + unsigned int probe_maximum; /* Longest read-side probe sequence. */ +}; +.Ed +.Sh RETURN VALUES +.Fn ck_rhs_stat 3 +has no return value. +.Sh ERRORS +Behavior is undefined if +.Fa hs +is uninitialized. Behavior is +undefined if this function is called by a non-writer +thread. +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.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_gc 3 , +.Xr ck_rhs_rebuild 3 , +.Xr ck_rhs_count 3 , +.Xr ck_rhs_reset 3 , +.Xr ck_rhs_reset_size 3 +.Pp +Additional information available at http://concurrencykit.org/