diff options
Diffstat (limited to 'doc')
172 files changed, 16147 insertions, 0 deletions
diff --git a/doc/CK_ARRAY_FOREACH b/doc/CK_ARRAY_FOREACH new file mode 100644 index 0000000..d85b767 --- /dev/null +++ b/doc/CK_ARRAY_FOREACH @@ -0,0 +1,79 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_FOREACH 3 +.Sh NAME +.Nm CK_ARRAY_FOREACH +.Nd iterate through an array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft bool +.Fn CK_ARRAY_FOREACH "ck_array_t *array" "ck_array_iterator_t *iterator" "void **b" +.Sh DESCRIPTION +The +.Fn CK_ARRAY_FOREACH 3 +macro iterates through the array pointed to by +.Fa array . +A pointer to an iterator object must be specified by +.Fa iterator +and +.Fa b +must point to a void pointer. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_array.h> + +/* Assume this was already previously initialized. */ +ck_array_t array; + +void +example(void) +{ + ck_array_iterator_t iterator; + void *pointer; + + CK_ARRAY_FOREACH(&array, &iterator, &pointer) { + do_something(pointer); + } +} +.Ed +.Sh RETURN VALUES +This macro has no return value. +.Sh SEE ALSO +.Xr ck_array_init 3 , +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_deinit 3 +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_INIT b/doc/CK_COHORT_INIT new file mode 100644 index 0000000..94454d9 --- /dev/null +++ b/doc/CK_COHORT_INIT @@ -0,0 +1,66 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_COHORT_INIT 3 +.Sh NAME +.Nm CK_COHORT_INIT +.Nd initialize instance of a cohort type +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_COHORT_INIT "COHORT_NAME cohort_name" "COHORT *cohort" "void *global_lock" \ +"void *local_lock" "unsigned int pass_limit" +.Sh DESCRIPTION +Until a cohort instance is initialized using the CK_COHORT_INIT macro, any operations +involving it will have undefined behavior. After this macro has been called, the cohort +pointed to by the +.Fa cohort +argument will use the lock pointed to by +.Fa global_lock +as its global lock and the lock pointed to by +.Fa local_lock +as its local lock. +.Pp +The cohort will relinquish its global lock after +.Fa pass_limit +consecutive acquisitions of its local lock, even if there are other threads waiting. +If you are unsure of a value to use for the +.Fa pass_limit +argument, you should use CK_COHORT_DEFAULT_LOCAL_PASS_LIMIT. +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_COHORT_PROTOTYPE 3 , +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_COHORT_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_INSTANCE b/doc/CK_COHORT_INSTANCE new file mode 100644 index 0000000..cec1617 --- /dev/null +++ b/doc/CK_COHORT_INSTANCE @@ -0,0 +1,59 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_COHORT_INSTANCE 3 +.Sh NAME +.Nm CK_COHORT_INSTANCE +.Nd declare an instance of a cohort type +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_COHORT_INSTANCE "COHORT_NAME cohort_name" +.Sh DESCRIPTION +The user must use this macro to declare instances of cohort types that they have +defined. For instance, if they have used the CK_COHORT_PROTOTYPE macro to define +a cohort type with name foo, they would create an instance of this type as follows: +.br +CK_COHORT_INSTANCE(foo) cohort; +.Pp +This macro should also be used when allocating memory for cohorts. For instance, +to allocate a block of 4 cohorts: +.br +CK_COHORT_INSTANCE(foo) *cohorts = malloc(4 * sizeof(CK_COHORT_INSTANCE(foo))); +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_COHORT_PROTOTYPE 3 , +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_COHORT_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_LOCK b/doc/CK_COHORT_LOCK new file mode 100644 index 0000000..22475f8 --- /dev/null +++ b/doc/CK_COHORT_LOCK @@ -0,0 +1,61 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_COHORT_LOCK 3 +.Sh NAME +.Nm CK_COHORT_LOCK +.Nd acquire cohort lock +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_COHORT_LOCK "COHORT_NAME cohort_name" "COHORT *cohort" "void *global_context" \ +"void *local_context" +.Sh DESCRIPTION +This call attempts to acquire both the local and global (if necessary) locks from +.Fa cohort . +The call will block until both locks have been acquired. +.Fa global_context +will be passed as the second argument to the function that was provided as the +.Fa global_lock_method +argument to CK_COHORT_PROTOTYPE if that method is called, and +.Fa local_context +will be passed to the function specified by +.Fa local_lock_method +. +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_COHORT_PROTOTYPE 3 , +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_COHORT_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_PROTOTYPE b/doc/CK_COHORT_PROTOTYPE new file mode 100644 index 0000000..7a7b1a7 --- /dev/null +++ b/doc/CK_COHORT_PROTOTYPE @@ -0,0 +1,76 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_COHORT_PROTOTYPE 3 +.Sh NAME +.Nm CK_COHORT_PROTOTYPE +.Nd define cohort type with specified lock types +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_COHORT_PROTOTYPE "COHORT_NAME cohort_name" "TYPE global_lock_method" \ +"LOCK_FXN global_unlock_method" "LOCK_FXN local_lock_method" "LOCK_FXN local_unlock_method" +.Sh DESCRIPTION +The ck_cohort.h header file does not define any cohort types. Instead, the user must use +the CK_COHORT_PROTOTYPE or +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 +macros to define any types they want to use. They must use CK_COHORT_TRYLOCK_PROTOTYPE +if they want their cohort type to support trylock operations. +The CK_COHORT_PROTOTYPE macro takes the following arguments: +.Pp +.Fa cohort_name +: An identifier used for this cohort type. This will have to be passed to each +of the other CK_COHORT macros. +.br +.Fa global_lock_method +: The method that should be called to acquire the global lock +.br +.Fa global_unlock_method +: The method that should be called to relinquish the global lock +.br +.Fa local_lock_method +: The method that should be called to acquire the local lock +.br +.Fa local_unlock_method +: The method that should be called to relinquish the local lock +.Pp +Instances of the defined cohort type can be declared as: +.br + CK_COHORT_INSTANCE(cohort_name) cohort; +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_COHORT_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_TRYLOCK b/doc/CK_COHORT_TRYLOCK new file mode 100644 index 0000000..22bb4b5 --- /dev/null +++ b/doc/CK_COHORT_TRYLOCK @@ -0,0 +1,69 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 9, 2013. +.Dt CK_COHORT_TRYLOCK 3 +.Sh NAME +.Nm CK_COHORT_TRYLOCK +.Nd try to acquire cohort lock +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_COHORT_TRYLOCK "COHORT_NAME cohort_name" "COHORT *cohort" "void *global_trylock_context" \ +"void *local_trylock_context" "void *lock_unlock_context" +.Sh DESCRIPTION +This call attempts to acquire both the local and global (if necessary) locks from +.Fa cohort . +It can only be used with cohort types that were defined using the +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 +macro. The call will not block and will return a bool that will evaluate to true iff +the cohort was successfully acquired. +.Fa global_trylock_context +will be passed as the second argument to the function that was provided as the +.Fa global_trylock_method +argument to CK_COHORT_TRYLOCK_PROTOTYPE if that method is called, and +.Fa local_trylock_context +will be passed to the function specified by +.Fa local_trylock_method . +If the global lock acquisition fails, then the cohort will immediately release its +local lock as well, and +.Fa local_unlock_context +will be passed to the function specified by +.Fa local_unlock_method +when this call is made. +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_COHORT_PROTOTYPE 3 , +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_COHORT_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_TRYLOCK_PROTOTYPE b/doc/CK_COHORT_TRYLOCK_PROTOTYPE new file mode 100644 index 0000000..dd97ad4 --- /dev/null +++ b/doc/CK_COHORT_TRYLOCK_PROTOTYPE @@ -0,0 +1,90 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 9, 2013. +.Dt CK_COHORT_TRYLOCK_PROTOTYPE 3 +.Sh NAME +.Nm CK_COHORT_TRYLOCK_PROTOTYPE +.Nd define cohort type with specified lock types +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_COHORT_TRYLOCK_PROTOTYPE "COHORT_NAME cohort_name" "LOCK_FXN global_lock_method" \ +"LOCK_FXN global_unlock_method" "BOOL_LOCK_FXN global_locked_method" \ +"BOOL_LOCK_FXN global_trylock_method" "LOCK_FXN local_lock_method" \ +"LOCK_FXN local_unlock_method" "BOOL_LOCK_FXN local_locked_method" "BOOL_LOCK_FXN local_trylock_method" +.Sh DESCRIPTION +The ck_cohort.h header file does not define any cohort types. Instead, the user must use +the CK_COHORT_PROTOTYPE or CK_COHORT_TRYLOCK_PROTOTYPE macros to define any types +they want to use. They must use CK_COHORT_TRYLOCK_PROTOTYPE if they want their cohort type to have support +for trylock operations. The CK_COHORT_TRYLOCK_PROTOTYPE macro takes the following arguments: +.Pp +.Fa cohort_name +: An identifier used for this cohort type. This will have to be passed to each +of the other CK_COHORT macros. +.br +.Fa global_lock_method +: The method that should be called to acquire the global lock +.br +.Fa global_unlock_method +: The method that should be called to relinquish the global lock +.br +.Fa global_locked_method +: This method should return true iff the global lock is acquired by a thread. +.br +.Fa global_trylock_method +: The method that should be called to try to acquire the global lock. +It should not block and return true iff the lock was successfully acquired. +.br +.Fa local_lock_method +: The method that should be called to acquire the local lock +.br +.Fa local_unlock_method +: The method that should be called to relinquish the local lock +.br +.Fa global_locked_method +: This method should return true iff the global lock is acquired by a thread. +.br +.Fa local_trylock_method +: The method that should be called to try to acquire the local lock. +It should not block and return true iff the lock was successfully acquired. +.Pp +Instances of the defined cohort type can be declared as: +.br + CK_COHORT_INSTANCE(cohort_name) cohort; +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_COHORT_PROTOTYPE 3 , +.Xr CK_COHORT_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_UNLOCK b/doc/CK_COHORT_UNLOCK new file mode 100644 index 0000000..a9f302f --- /dev/null +++ b/doc/CK_COHORT_UNLOCK @@ -0,0 +1,61 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_COHORT_UNLOCK 3 +.Sh NAME +.Nm CK_COHORT_UNLOCK +.Nd release cohort lock +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_COHORT_UNLOCK "COHORT_NAME cohort_name" "COHORT *cohort" "void *global_context" \ +"void *local_context" +.Sh DESCRIPTION +This call instructs +.Fa cohort +to relinquish its local lock and potentially its global lock as well. +.Fa global_context +will be passed as the second argument to the function that was provided as the +.Fa global_lock_method +argument to CK_COHORT_PROTOTYPE if that method is called, and +.Fa local_context +will be passed to the function specified by +.Fa local_lock_method +. +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_COHORT_PROTOTYPE 3 , +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_COHORT_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_HS_HASH b/doc/CK_HS_HASH new file mode 100644 index 0000000..6d8dc75 --- /dev/null +++ b/doc/CK_HS_HASH @@ -0,0 +1,71 @@ +.\" +.\" 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 March 28, 2012 +.Dt CK_HS_HASH 3 +.Sh NAME +.Nm CK_HS_HASH +.Nd invoke hash function with hash set seed +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft unsigned long +.Fn CK_HS_HASH "ck_hs_t *hs" "ck_hs_hash_cb_t *hf" "const void *key" +.Sh DESCRIPTION +The +.Fn CK_HS_HASH 3 +macro will invoke the hash function pointed to by the +.Fa hf +argument with the seed value associated with +.Fa hs +and the key pointer specified by the +.Fa key +argument. +.Sh RETURN VALUES +This function will return the value returned by the +.Fa hf +function. +.Sh ERRORS +It is expected +.Fa hs +was previously initialized via +.Fn ck_hs_init 3 . +.Sh SEE ALSO +.Xr ck_hs_init 3 , +.Xr ck_hs_destroy 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_RHS_HASH b/doc/CK_RHS_HASH new file mode 100644 index 0000000..43b8859 --- /dev/null +++ b/doc/CK_RHS_HASH @@ -0,0 +1,71 @@ +.\" +.\" 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 March 28, 2012 +.Dt CK_RHS_HASH 3 +.Sh NAME +.Nm CK_RHS_HASH +.Nd invoke hash function with hash set seed +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft unsigned long +.Fn CK_RHS_HASH "ck_rhs_t *hs" "ck_rhs_hash_cb_t *hf" "const void *key" +.Sh DESCRIPTION +The +.Fn CK_RHS_HASH 3 +macro will invoke the hash function pointed to by the +.Fa hf +argument with the seed value associated with +.Fa hs +and the key pointer specified by the +.Fa key +argument. +.Sh RETURN VALUES +This function will return the value returned by the +.Fa hf +function. +.Sh ERRORS +It is expected +.Fa hs +was previously initialized via +.Fn ck_rhs_init 3 . +.Sh SEE ALSO +.Xr ck_rhs_init 3 , +.Xr ck_rhs_destroy 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_remove 3 , +.Xr ck_rhs_grow 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_RWCOHORT_INIT b/doc/CK_RWCOHORT_INIT new file mode 100644 index 0000000..18d1b33 --- /dev/null +++ b/doc/CK_RWCOHORT_INIT @@ -0,0 +1,61 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_RWCOHORT_INIT 3 +.Sh NAME +.Nm CK_RWCOHORT_INIT +.Nd initialize instance of a cohort-based reader-writer lock type +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rwcohort.h +.Fn CK_RWCOHORT_NEUTRAL_INIT "COHORT_NAME cohort_name" "LOCK *lock" +.Fn CK_RWCOHORT_RP_INIT "COHORT_NAME cohort_name" "LOCK *lock" "unsigned int wait_limit" +.Fn CK_RWCOHORT_WP_INIT "COHORT_NAME cohort_name" "LOCK *lock" "unsigned int wait_limit" +.Sh DESCRIPTION +This macro initializes the lock instance pointed to by the +.Fa lock +argument. Until a lock instance is initialized using the CK_RWCOHORT_INIT macro, any operations +involving it will have undefined behavior. Note that the +.Fa wait_limit +argument should only be used with reader-preference or writer-preference locks. For neutral +locks, this argument should be excluded. +If you are unsure of a value to use for the +.Fa wait_limit +argument, you should use CK_RWCOHORT_STRATEGY_DEFAULT_LOCAL_WAIT_LIMIT. +.Sh SEE ALSO +.Xr ck_rwcohort 3 , +.Xr CK_RWCOHORT_PROTOTYPE 3 , +.Xr CK_RWCOHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_RWCOHORT_INSTANCE 3 , +.Xr CK_RWCOHORT_INITIALIZER 3 , +.Xr CK_RWCOHORT_LOCK 3 , +.Xr CK_RWCOHORT_UNLOCK 3 , +.Xr CK_RWCOHORT_LOCKED 3 , +.Xr CK_RWCOHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_RWCOHORT_INSTANCE b/doc/CK_RWCOHORT_INSTANCE new file mode 100644 index 0000000..10251a3 --- /dev/null +++ b/doc/CK_RWCOHORT_INSTANCE @@ -0,0 +1,64 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_RWCOHORT_INSTANCE 3 +.Sh NAME +.Nm CK_RWCOHORT_INSTANCE +.Nd declare an instance of a cohort-based reader-writer lock type +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_RWCOHORT_NEUTRAL_INSTANCE "COHORT_NAME cohort_name" +.Fn CK_RWCOHORT_RP_INSTANCE "COHORT_NAME cohort_name" +.Fn CK_RWCOHORT_WP_INSTANCE "COHORT_NAME cohort_name" +.Sh DESCRIPTION +The user must use this macro to declare instances of lock types that they have +defined using the +.Xr CK_RWCOHORT_PROTOTYPE 3 +macro. The cohort_name must be the same as the one used in the prototype macro. +For instance, if CK_RWCOHORT_PROTOTYPE was called with the name "foo", the +CK_RWCOHORT_INSTANCE macro should be called as +.br +CK_RWCOHORT_INSTANCE(foo) cohort; +.Pp +This macro should also be used when allocating memory for cohorts. For instance, +to allocate a block of 4 cohorts: +.br +CK_RWCOHORT_WP_INSTANCE(foo) *cohorts = malloc(4 * sizeof(CK_RWCOHORT_WP_INSTANCE(foo))); +.Sh SEE ALSO +.Xr ck_rwcohort 3 , +.Xr CK_RWCOHORT_PROTOTYPE 3 , +.Xr CK_RWCOHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_RWCOHORT_INSTANCE 3 , +.Xr CK_RWCOHORT_INITIALIZER 3 , +.Xr CK_RWCOHORT_LOCK 3 , +.Xr CK_RWCOHORT_UNLOCK 3 , +.Xr CK_RWCOHORT_LOCKED 3 , +.Xr CK_RWCOHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_RWCOHORT_PROTOTYPE b/doc/CK_RWCOHORT_PROTOTYPE new file mode 100644 index 0000000..a2705b6 --- /dev/null +++ b/doc/CK_RWCOHORT_PROTOTYPE @@ -0,0 +1,65 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_RWCOHORT_PROTOTYPE 3 +.Sh NAME +.Nm CK_RWCOHORT_PROTOTYPE +.Nd define reader-writer cohort-based lock using the specified cohort type +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rwcohort.h +.Fn CK_RWCOHORT_NEUTRAL_PROTOTYPE "COHORT_NAME cohort_name" +.Fn CK_RWCOHORT_RP_PROTOTYPE "COHORT_NAME cohort_name" +.Fn CK_RWCOHORT_WP_PROTOTYPE "COHORT_NAME cohort_name" +.Sh DESCRIPTION +The ck_rwcohort.h header file does not define any cohort types. Instead, the user must use +the CK_RWCOHORT_PROTOTYPE macro to define any types they want to use. +This macro takes a single argument which corresponds to the type of the cohort lock that +the reader-writer lock should use. A cohort type must have already been defined with that name +using the +.Xr CK_COHORT_PROTOTYPE 3 +or +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 +macros. +.Pp +Instances of the defined lock type can be declared as: +.br + CK_RWCOHORT_INSTANCE(cohort_name) lock; +.Sh SEE ALSO +.Xr ck_rwcohort 3 , +.Xr CK_COHORT_PROTOTYPE 3 , +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_RWCOHORT_INSTANCE 3 , +.Xr CK_RWCOHORT_INITIALIZER 3 , +.Xr CK_RWCOHORT_INIT 3 , +.Xr CK_RWCOHORT_READ_LOCK 3 , +.Xr CK_RWCOHORT_READ_UNLOCK 3 , +.Xr CK_RWCOHORT_WRITE_LOCK 3 , +.Xr CK_RWCOHORT_WRITE_UNLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_RWCOHORT_READ_LOCK b/doc/CK_RWCOHORT_READ_LOCK new file mode 100644 index 0000000..62831ea --- /dev/null +++ b/doc/CK_RWCOHORT_READ_LOCK @@ -0,0 +1,66 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_RWCOHORT_READ_LOCK 3 +.Sh NAME +.Nm CK_RWCOHORT_READ_LOCK +.Nd acquire read-only permission for cohort-based reader-writer lock +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_RWCOHORT_NEUTRAL_READ_LOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_RP_READ_LOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_WP_READ_LOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Sh DESCRIPTION +This call will acquire read-only permission from +.Fa lock . +The call will block until this permission has been acquired. +.Fa cohort +must point to a cohort whose global lock is the same as all other cohorts used with +.Fa lock . +The +.Fa global_context +and +.Fa local_context +arguments will be passed along as the context arguments to any calls to +.Fa cohort . +. +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_RWCOHORT_PROTOTYPE 3 , +.Xr CK_RWCOHORT_INSTANCE 3 , +.Xr CK_RWCOHORT_INITIALIZER 3 , +.Xr CK_RWCOHORT_INIT 3 , +.Xr CK_RWCOHORT_READ_UNLOCK 3 , +.Xr CK_RWCOHORT_WRITE_LOCK 3 , +.Xr CK_RWCOHORT_WRITE_UNLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_RWCOHORT_READ_UNLOCK b/doc/CK_RWCOHORT_READ_UNLOCK new file mode 100644 index 0000000..1c81801 --- /dev/null +++ b/doc/CK_RWCOHORT_READ_UNLOCK @@ -0,0 +1,65 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_RWCOHORT_READ_UNLOCK 3 +.Sh NAME +.Nm CK_RWCOHORT_READ_UNLOCK +.Nd relinquish read-only access to cohort-based reader-writer lock +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_RWCOHORT_NEUTRAL_READ_UNLOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_RP_READ_UNLOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_WP_READ_UNLOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Sh DESCRIPTION +This call will relinquish read-only permission to +.Fa lock . +.Fa cohort +must point to a cohort whose global lock is the same as all other cohorts used with +.Fa lock . +The +.Fa global_context +and +.Fa local_context +arguments will be passed along as the context arguments to any calls to +.Fa cohort . +. +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_RWCOHORT_PROTOTYPE 3 , +.Xr CK_RWCOHORT_INSTANCE 3 , +.Xr CK_RWCOHORT_INITIALIZER 3 , +.Xr CK_RWCOHORT_INIT 3 , +.Xr CK_RWCOHORT_READ_LOCK 3 , +.Xr CK_RWCOHORT_WRITE_LOCK 3 , +.Xr CK_RWCOHORT_WRITE_UNLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_RWCOHORT_WRITE_LOCK b/doc/CK_RWCOHORT_WRITE_LOCK new file mode 100644 index 0000000..161c7bb --- /dev/null +++ b/doc/CK_RWCOHORT_WRITE_LOCK @@ -0,0 +1,66 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_RWCOHORT_WRITE_LOCK 3 +.Sh NAME +.Nm CK_RWCOHORT_WRITE_LOCK +.Nd acquite write access for a cohort-based reader-writer lock +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_RWCOHORT_NEUTRAL_WRITE_LOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_RP_WRITE_LOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_WP_WRITE_LOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Sh DESCRIPTION +This call will acquire write permission for +.Fa lock . +The call will block until this permission has been acquired. +.Fa cohort +must point to a cohort whose global lock is the same as all other cohorts used with +.Fa lock . +The +.Fa global_context +and +.Fa local_context +arguments will be passed along as the context arguments to any calls to +.Fa cohort . +. +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_RWCOHORT_PROTOTYPE 3 , +.Xr CK_RWCOHORT_INSTANCE 3 , +.Xr CK_RWCOHORT_INITIALIZER 3 , +.Xr CK_RWCOHORT_INIT 3 , +.Xr CK_RWCOHORT_READ_LOCK 3 , +.Xr CK_RWCOHORT_READ_UNLOCK 3 , +.Xr CK_RWCOHORT_WRITE_UNLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_RWCOHORT_WRITE_UNLOCK b/doc/CK_RWCOHORT_WRITE_UNLOCK new file mode 100644 index 0000000..5772a9f --- /dev/null +++ b/doc/CK_RWCOHORT_WRITE_UNLOCK @@ -0,0 +1,65 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt CK_RWCOHORT_WRITE_UNLOCK 3 +.Sh NAME +.Nm CK_RWCOHORT_WRITE_UNLOCK +.Nd relinquish write access for cohort-based reader-writer lock +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_RWCOHORT_NEUTRAL_WRITE_UNLOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_RP_WRITE_UNLOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_WP_WRITE_UNLOCK "COHORT_NAME cohort_name" "LOCK *lock" "COHORT *cohort"\ +"void *global_context" "void *local_context" +.Sh DESCRIPTION +This call will relinquish write permission for +.Fa lock . +.Fa cohort +must point to a cohort whose global lock is the same as all other cohorts used with +.Fa lock . +The +.Fa global_context +and +.Fa local_context +arguments will be passed along as the context arguments to any calls to +.Fa cohort . +. +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr CK_RWCOHORT_PROTOTYPE 3 , +.Xr CK_RWCOHORT_INSTANCE 3 , +.Xr CK_RWCOHORT_INITIALIZER 3 , +.Xr CK_RWCOHORT_INIT 3 , +.Xr CK_RWCOHORT_READ_LOCK 3 , +.Xr CK_RWCOHORT_READ_UNLOCK 3 , +.Xr CK_RWCOHORT_WRITE_LOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..cbad704 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,218 @@ +.PHONY: clean install uninstall + +MANDIR=@MANDIR@ +GZIP=@GZIP@ +GZIP_SUFFIX=.3@GZIP_SUFFIX@ +BUILD_DIR=@BUILD_DIR@ +SRC_DIR=@SRC_DIR@ +HTML_SUFFIX=.html + +OBJECTS=CK_ARRAY_FOREACH \ + ck_array_buffer \ + ck_array_commit \ + ck_array_deinit \ + ck_array_init \ + ck_array_initialized \ + ck_array_length \ + ck_array_put \ + ck_array_put_unique \ + ck_array_remove \ + ck_array_deinit \ + ck_brlock \ + ck_ht_count \ + ck_ht_destroy \ + ck_ht_gc \ + ck_ht_get_spmc \ + ck_ht_grow_spmc \ + ck_ht_hash \ + ck_ht_hash_direct \ + ck_ht_init \ + ck_ht_put_spmc \ + ck_ht_remove_spmc \ + ck_ht_reset_spmc \ + ck_ht_reset_size_spmc \ + ck_ht_set_spmc \ + ck_ht_entry_empty \ + ck_ht_entry_key \ + ck_ht_entry_key_direct \ + ck_ht_entry_key_length \ + ck_ht_entry_key_set \ + ck_ht_entry_key_set_direct \ + ck_ht_entry_set \ + ck_ht_entry_set_direct \ + ck_ht_entry_value_direct \ + ck_ht_entry_value \ + ck_ht_iterator_init \ + ck_ht_next \ + ck_ht_stat \ + ck_bitmap_init \ + ck_bitmap_reset \ + ck_bitmap_set \ + ck_bitmap_bts \ + ck_bitmap_test \ + ck_bitmap_base \ + ck_bitmap_union \ + ck_bitmap_size \ + ck_bitmap_clear \ + ck_bitmap_bits \ + ck_bitmap_buffer \ + ck_bitmap_next \ + ck_bitmap_iterator_init \ + ck_elide \ + ck_epoch_barrier \ + ck_epoch_begin \ + ck_epoch_call \ + ck_epoch_end \ + ck_epoch_init \ + ck_epoch_poll \ + ck_epoch_recycle \ + ck_epoch_register \ + ck_epoch_reclaim \ + ck_epoch_synchronize \ + ck_epoch_unregister \ + ck_hs_gc \ + ck_hs_init \ + ck_hs_destroy \ + CK_HS_HASH \ + ck_hs_apply \ + ck_hs_iterator_init \ + ck_hs_next \ + ck_hs_get \ + ck_hs_put \ + ck_hs_put_unique \ + ck_hs_set \ + ck_hs_fas \ + ck_hs_remove \ + ck_hs_move \ + ck_hs_grow \ + ck_hs_rebuild \ + ck_hs_count \ + 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_put_unique \ + 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 \ + CK_RWCOHORT_PROTOTYPE \ + CK_RWCOHORT_READ_LOCK \ + CK_RWCOHORT_READ_UNLOCK \ + CK_RWCOHORT_WRITE_LOCK \ + CK_RWCOHORT_WRITE_UNLOCK \ + ck_cohort \ + CK_COHORT_PROTOTYPE \ + CK_COHORT_TRYLOCK_PROTOTYPE \ + CK_COHORT_INSTANCE \ + CK_COHORT_INIT \ + CK_COHORT_LOCK \ + CK_COHORT_UNLOCK \ + CK_COHORT_TRYLOCK \ + ck_pr \ + ck_pr_fence_acquire \ + ck_pr_fence_release \ + ck_pr_barrier \ + ck_pr_fas \ + ck_pr_fence_atomic \ + ck_pr_fence_atomic_load \ + ck_pr_fence_atomic_store \ + ck_pr_fence_load \ + ck_pr_fence_load_atomic \ + ck_pr_fence_load_store \ + ck_pr_fence_load_depends \ + ck_pr_fence_memory \ + ck_pr_fence_store \ + ck_pr_fence_store_atomic \ + ck_pr_fence_store_load \ + ck_pr_stall \ + ck_pr_faa \ + ck_pr_inc \ + ck_pr_dec \ + ck_pr_not \ + ck_pr_neg \ + ck_pr_add \ + ck_pr_sub \ + ck_pr_and \ + ck_pr_xor \ + ck_pr_or \ + ck_pr_cas \ + ck_pr_bts \ + ck_pr_btc \ + ck_pr_btr \ + ck_pr_store \ + ck_pr_load \ + ck_pr_rtm \ + ck_queue \ + ck_ring_init \ + ck_ring_dequeue_spmc \ + ck_ring_enqueue_spmc \ + ck_ring_enqueue_spmc_size \ + ck_ring_trydequeue_spmc \ + ck_ring_dequeue_spsc \ + ck_ring_enqueue_spsc \ + ck_ring_enqueue_spsc_size \ + ck_ring_size \ + ck_ring_capacity \ + ck_tflock \ + ck_rwlock \ + ck_pflock \ + ck_swlock \ + ck_sequence \ + ck_spinlock + +all: + for target in $(OBJECTS); do \ + $(GZIP) $(SRC_DIR)/doc/$$target > $(BUILD_DIR)/doc/$$target$(GZIP_SUFFIX); \ + done + +html: + for target in $(OBJECTS); do \ + echo $$target; \ + groff -man -Tascii $(SRC_DIR)/doc/$$target | col -bx > \ + $(BUILD_DIR)/doc/$$target$(HTML_SUFFIX); \ + sed -i.bk 's/\&/\&\;/g;s/>/\>\;/g;s/</\<\;/g;' \ + $(BUILD_DIR)/doc/$$target$(HTML_SUFFIX); \ + done + +# check for entries that are missing in OBJECTS +objcheck: all + for file in `ls * | egrep '(ck|CK)_' | egrep -v "($(GZIP_SUFFIX)|$(HTML_SUFFIX))$$"`; do \ + if [ ! -f $${file}$(GZIP_SUFFIX) ]; then \ + echo "$$file is missing from OBJECTS" >&2; \ + fi; \ + done + +# check for stale references +refcheck: + @./refcheck.pl $(OBJECTS) + +install: + mkdir -p $(DESTDIR)/$(MANDIR)/man3 || exit + cp *$(GZIP_SUFFIX) $(DESTDIR)/$(MANDIR)/man3 || exit + +uninstall: + for target in $(OBJECTS); do \ + rm -f $(DESTDIR)/$(MANDIR)/man3/$$target$(GZIP_SUFFIX); \ + done + +clean: + rm -f $(BUILD_DIR)/doc/*~ $(BUILD_DIR)/doc/*$(GZIP_SUFFIX) $(BUILD_DIR)/doc/*$(HTML_SUFFIX) + diff --git a/doc/ck_array_buffer b/doc/ck_array_buffer new file mode 100644 index 0000000..7a8ded3 --- /dev/null +++ b/doc/ck_array_buffer @@ -0,0 +1,60 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_BUFFER 3 +.Sh NAME +.Nm ck_array_buffer +.Nd return length and pointer to array of reader-visible pointers +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft void * +.Fn ck_array_buffer "ck_array_t *array" "unsigned int *length" +.Sh DESCRIPTION +The +.Fn ck_array_buffer 3 +returns a pointer to the array of pointers currently visible +to readers after the last commit operation in +.Fa array . +The unsigned integer pointed to by +.Fa length +is updated to reflect the length of the array. +.Sh RETURN VALUES +This function returns a pointer to an array of pointers. +.Sh SEE ALSO +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_init 3 +.Xr ck_array_deinit 3 , +.Xr ck_array_length 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_commit b/doc/ck_array_commit new file mode 100644 index 0000000..0fc1192 --- /dev/null +++ b/doc/ck_array_commit @@ -0,0 +1,58 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_COMMIT 3 +.Sh NAME +.Nm ck_array_commit +.Nd linearization point for mutations before commit call +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft bool +.Fn ck_array_commit "ck_array_t *array" +.Sh DESCRIPTION +The +.Fn ck_array_commit 3 +function will commit any pending put or remove operations associated +with the array. The function may end up requesting the safe reclamation +of memory actively being iterated upon by other threads. +.Sh RETURN VALUES +This function returns true if the commit operation succeeded. It will +return false otherwise, and pending operations will not be applied. +.Sh SEE ALSO +.Xr ck_array_init 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_deinit 3 +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_deinit b/doc/ck_array_deinit new file mode 100644 index 0000000..3a5e5ab --- /dev/null +++ b/doc/ck_array_deinit @@ -0,0 +1,62 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_DEINIT 3 +.Sh NAME +.Nm ck_array_deinit +.Nd destroy and deinitialize a pointer array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft void +.Fn ck_array_deinit "ck_array_t *array" "bool defer" +.Sh DESCRIPTION +The +.Fn ck_array_deinit 3 +destroys the memory associated with the array pointed +to by +.Fa array . +The +.Fa defer +argument is true if the allocator must destroy +the memory using safe memory reclamation or false +if the allocator can destroy this memory immediately. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_init 3 +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_init b/doc/ck_array_init new file mode 100644 index 0000000..ad8a9fe --- /dev/null +++ b/doc/ck_array_init @@ -0,0 +1,69 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_INIT 3 +.Sh NAME +.Nm ck_array_init +.Nd initialize a pointer array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft bool +.Fn ck_array_init "ck_array_t *array" "unsigned int mode" "struct ck_malloc *allocator" "unsigned int initial_length" +.Sh DESCRIPTION +The +.Fn ck_array_init 3 +function initializes the array pointed to by the argument +.Fa array . +The mode value must be +.Dv CK_ARRAY_MODE_SPMC . +The +.Fa allocator +argument must point to a ck_malloc data structure with valid non-NULL function pointers +initialized for malloc, free and realloc. The +.Fa initial_length +specifies the initial length of the array. The value of +.Fa initial_length +must be greater than or equal to 2. An array allows for one concurrent put or remove operations +in the presence of any number of concurrent CK_ARRAY_FOREACH operations. +.Sh RETURN VALUES +This function returns true if the array was successfully created. It returns +false if the creation failed. Failure may occur due to internal memory allocation +failures or invalid arguments. +.Sh SEE ALSO +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_deinit 3 +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_initialized b/doc/ck_array_initialized new file mode 100644 index 0000000..3a06413 --- /dev/null +++ b/doc/ck_array_initialized @@ -0,0 +1,62 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_INITIALIZED 3 +.Sh NAME +.Nm ck_array_initialized +.Nd indicates whether an array was recently initialized or deinitialized +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft bool +.Fn ck_array_initialized "ck_array_t *array" +.Sh DESCRIPTION +The +.Fn ck_array_initialized 3 +can be used to determine whether an array was recently initialized +with +.Fn ck_array_init 3 +or deinitialized with +.Fn ck_array_deinit 3 . +Behavior is undefined if a user allocates internal allocator data +in through other means. +.Sh RETURN VALUES +This function returns true if the array is initialized, and false +otherwise. +.Sh SEE ALSO +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_init 3 +.Xr ck_array_deinit 3 , +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_length b/doc/ck_array_length new file mode 100644 index 0000000..e60c6c3 --- /dev/null +++ b/doc/ck_array_length @@ -0,0 +1,57 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_LENGTH 3 +.Sh NAME +.Nm ck_array_length +.Nd returns the number of pointers committed to an array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft unsigned int +.Fn ck_array_length "ck_array_t *array" +.Sh DESCRIPTION +The +.Fn ck_array_length 3 +function returns the number of items a concurrent +traversal operation would encounter at completion +time. +.Sh RETURN VALUES +The number of traversal-visible pointers is returned. +.Sh SEE ALSO +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_init 3 +.Xr ck_array_deinit 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_put b/doc/ck_array_put new file mode 100644 index 0000000..0f74eb0 --- /dev/null +++ b/doc/ck_array_put @@ -0,0 +1,65 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_PUT 3 +.Sh NAME +.Nm ck_array_put +.Nd attempt immediate or deferred insertion of a pointer into array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft bool +.Fn ck_array_put "ck_array_t *array" "void *pointer" +.Sh DESCRIPTION +The +.Fn ck_array_put 3 +function will attempt to insert the value of +.Fa pointer +into the array pointed to by +.Fa array . +This function may incur additional memory allocations +if not enough memory has been allocated in the array +for a new entry. The operation is also free to apply +the operation immediately if there is an opportunity +for elimination with a pending (uncommitted) remove +operation. +.Sh RETURN VALUES +This function returns true if the put operation succeeded. It will +return false otherwise due to internal allocation failures. +.Sh SEE ALSO +.Xr ck_array_init 3 , +.Xr ck_array_commit 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_deinit 3 +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_put_unique b/doc/ck_array_put_unique new file mode 100644 index 0000000..bb355fe --- /dev/null +++ b/doc/ck_array_put_unique @@ -0,0 +1,67 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_PUT_UNIQUE 3 +.Sh NAME +.Nm ck_array_put_unique +.Nd attempt immediate or deferred insertion of a unique pointer into array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft int +.Fn ck_array_put_unique "ck_array_t *array" "void *pointer" +.Sh DESCRIPTION +The +.Fn ck_array_put_unique 3 +function will attempt to insert the value of +.Fa pointer +into the array pointed to by +.Fa array . +This function may incur additional memory allocations +if not enough memory has been allocated in the array +for a new entry. The operation is also free to apply +the operation immediately if there is an opportunity +for elimination with a pending (uncommitted) remove +operation. The function will not make any modifications +if the pointer already exists in the array. +.Sh RETURN VALUES +This function returns 1 if the pointer already exists in the array. +It returns 0 if the put operation succeeded. It returns -1 on +error due to internal memory allocation failures. +.Sh SEE ALSO +.Xr ck_array_init 3 , +.Xr ck_array_commit 3 , +.Xr ck_array_put 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_deinit 3 +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_array_remove b/doc/ck_array_remove new file mode 100644 index 0000000..8df454d --- /dev/null +++ b/doc/ck_array_remove @@ -0,0 +1,64 @@ +.\" +.\" 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 October 18, 2013 +.Dt CK_ARRAY_REMOVE 3 +.Sh NAME +.Nm ck_array_remove +.Nd attempt immediate or deferred removal of a pointer from an array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_array.h +.Ft bool +.Fn ck_array_remove "ck_array_t *array" "void *pointer" +.Sh DESCRIPTION +The +.Fn ck_array_remove 3 +function will attempt to remove the value of +.Fa pointer +into the array pointed to by +.Fa array . The operation is also free to apply +the operation immediately if there is an opportunity +for elimination with a pending (uncommitted) put +operation. If no elimination was possible, the function +may require to allocate more memory. +.Sh RETURN VALUES +This function returns true if the remove operation succeeded. It will +return false otherwise due to internal allocation failures or because +the value did not exist. +.Sh SEE ALSO +.Xr ck_array_init 3 , +.Xr ck_array_commit 3 , +.Xr ck_array_remove 3 , +.Xr ck_array_put_unique 3 , +.Xr ck_array_deinit 3 +.Xr ck_array_length 3 , +.Xr ck_array_buffer 3 , +.Xr ck_array_initialized 3 , +.Xr CK_ARRAY_FOREACH 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_base b/doc/ck_bitmap_base new file mode 100644 index 0000000..e9342bf --- /dev/null +++ b/doc/ck_bitmap_base @@ -0,0 +1,58 @@ +.\" +.\" 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 April 22, 2012 +.Dt CK_BITMAP_BASE 3 +.Sh NAME +.Nm ck_bitmap_base +.Nd determine the size of a bit array in bytes +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft unsigned int +.Fn ck_bitmap_base "unsigned int n_bits" +.Sh DESCRIPTION +The +.Fn ck_bitmap_base +function returns the number of bytes that would be used +to store the number of bits specified by +.Fa n_bits . +.Sh RETURN VALUES +This function returns a non-zero value that is guaranteed to +be a multiple of +.Dv sizeof(CK_BITMAP_WORD) . +.Sh SEE ALSO +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_bits b/doc/ck_bitmap_bits new file mode 100644 index 0000000..efd5eb2 --- /dev/null +++ b/doc/ck_bitmap_bits @@ -0,0 +1,56 @@ +.\" +.\" 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 April 22, 2012 +.Dt CK_BITMAP_BITS 3 +.Sh NAME +.Nm ck_bitmap_bits +.Nd return number of addressable bits in bitmap +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft unsigned int +.Fn ck_bitmap_bits "ck_bitmap_t *bitmap" +.Sh DESCRIPTION +The +.Fn ck_bitmap_bits +function returns the maximum number of addressable bits in +the object pointed to by +.Fa bitmap . +.Sh RETURN VALUES +This function returns a non-zero value. +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_bts b/doc/ck_bitmap_bts new file mode 100644 index 0000000..872284c --- /dev/null +++ b/doc/ck_bitmap_bts @@ -0,0 +1,61 @@ +.\" +.\" Copyright 2014 David Joseph. +.\" 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 August 22, 2014 +.Dt CK_BITMAP_BTS 3 +.Sh NAME +.Nm ck_bitmap_bts +.Nd set the bit at the specified index and fetch its original value +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft bool +.Fn ck_bitmap_bts "ck_bitmap_t *bitmap" "unsigned int n" +.Sh DESCRIPTION +.Fn ck_bitmap_bts +sets the bit at the offset specified by the argument +.Fa n +to +.Dv 1 +and fetches its original value. +.Sh RETURN VALUES +This function returns the original value of the bit at offset +.Fa n +in +.Fa bitmap . +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_buffer b/doc/ck_bitmap_buffer new file mode 100644 index 0000000..206df03 --- /dev/null +++ b/doc/ck_bitmap_buffer @@ -0,0 +1,65 @@ +.\" +.\" 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 April 22, 2012 +.Dt CK_BITMAP_BUFFER 3 +.Sh NAME +.Nm ck_bitmap_buffer +.Nd returns pointer to bit array +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft void * +.Fn ck_bitmap_buffer "ck_bitmap_t *bitmap" +.Sh DESCRIPTION +The +.Fn ck_bitmap_buffer +functions returns a pointer to the actual bit array. +For ck_bitmap pointers, the bit array is of type +CK_BITMAP_WORD[] and consists of +ck_bitmap_base(bitmap) / sizeof(CK_BITMAP_WORD) elements. +On currently supported 64-bit platforms +.Dv CK_BITMAP_WORD +is +.Dv uint64_t . +On currently supported 32-bit platforms +.Dv CK_BITMAP_WORD +is +.Dv uint32_t . +.Sh RETURN VALUES +This function returns a non-NULL value. +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_bits 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_clear b/doc/ck_bitmap_clear new file mode 100644 index 0000000..f94dca2 --- /dev/null +++ b/doc/ck_bitmap_clear @@ -0,0 +1,56 @@ +.\" +.\" 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 April 22, 2012 +.Dt CK_BITMAP_CLEAR 3 +.Sh NAME +.Nm ck_bitmap_clear +.Nd reset all bits +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft void +.Fn ck_bitmap_clear "ck_bitmap_t *bitmap" +.Sh DESCRIPTION +The +.Fn ck_bitmap_clear +function sets all bits in the bitmap pointed to by +.Fa bitmap +to 0. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_init b/doc/ck_bitmap_init new file mode 100644 index 0000000..a238374 --- /dev/null +++ b/doc/ck_bitmap_init @@ -0,0 +1,84 @@ +.\" +.\" 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 April 22, 2012 +.Dt CK_BITMAP_INIT 3 +.Sh NAME +.Nm ck_bitmap_init +.Nd initialize a bitmap +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft void +.Fn ck_bitmap_init "ck_bitmap_t *bitmap" "unsigned int n_bits" "bool set" +.Sh DESCRIPTION +The +.Fn ck_bitmap_init +function initializes the bitmap pointed to by the +.Fa bitmap +pointer. The argument +.Fa n_bits +specifies the number of bits that are to be stored in the bitmap. +The argument +.Fa set +determines whether the values of the bits in +.Fa bitmap +are to be initialized to +.Dv 1 +or +.Dv 0 . +.Pp +It is expected that +.Fa bitmap +points to a contiguous region of memory containing at least +the number of bytes specified by +.Xr ck_bitmap_size 3 . +.Sh RETURN VALUES +This function has no return value. +.Sh ERRORS +.Bl -tag -width Er +.Pp +The behavior of +.Fn ck_bitmap_init +is undefined if +.Fa bitmap +is not a pointer to a region of bytes +of at least +.Xr ck_bitmap_size 3 +length. +.El +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_iterator_init b/doc/ck_bitmap_iterator_init new file mode 100644 index 0000000..d67c659 --- /dev/null +++ b/doc/ck_bitmap_iterator_init @@ -0,0 +1,70 @@ +.\" +.\" Copyright 2012-2013 Samy Al Bahra. +.\" Copyright 2012-2013 Shreyas Prasad. +.\" 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 April 27, 2012 +.Dt CK_BITMAP_ITERATOR_INIT 3 +.Sh NAME +.Nm ck_bitmap_iterator_init +.Nd initialize bitmap iterator +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Pp +.Ft void +.Fn ck_bitmap_iterator_init "ck_bitmap_iterator_t *iterator" "ck_bitmap_t *bitmap" +.Sh DESCRIPTION +The +.Fn ck_bitmap_iterator_init +function will initialize the object pointed to by +the +.Fa iterator +argument for use with +.Fa bitmap . +.Pp +An iterator is used to iterate through set bitmap bits +with the +.Xr ck_bitmap_next 3 +function. +.Sh RETURN VALUES +The +.Fn ck_bitmap_iterator_init +function does not return a value. +.Sh ERRORS +This function will not fail. +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 , +.Xr ck_bitmap_next 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_next b/doc/ck_bitmap_next new file mode 100644 index 0000000..3e93c43 --- /dev/null +++ b/doc/ck_bitmap_next @@ -0,0 +1,90 @@ +.\" +.\" Copyright 2012-2013 Samy Al Bahra. +.\" Copyright 2012-2013 Shreyas Prasad. +.\" 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 April 27, 2012 +.Dt CK_BITMAP_TEST 3 +.Sh NAME +.Nm ck_bitmap_next +.Nd iterate to the next set bit in bitmap +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft bool +.Fn ck_bitmap_next "ck_bitmap_t *bitmap" "ck_bitmap_iterator_t iterator" "unsigned int *bit" +.Sh DESCRIPTION +The +.Fn ck_bitmap_next +function will increment the iterator object pointed to by +.Fa iterator +to point to the next set bit in the bitmap. If +.Fn ck_bitmap_next +returns +.Dv true +then the pointer pointed to by +.Fa bit +is initialized to the number of the current set bit pointed to by the +.Fa iterator +object. +.Pp +It is expected that +.Fa iterator +has been initialized using the +.Xr ck_bitmap_iterator_init 3 +function. +.Sh RETURN VALUES +If +.Fn ck_bitmap_next +returns +.Dv true +then the object pointed to by +.Fa bit +contains a set bit. If +.Fn ck_bitmap_next +returns +.Dv false +then value of the object pointed to by +.Fa bit +is undefined. +.Sh ERRORS +Behavior is undefined if +.Fa iterator +or +.Fa bitmap +are uninitialized. +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 , +.Xr ck_bitmap_iterator_init 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_reset b/doc/ck_bitmap_reset new file mode 100644 index 0000000..c6b8ee5 --- /dev/null +++ b/doc/ck_bitmap_reset @@ -0,0 +1,57 @@ +.\" +.\" 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 April 22, 2012 +.Dt CK_BITMAP_RESET 3 +.Sh NAME +.Nm ck_bitmap_reset +.Nd resets the bit at the specified index +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft void +.Fn ck_bitmap_reset "ck_bitmap_t *bitmap" "unsigned int n" +.Sh DESCRIPTION +The +.Fn ck_bitmap_reset +resets the bit at offset specified by the argument +.Fa n +to +.Dv 0 . +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_set b/doc/ck_bitmap_set new file mode 100644 index 0000000..e92ba24 --- /dev/null +++ b/doc/ck_bitmap_set @@ -0,0 +1,57 @@ +.\" +.\" 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 April 22, 2012 +.Dt CK_BITMAP_SET 3 +.Sh NAME +.Nm ck_bitmap_set +.Nd set the bit at the specified index +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft void +.Fn ck_bitmap_set "ck_bitmap_t *bitmap" "unsigned int n" +.Sh DESCRIPTION +The +.Fn ck_bitmap_set +sets the bit at offset specified by the argument +.Fa n +to +.Dv 1 . +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_size b/doc/ck_bitmap_size new file mode 100644 index 0000000..03e5892 --- /dev/null +++ b/doc/ck_bitmap_size @@ -0,0 +1,62 @@ +.\" +.\" 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 April 22, 2012 +.Dt CK_BITMAP_SIZE 3 +.Sh NAME +.Nm ck_bitmap_size +.Nd returns necessary number of bytes for bitmap +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft unsigned int +.Fn ck_bitmap_size "unsigned int n_bits" +.Sh DESCRIPTION +The +.Fn ck_bitmap_size +function returns the number of bytes that are necessary +to allocate for a bitmap that will contain the number +of bits specified by +.Fa n_bits . +.Pp +This function is used to determine how many bytes to +allocate for dynamically created bitmap objects. The +allocated object must still be initialized using +.Xr ck_bitmap_init 3 . +.Sh RETURN VALUES +This function returns a non-zero value. +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_set_mpmc 3 , +.Xr ck_bitmap_reset_mpmc 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_test b/doc/ck_bitmap_test new file mode 100644 index 0000000..9eb8936 --- /dev/null +++ b/doc/ck_bitmap_test @@ -0,0 +1,62 @@ +.\" +.\" 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 April 22, 2012 +.Dt CK_BITMAP_TEST 3 +.Sh NAME +.Nm ck_bitmap_test +.Nd determine if the bit at the specified index is set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft bool +.Fn ck_bitmap_test "ck_bitmap_t *bitmap" "unsigned int n" +.Sh DESCRIPTION +The +.Fn ck_bitmap_test +determines if the bit at the offset specified by the argument +.Fa n +is set to +.Dv 1 . +.Sh RETURN VALUES +This function returns +.Dv true +if the bit at the specified offset is set to +.Dv 1 +and otherwise returns +.Dv false . +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_set_mpmc 3 , +.Xr ck_bitmap_reset_mpmc 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_bitmap_union b/doc/ck_bitmap_union new file mode 100644 index 0000000..b0ab8e8 --- /dev/null +++ b/doc/ck_bitmap_union @@ -0,0 +1,58 @@ +.\" +.\" Copyright 2012-2014 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 February 23, 2013 +.Dt CK_BITMAP_UNION 3 +.Sh NAME +.Nm ck_bitmap_union +.Nd generates union of two bitmaps +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_bitmap.h +.Ft void +.Fn ck_bitmap_union "ck_bitmap_t *dst" "ck_bitmap_t *src" +.Sh DESCRIPTION +The +.Fn ck_bitmap_union +function sets all bits in the bitmap pointed to by +.Fa src +in the bitmap pointed to by +.Fa dst . +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_bitmap_base 3 , +.Xr ck_bitmap_size 3 , +.Xr ck_bitmap_init 3 , +.Xr ck_bitmap_reset 3 , +.Xr ck_bitmap_set 3 , +.Xr ck_bitmap_clear 3 , +.Xr ck_bitmap_test 3 , +.Xr ck_bitmap_bits 3 , +.Xr ck_bitmap_buffer 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_brlock b/doc/ck_brlock new file mode 100644 index 0000000..7972ee4 --- /dev/null +++ b/doc/ck_brlock @@ -0,0 +1,121 @@ +.\" +.\" 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 26, 2013. +.Dt ck_brlock 3 +.Sh NAME +.Nm ck_brlock_init , +.Nm ck_brlock_write_lock , +.Nm ck_brlock_write_unlock , +.Nm ck_brlock_write_trylock , +.Nm ck_brlock_read_register , +.Nm ck_brlock_read_unregister , +.Nm ck_brlock_read_lock , +.Nm ck_brlock_read_trylock , +.Nm ck_brlock_read_unlock +.Nd big-reader locks +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_brlock.h +.Pp +.Dv ck_brlock_t brlock = CK_BRLOCK_INITIALIZER; +.Pp +.Dv ck_brlock_reader_t reader = CK_BRLOCK_READER_INITIALIZER; +.Pp +.Ft void +.Fn ck_brlock_init "ck_brlock_t *br" +.Ft void +.Fn ck_brlock_write_lock "ck_brlock_t *br" +.Ft void +.Fn ck_brlock_write_unlock "ck_brlock_t *br" +.Ft bool +.Fn ck_brlock_write_trylock "ck_brlock_t *br" "unsigned int factor" +.Ft void +.Fn ck_brlock_read_register "ck_brlock_t *br" "ck_brlock_reader_t *reader" +.Ft void +.Fn ck_brlock_read_unregister "ck_brlock_t *br" "ck_brlock_reader_t *reader" +.Ft void +.Fn ck_brlock_read_lock "ck_brlock_t *br" "ck_brlock_reader_t *reader" +.Ft bool +.Fn ck_brlock_read_trylock "ck_brlock_t *br" "ck_brlock_reader_t *reader" \ +"unsigned int factor" +.Ft void +.Fn ck_brlock_read_unlock "ck_brlock_reader_t *reader" +.Sh DESCRIPTION +Big reader locks are distributed reader-writer locks with low latency constant time +reader acquisition (with respect to number of concurrent readers). On the other +hand, writer acquisitions are a relatively expensive O(n) operation. This is a write-biased +lock. +.Sh EXAMPLE +.Bd -literal -offset indent +static ck_brlock_t lock = CK_BRLOCK_INITIALIZER; +static __thread ck_brlock_reader_t reader; + +static void +reader(void) +{ + + /* Add our thread as a lock participant. */ + ck_brlock_read_register(&lock, &reader); + + for (;;) { + ck_brlock_read_lock(&lock, &reader); + /* Read-side critical section. */ + ck_brlock_read_unlock(&reader); + + if (ck_brlock_read_trylock(&lock, &reader, 1) == true) { + /* Read-side critical section. */ + ck_brlock_read_unlock(&reader); + } + } + + return; +} + +static void +writer(void) +{ + + for (;;) { + ck_brlock_write_lock(&lock); + /* Write-side critical section. */ + ck_brlock_write_unlock(&lock); + + if (ck_brlock_write_trylock(&lock, 1) == true) { + /* Write-side critical section. */ + ck_brlock_write_unlock(&lock); + } + } + + return; +} +.Ed +.Sh SEE ALSO +.Xr ck_bytelock 3 , +.Xr ck_rwlock 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_cohort b/doc/ck_cohort new file mode 100644 index 0000000..4905418 --- /dev/null +++ b/doc/ck_cohort @@ -0,0 +1,211 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 February 24, 2013. +.Dt ck_cohort 3 +.Sh NAME +.Nm ck_cohort +.Nd generalized interface for lock cohorts +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_cohort.h +.Fn CK_COHORT_PROTOTYPE "COHORT_NAME cohort_name" "LOCK_FXN global_lock_method" \ +"LOCK_FXN global_unlock_method" "LOCK_FXN local_lock_method" "LOCK_FXN local_unlock_method" +.Fn CK_COHORT_TRYLOCK_PROTOTYPE "COHORT_NAME cohort_name" \ +"LOCK_FXN global_lock_method" "LOCK_FXN global_unlock_method" \ +"BOOL_LOCK_FXN global_locked_method" "BOOL_LOCK_FXN global_trylock_method" \ +"LOCK_FXN local_lock_method" "LOCK_FXN local_unlock_method" \ +"BOOL_LOCK_FXN local_locked_method" "BOOL_LOCK_FXN local_trylock_method" +.Fn CK_COHORT_INSTANCE "COHORT_NAME cohort_name" +.Fn CK_COHORT_INIT "COHORT_NAME cohort_name" "ck_cohort *cohort" \ +"void *global_lock" "void *local_lock" "unsigned int pass_limit" +.Fn CK_COHORT_LOCK "COHORT_NAME cohort_name" "ck_cohort *cohort" \ +"void *global_context" "void *local_context" +.Fn CK_COHORT_UNLOCK "COHORT_NAME cohort_name" "ck_cohort *cohort" \ +"void *global_context" "void *local_context" +.Pp +Where LOCK_FXN refers to a method with the signature +.br +void(void *lock, void *context) +.br +BOOL_LOCK_FXN refers to a method with the signature +.br +bool(void *lock, void *context) +.Pp +The +.Fa context +argument in each signature is used to pass along any additional information that +the lock might need for its lock, unlock and trylock methods. The values for this +argument are provided to each call to +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +and +.Xr CK_COHORT_TRYLOCK 3 +. +.Sh DESCRIPTION +ck_cohort.h provides an interface for defining lock cohorts with +arbitrary lock types. Cohorts are a mechanism for coordinating +threads on NUMA architectures in order to reduce the frequency +with which a lock is passed between threads on different clusters. +.Pp +Before using a cohort, the user must define a cohort type using +either the +.Fn CK_COHORT_PROTOTYPE +or the +.Fn CK_COHORT_TRYLOCK_PROTOTYPE +macros. These macros allow the user to specify the lock methods that +they would like the cohort to use. See the +.Xr CK_COHORT_PROTOTYPE 3 +and +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 +man pages for more details. +.Pp +.Sh EXAMPLE +.Bd -literal -offset indent +#include <stdlib.h> +#include <pthread.h> + +#include <ck_pr.h> +#include <ck_cohort.h> +#include <ck_spinlock.h> + +/* + * Create cohort methods with signatures that match + * the required signature + */ +static void +ck_spinlock_lock_with_context(ck_spinlock_t *lock, void *context) +{ + (void)context; + ck_spinlock_lock(lock); + return; +} + +static void +ck_spinlock_unlock_with_context(ck_spinlock_t *lock, void *context) +{ + (void)context; + ck_spinlock_unlock(lock); + return; +} + +static bool +ck_spinlock_locked_with_context(ck_spinlock_t *lock, void *context) +{ + (void)context; + return ck_spinlock_locked(lock); +} + +/* + * define a cohort type named "test_cohort" that will use + * the above methods for both its global and local locks + */ +CK_COHORT_PROTOTYPE(test_cohort, + ck_spinlock_lock_with_context, ck_spinlock_unlock_with_context, ck_spinlock_locked_with_context, + ck_spinlock_lock_with_context, ck_spinlock_unlock_with_context, ck_spinlock_locked_with_context) + +static ck_spinlock_t global_lock = CK_SPINLOCK_INITIALIZER; +static unsigned int ready; + +static void * +function(void *context) +{ + CK_COHORT_INSTANCE(test_cohort) *cohort = context; + + while (ready == 0); + + while (ready > 0) { + /* + * acquire the cohort lock before performing critical section. + * note that we pass NULL for both the global and local context + * arguments because neither the lock nor unlock functions + * will use them. + */ + CK_COHORT_LOCK(test_cohort, cohort, NULL, NULL); + + /* perform critical section */ + + /* relinquish cohort lock */ + CK_COHORT_UNLOCK(test_cohort, cohort, NULL, NULL); + } + + return NULL; +} + +int +main(void) +{ + unsigned int nthr = 4; + unsigned int n_cohorts = 2; + unsigned int i; + + /* allocate 2 cohorts of the defined type */ + CK_COHORT_INSTANCE(test_cohort) *cohorts = + calloc(n_cohorts, sizeof(CK_COHORT_INSTANCE(test_cohort))); + + /* create local locks to use with each cohort */ + ck_spinlock_t *local_locks = + calloc(n_cohorts, sizeof(ck_spinlock_t)); + + pthread_t *threads = + calloc(nthr, sizeof(pthread_t)); + + /* initialize each of the cohorts before using them */ + for (i = 0 ; i < n_cohorts ; ++i) { + CK_COHORT_INIT(test_cohort, cohorts + i, &global_lock, local_locks + i, + CK_COHORT_DEFAULT_LOCAL_PASS_LIMIT); + } + + /* start each thread and assign cohorts equally */ + for (i = 0 ; i < nthr ; ++i) { + pthread_create(threads + i, NULL, function, cohorts + (i % n_cohorts)); + } + + ck_pr_store_uint(&ready, 1); + sleep(10); + ck_pr_store_uint(&ready, 0); + + for (i = 0 ; i < nthr ; ++i) { + pthread_join(threads[i], NULL); + } + + return 0; +} +.Ed +.Sh SEE ALSO +.Xr CK_COHORT_PROTOTYPE 3 , +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_COHORT_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_elide b/doc/ck_elide new file mode 100644 index 0000000..c068567 --- /dev/null +++ b/doc/ck_elide @@ -0,0 +1,252 @@ +.\" +.\" 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 13, 2013. +.Dt ck_elide 3 +.Sh NAME +.Nm CK_ELIDE_PROTOTYPE , +.Nm CK_ELIDE_LOCK_ADAPTIVE , +.Nm CK_ELIDE_UNLOCK_ADAPTIVE , +.Nm CK_ELIDE_LOCK , +.Nm CK_ELIDE_UNLOCK , +.Nm CK_ELIDE_TRYLOCK_PROTOTYPE , +.Nm CK_ELIDE_TRYLOCK +.Nd lock elision wrappers +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_elide.h +.Pp +.Dv ck_elide_stat_t stat = CK_ELIDE_STAT_INITIALIZER; +.Pp +.Ft void +.Fn ck_elide_stat_init "ck_elide_stat_t *" +.Pp +.Dv struct ck_elide_config config = CK_ELIDE_CONFIG_DEFAULT_INITIALIZER; +.Pp +.Bd -literal -offset +struct ck_elide_config { + unsigned short skip_busy; + short retry_busy; + unsigned short skip_other; + short retry_other; + unsigned short skip_conflict; + short retry_conflict; +}; +.Ed +.Pp +.Fn CK_ELIDE_PROTOTYPE "NAME" "TYPE" "LOCK_PREDICATE" "LOCK_FUNCTION" "UNLOCK_PREDICATE" "UNLOCK_FUNCTION" +.Fn CK_ELIDE_LOCK_ADAPTIVE "NAME" "ck_elide_stat_t *" "struct ck_elide_config *" "TYPE *" +.Fn CK_ELIDE_UNLOCK_ADAPTIVE "NAME" "ck_elide_stat_t *" "TYPE *" +.Fn CK_ELIDE_LOCK "NAME" "TYPE *" +.Fn CK_ELIDE_UNLOCK "NAME" "TYPE *" +.Fn CK_ELIDE_TRYLOCK_PROTOTYPE "NAME" "TYPE" "LOCK_PREDICATE" "TRYLOCK_FUNCTION" +.Sh DESCRIPTION +These macros implement lock elision wrappers for a user-specified single-argument +lock interface. The wrappers will attempt to elide lock acquisition, allowing +concurrent execution of critical sections that do not issue conflicting memory +operations. If any threads have successfully elided a lock acquisition, +conflicting memory operations will roll-back any side-effects of the critical +section and force every thread to retry the lock acquisition regularly. +.Pp +.Fn CK_ELIDE_LOCK , +.Fn CK_ELIDE_UNLOCK , +.Fn CK_ELIDE_LOCK_ADAPTIVE , +and +.Fn CK_ELIDE_UNLOCK_ADAPTIVE +macros require +a previous +.Fn CK_ELIDE_PROTOTYPE +with the same +.Fa NAME . +Elision is attempted if the +.Fa LOCK_PREDICATE +function returns false. If +.Fa LOCK_PREDICATE +returns true then elision is aborted and +.Fa LOCK_FUNCTION +is executed instead. If any threads are in an elided critical section, +.Fa LOCK_FUNCTION +must force them to rollback through a conflicting memory operation. +The +.Fa UNLOCK_PREDICATE +function must return true if the lock is acquired by the caller, meaning +that the lock was not successfully elided. If +.Fa UNLOCK_PREDICATE +returns true, then the +.Fa UNLOCK_FUNCTION +is executed. If RTM is unsupported (no CK_F_PR_RTM macro) then +.Fn CK_ELIDE_LOCK +and +.Fn CK_ELIDE_LOCK_ADAPTIVE +will immediately call +.Fn LOCK_FUNCTION . +.Fn CK_ELIDE_UNLOCK +and +.Fn CK_ELIDE_UNLOCK_ADAPTIVE +will immediately call +.Fn UNLOCK_FUNCTION . +.Pp +.Fn CK_ELIDE_TRYLOCK +requires a previous +.Fn CK_ELIDE_TRYLOCK_PROTOTYPE +with the same name. +Elision is attempted if the +.Fa LOCK_PREDICATE +function returns false. If +.Fa LOCK_PREDICATE +returns true or if elision fails then the +operation is aborted. If RTM is unsupported +(no CK_F_PR_RTM macro) then +.Fn CK_ELIDE_TRYLOCK +will immediately call +.Fn TRYLOCK_FUNCTION . +.Pp +.Fn CK_ELIDE_LOCK_ADAPTIVE +and +.Fn CK_ELIDE_UNLOCK_ADAPTIVE +will adapt the elision behavior associated with lock operations +according to the run-time behavior of the program. This behavior +is defined by the ck_elide_config structure pointer passed to +.Fn CK_ELIDE_LOCK_ADAPTIVE . +A thread-local ck_elide_stat structure must be passed to both +.Fn CK_ELIDE_LOCK_ADAPTIVE +and +.Fn CK_ELIDE_UNLOCK_ADAPTIVE . +This structure is expected to be unique for different workloads, +may not be re-used in recursive acquisitions and must match the +lifetime of the lock it is associated with. It is safe to mix +adaptive calls with best-effort calls. +.Pp +Both ck_spinlock.h and ck_rwlock.h define ck_elide wrappers under +the ck_spinlock and ck_rwlock namespace, respectively. +.Sh EXAMPLES +This example utilizes built-in lock elision facilities in ck_rwlock and ck_spinlock. +.Bd -literal -offset indent +#include <ck_rwlock.h> +#include <ck_spinlock.h> + +static ck_rwlock_t rw = CK_RWLOCK_INITIALIZER; +static struct ck_elide_config rw_config = + CK_ELIDE_CONFIG_DEFAULT_INITIALIZER; +static __thread ck_elide_stat_t rw_stat = + CK_ELIDE_STAT_INITIALIZER; + +static ck_spinlock_t spinlock = CK_SPINLOCK_INITIALIZER; +static struct ck_elide_config spinlock_config = + CK_ELIDE_CONFIG_DEFAULT_INITIALIZER; +static __thread ck_elide_stat_t spinlock_stat = + CK_ELIDE_STAT_INITIALIZER; + +void +function(void) +{ + + /* Lock-unlock write-side lock in weak best-effort manner. */ + CK_ELIDE_LOCK(ck_rwlock_write, &rw); + CK_ELIDE_UNLOCK(ck_rwlock_write, &rw); + + /* Attempt to acquire the write-side lock. */ + if (CK_ELIDE_TRYLOCK(ck_rwlock_write, &rw) == true) + CK_ELIDE_UNLOCK(ck_rwlock_write, &rw); + + /* Lock-unlock read-side lock in weak best-effort manner. */ + CK_ELIDE_LOCK(ck_rwlock_read, &rw); + CK_ELIDE_UNLOCK(ck_rwlock_read, &rw); + + /* Attempt to acquire the read-side lock. */ + if (CK_ELIDE_TRYLOCK(ck_rwlock_read, &rw) == true) + CK_ELIDE_UNLOCK(ck_rwlock_read, &rw); + + /* Lock-unlock write-side lock in an adaptive manner. */ + CK_ELIDE_LOCK_ADAPTIVE(ck_rwlock_write, &rw_stat, + &rw_config, &rw); + CK_ELIDE_UNLOCK_ADAPTIVE(ck_rwlock_write, &rw_stat, + &rw_config, &rw); + + /* Lock-unlock read-side lock in an adaptive manner. */ + CK_ELIDE_LOCK_ADAPTIVE(ck_rwlock_read, &rw_stat, + &rw_config, &rw); + CK_ELIDE_UNLOCK_ADAPTIVE(ck_rwlock_read, &rw_stat, + &rw_config, &rw); + + /* Lock-unlock spinlock in weak best-effort manner. */ + CK_ELIDE_LOCK(ck_spinlock, &spinlock); + CK_ELIDE_UNLOCK(ck_spinlock, &spinlock); + + /* Attempt to acquire the lock. */ + if (CK_ELIDE_TRYLOCK(ck_spinlock, &lock) == true) + CK_ELIDE_UNLOCK(ck_spinlock, &spinlock); + + /* Lock-unlock spinlock in an adaptive manner. */ + CK_ELIDE_LOCK_ADAPTIVE(ck_spinlock, &spinlock_stat, + &spinlock_config, &spinlock); + CK_ELIDE_UNLOCK_ADAPTIVE(ck_spinlock, &spinlock_stat, + &spinlock_config, &spinlock); +} +.Ed +.Pp +In this example, user-defined locking functions are provided an elision +implementation. +.Bd -literal -offset indent +/* Assume lock_t has been previously defined. */ +#include <ck_elide.h> + +/* + * This function returns true if the lock is unavailable at the time + * it was called or false if the lock is available. + */ +bool is_locked(lock_t *); + +/* + * This function acquires the supplied lock. + */ +void lock(lock_t *); + +/* + * This function releases the lock. + */ +void unlock(lock_t *); + +CK_ELIDE_PROTOTYPE(my_lock, lock_t, is_locked, lock, is_locked, unlock) + +static lock_t lock; + +void +function(void) +{ + + CK_ELIDE_LOCK(my_lock, &lock); + CK_ELIDE_UNLOCK(my_lock, &lock); +} +.Ed +.Sh SEE ALSO +.Xr ck_rwlock 3 , +.Xr ck_spinlock 3 +.Pp +Ravi Rajwar and James R. Goodman. 2001. Speculative lock elision: enabling highly concurrent multithreaded execution. In Proceedings of the 34th annual ACM/IEEE international symposium on Microarchitecture (MICRO 34). IEEE Computer Society, Washington, DC, USA, 294-305. +.Pp +Additional information available at http://en.wikipedia.org/wiki/Transactional_Synchronization_Extensions and http://concurrencykit.org/ diff --git a/doc/ck_epoch_barrier b/doc/ck_epoch_barrier new file mode 100644 index 0000000..a586145 --- /dev/null +++ b/doc/ck_epoch_barrier @@ -0,0 +1,120 @@ +.\" +.\" 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 2, 2012 +.Dt CK_EPOCH_BARRIER 3 +.Sh NAME +.Nm ck_epoch_barrier +.Nd block until a grace period and all callbacks have been dispatched +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft void +.Fn ck_epoch_barrier "ck_epoch_record_t *record" +.Sh DESCRIPTION +The +.Fn ck_epoch_barrier 3 +function will block the caller until a grace period has been +detected, according to the semantics of epoch reclamation. +Any objects requiring safe memory reclamation which are logically +deleted are safe for physical deletion following a call to +.Fn ck_epoch_barrier 3 . This function will also dispatch all callbacks +associated with +.Fa epoch +that were previously scheduled via +.Fn ck_epoch_call 3 . +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_epoch.h> +#include <ck_stack.h> +#include <stdlib.h> + +/* + * epoch was previously initialized with ck_epoch_init. + * stack was previously initialized with ck_stack_init. + */ +ck_epoch_t *epoch; +ck_stack_t *stack; + +void +function(void) +{ + ck_epoch_record_t *record; + ck_stack_entry_t *s; + + record = malloc(sizeof *record); + ck_epoch_register(&epoch, record); + + /* + * We are using an epoch section here to guarantee no + * nodes in the stack are deleted while we are dereferencing + * them. This is needed here because there are multiple writers. + * If there was only one thread popping from the this stack, + * then there is no need to ck_epoch_begin/ck_epoch_end. + */ + ck_epoch_begin(record); + + /* Logically delete an object. */ + s = ck_stack_pop_upmc(stack); + + ck_epoch_end(record); + + /* + * Wait until no threads could possibly have a reference to the + * object we just popped (assume all threads are simply executing + * ck_stack_pop_upmc). + */ + ck_epoch_barrier(record); + + /* It is now safe to physically delete the object. */ + free(s); + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh ERRORS +Behavior is undefined if the object pointed to by +.Fa epoch +is not a valid epoch object. The object pointed to by +.Fa record +must have been previously registered via +.Fn ck_epoch_register 3 . +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_register 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_synchronize 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_begin 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_begin b/doc/ck_epoch_begin new file mode 100644 index 0000000..a44ecf8 --- /dev/null +++ b/doc/ck_epoch_begin @@ -0,0 +1,73 @@ +.\" +.\" 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 2, 2012 +.Dt CK_EPOCH_BEGIN 3 +.Sh NAME +.Nm ck_epoch_begin +.Nd begin epoch-protected segment of execution +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft void +.Fn ck_epoch_begin "ck_epoch_record_t *record" "ck_epoch_section_t *section" +.Sh DESCRIPTION +The +.Fn ck_epoch_begin 3 +function will mark the beginning of an epoch-protected code section. +An epoch-protected code section is delimited by a call to the +.Fn ck_epoch_end 3 +function. Though recursion is allowed for epoch-protected sections, +recursive calls will be associated with the +.Fn ck_epoch_begin 3 +that is at the top of the call stack. If a section is passed, then +recursion on a record will cause the epoch to be refreshed on entry +of every protected section. +.Sh RETURN VALUES +This function has no return value. +.Sh ERRORS +The object pointed to by +.Fa epoch +must have been previously initiated via +.Fn ck_epoch_init 3 . +The object pointed to by +.Fa record +must have been previously registered via +.Fn ck_epoch_register 3 . +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_register 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_synchronize 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_call b/doc/ck_epoch_call new file mode 100644 index 0000000..7390642 --- /dev/null +++ b/doc/ck_epoch_call @@ -0,0 +1,136 @@ +.\" +.\" 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 2, 2012 +.Dt CK_EPOCH_CALL 3 +.Sh NAME +.Nm ck_epoch_call +.Nd defer function execution until a grace period +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +typedef struct ck_epoch_entry ck_epoch_entry_t; +.br +typedef void ck_epoch_cb_t(ck_epoch_entry_t *); +.Ft void +.Fn ck_epoch_call "ck_epoch_record_t *record" "ck_epoch_entry_t *entry" "ck_epoch_cb_t *function" +.Sh DESCRIPTION +The +.Fn ck_epoch_call 3 +function will defer the execution of the function pointed to by +.Fa function +until a grace-period has been detected in +.Fa epoch . +The function will be provided +the pointer specified by +.Fa entry . +The function will execute at some time in the future via calls to +.Fn ck_epoch_reclaim 3 , +.Fn ck_epoch_barrier 3 +or +.Fn ck_epoch_poll 3 . +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_epoch.h> +#include <ck_stack.h> +#include <stdlib.h> + +/* + * epoch was previously initialized with ck_epoch_init. + */ +ck_epoch_t *epoch; + +struct object { + int value; + ck_epoch_entry_t epoch_entry; +}; +static struct object *global; + +CK_EPOCH_CONTAINER(struct object, epoch_entry, object_container) + +void +destroy_object(ck_epoch_entry_t *e) +{ + struct object *o = object_container(e); + + free(o); + return; +} + +void +function(void) +{ + ck_epoch_record_t *record; + struct object *n; + + record = malloc(sizeof *record); + ck_epoch_register(&epoch, record); + + n = malloc(sizeof *n); + if (n == NULL) + return; + + n->value = 1; + + /* + * We are using an epoch section here because there are multiple + * writers. It is also an option to use other forms of blocking + * write-side synchronization such as mutexes. + */ + ck_epoch_begin(record); + n = ck_pr_fas_ptr(&global, n); + ck_epoch_end(record); + + /* Defer destruction of previous object. */ + ck_epoch_call(record, &n->epoch_entry, destroy_object); + + /* Poll epoch sub-system in non-blocking manner. */ + ck_epoch_poll(record); + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh ERRORS +The object pointed to by +.Fa record +must have been previously registered via +.Fn ck_epoch_register 3 . +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_register 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_synchronize 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_begin 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_end b/doc/ck_epoch_end new file mode 100644 index 0000000..a36afbd --- /dev/null +++ b/doc/ck_epoch_end @@ -0,0 +1,64 @@ +.\" +.\" 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 2, 2012 +.Dt CK_EPOCH_END 3 +.Sh NAME +.Nm ck_epoch_end +.Nd end epoch-protected segment of execution +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft void +.Fn ck_epoch_end "ck_epoch_record_t *record" "ck_epoch_section_t *section" +.Sh DESCRIPTION +The +.Fn ck_epoch_end 3 +function will mark the end of an epoch-protected code section. +.Fa section +must point to a section object initialized previously with +.Fn ck_epoch_begin 3 . +.Sh RETURN VALUES +This function has no return value. +.Sh ERRORS +The object pointed to by +.Fa record +must have been previously registered via +.Fn ck_epoch_register 3 . +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_register 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_synchronize 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_begin 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_init b/doc/ck_epoch_init new file mode 100644 index 0000000..51a3e2a --- /dev/null +++ b/doc/ck_epoch_init @@ -0,0 +1,69 @@ +.\" +.\" 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 2, 2012 +.Dt CK_EPOCH_INIT 3 +.Sh NAME +.Nm ck_epoch_init +.Nd initialize epoch reclamation object +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft void +.Fn ck_epoch_init "ck_epoch_t *epoch" +.Sh DESCRIPTION +The +.Fn ck_epoch_init +function initializes the epoch object pointed to by the +.Fa epoch +pointer. +.Sh RETURN VALUES +This function has no return value. +.Sh ERRORS +.Bl -tag -width Er +.Pp +The behavior of +.Fn ck_epoch_init +is undefined if +.Fa epoch +is not a pointer to a +.Tn ck_epoch_t +object. +.El +.Sh SEE ALSO +.Xr ck_epoch_register 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_synchronize 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_begin 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_poll b/doc/ck_epoch_poll new file mode 100644 index 0000000..68c4a4e --- /dev/null +++ b/doc/ck_epoch_poll @@ -0,0 +1,71 @@ +.\" +.\" 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 2, 2012 +.Dt CK_EPOCH_POLL 3 +.Sh NAME +.Nm ck_epoch_poll +.Nd non-blocking poll of epoch object for dispatch cycles +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft bool +.Fn ck_epoch_poll "ck_epoch_record_t *record" +.Sh DESCRIPTION +The +.Fn ck_epoch_poll 3 +function will attempt to dispatch any functions associated with the +object pointed to by +.Fa epoch +via +.Fn ck_epoch_call 3 +if deemed safe. This function is meant to be used in cases epoch +reclamation cost must be amortized over time in a manner that does +not affect caller progress. +.Sh RETURN VALUES +This function will return true if at least one function was dispatched. +This function will return false if it has determined not all threads have +observed the latest generation of epoch-protected objects. Neither value +indicates an error. +.Sh ERRORS +Behavior is undefined if the object pointed to by +.Fa record +has not have been previously registered via +.Fn ck_epoch_register 3 . +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_register 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_synchronize 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_begin 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_reclaim b/doc/ck_epoch_reclaim new file mode 100644 index 0000000..ffe3bac --- /dev/null +++ b/doc/ck_epoch_reclaim @@ -0,0 +1,92 @@ +.\" +.\" 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 May 2, 2013 +.Dt CK_EPOCH_RECLAIM 3 +.Sh NAME +.Nm ck_epoch_reclaim +.Nd immediately execute all deferred callbacks +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft void +.Fn ck_epoch_reclaim "ck_epoch_record_t *record" +.Sh DESCRIPTION +The +.Fn ck_epoch_reclaim 3 +function will unconditionally execute all callbacks +that have been deferred with +.Fn ck_epoch_call 3 . +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_epoch.h> +#include <ck_stack.h> +#include <stdlib.h> + +/* + * epoch was previously initialized with ck_epoch_init. + */ +ck_epoch_t *epoch; + +void +function(void) +{ + ck_epoch_record_t *record; + + logically_delete(object); + ck_epoch_call(epoch, record, &object->epoch_entry, destructor); + + /* + * Wait until no threads could possibly have a reference to the + * object we just deleted. + */ + ck_epoch_synchronize(epoch, record); + + /* + * Execute all deferred callbacks. + */ + ck_epoch_reclaim(record); + + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_register 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_begin 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_recycle b/doc/ck_epoch_recycle new file mode 100644 index 0000000..530079c --- /dev/null +++ b/doc/ck_epoch_recycle @@ -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 2, 2012 +.Dt CK_EPOCH_RECYCLE 3 +.Sh NAME +.Nm ck_epoch_recycle +.Nd return an epoch record that may be used by caller +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft ck_epoch_record_t * +.Fn ck_epoch_recycle "ck_epoch_t *epoch" +.Sh DESCRIPTION +The +.Fn ck_epoch_recycle 3 +function attempts to return an unused epoch record object for use by +the caller. These epoch records were associated with previous calls +to the +.Fn ck_epoch_unregister 3 +function. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_epoch.h> +#include <stdlib.h> + +/* + * epoch was previously initialized with ck_epoch_init. + */ +ck_epoch_t *epoch; + +void +function(void) +{ + ck_epoch_record_t *record; + + record = ck_epoch_recycle(&epoch); + if (record == NULL) { + record = malloc(sizeof *record); + if (record == NULL) + return; + + ck_epoch_register(&epoch, record); + } + + /* + * After we are done, we will unregister the record so it + * can be used by other new participants in the epoch system + * provided by the object pointed to by "epoch". + */ + ck_epoch_unregister(&epoch, record); + return; +} +.Ed +.Sh RETURN VALUES +This function returns a pointer to a +.Dv ck_epoch_record_t +object. If no unused record was found to be associated with the +object pointed to by +.Fa epoch , +then the function will return NULL. +.Sh ERRORS +Behavior is undefined if the object pointed to by +.Fa epoch +is not a valid epoch object. +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_register 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_synchronize 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_begin 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_register b/doc/ck_epoch_register new file mode 100644 index 0000000..85ea461 --- /dev/null +++ b/doc/ck_epoch_register @@ -0,0 +1,67 @@ +.\" +.\" 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 2, 2012 +.Dt CK_EPOCH_REGISTER 3 +.Sh NAME +.Nm ck_epoch_register +.Nd register a thread for epoch reclamation +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft void +.Fn ck_epoch_register "ck_epoch_t *epoch" "ck_epoch_record_t *record" +.Sh DESCRIPTION +The +.Fn ck_epoch_register 3 +function associates a record object specified by the +.Fa record +pointer with the epoch object pointed to by +.Fa epoch . +Any thread or processor that will require safe memory reclamation +guarantees must register a unique record object. After registration, the +object pointed to by the +.Fa record +argument will have lifetime managed by the underlying epoch sub-system. +The record object must not be destroyed after it is associated with a +.Fn ck_epoch_register 3 +call. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_synchronize 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_begin 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_synchronize b/doc/ck_epoch_synchronize new file mode 100644 index 0000000..6c9a698 --- /dev/null +++ b/doc/ck_epoch_synchronize @@ -0,0 +1,119 @@ +.\" +.\" 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 2, 2012 +.Dt CK_EPOCH_SYNCHRONIZE 3 +.Sh NAME +.Nm ck_epoch_synchronize +.Nd block until a grace period has been detected +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft void +.Fn ck_epoch_synchronize "ck_epoch_record_t *record" +.Sh DESCRIPTION +The +.Fn ck_epoch_synchronize 3 +function will block the caller until a grace period has been +detected, according to the semantics of epoch reclamation. +Any objects requiring safe memory reclamation which are logically +deleted are safe for physical deletion following a call to +.Fn ck_epoch_synchronize 3 . +If you require that all callbacks be dispatched, then it is suggested +that you use +.Fn ck_epoch_barrier 3 +instead or follow a call of +.Fn ck_epoch_synchronize 3 +with +.Fn ck_epoch_reclaim 3 . +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_epoch.h> +#include <ck_stack.h> +#include <stdlib.h> + +/* + * epoch was previously initialized with ck_epoch_init. + * stack was previously initialized with ck_stack_init. + */ +ck_epoch_t *epoch; +ck_stack_t *stack; + +void +function(void) +{ + ck_epoch_record_t *record; + ck_stack_entry_t *s; + + record = malloc(sizeof *record); + ck_epoch_register(&epoch, record); + + /* + * We are using an epoch section here to guarantee no + * nodes in the stack are deleted while we are dereferencing + * them. This is needed here because there are multiple writers. + * If there was only one thread popping from the this stack, + * then there is no need to ck_epoch_begin/ck_epoch_end. + */ + ck_epoch_begin(record); + + /* Logically delete an object. */ + s = ck_stack_pop_upmc(stack); + + ck_epoch_end(record); + + /* + * Wait until no threads could possibly have a reference to the + * object we just popped (assume all threads are simply executing + * ck_stack_pop_upmc). + */ + ck_epoch_synchronize(record); + + /* It is now safe to physically delete the object. */ + free(s); + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh ERRORS +The object pointed to by .Fa record must have been previously registered via +.Fn ck_epoch_register 3 . +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_register 3 , +.Xr ck_epoch_unregister 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_begin 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_epoch_unregister b/doc/ck_epoch_unregister new file mode 100644 index 0000000..3be537f --- /dev/null +++ b/doc/ck_epoch_unregister @@ -0,0 +1,65 @@ +.\" +.\" 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 2, 2012 +.Dt CK_EPOCH_UNREGISTER 3 +.Sh NAME +.Nm ck_epoch_unregister +.Nd unregister a thread for epoch reclamation +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_epoch.h +.Ft void +.Fn ck_epoch_unregister "ck_epoch_record_t *record" +.Sh DESCRIPTION +The +.Fn ck_epoch_unregister 3 +function allows for the record pointed by the +.Fa record +pointer to be used as a return value by the +.Fn ck_epoch_recycle 3 +function. This record can now be used by another thread +of execution. Behavior is undefined if the object pointed by +.Fa record +is modified in any way, even after a call is made to the +.Fn ck_epoch_unregister 3 +function. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_epoch_init 3 , +.Xr ck_epoch_register 3 , +.Xr ck_epoch_recycle 3 , +.Xr ck_epoch_poll 3 , +.Xr ck_epoch_synchronize 3 , +.Xr ck_epoch_reclaim 3 , +.Xr ck_epoch_barrier 3 , +.Xr ck_epoch_call 3 , +.Xr ck_epoch_begin 3 , +.Xr ck_epoch_end 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_apply b/doc/ck_hs_apply new file mode 100644 index 0000000..5664f73 --- /dev/null +++ b/doc/ck_hs_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_HS_APPLY 3 +.Sh NAME +.Nm ck_hs_apply +.Nd apply a function to hash set value +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft void * +.Fn ck_hs_apply_fn_t "void *key" "void *closure" +.Ft bool +.Fn ck_hs_apply "ck_hs_t *hs" "unsigned long hash" "const void *key" "ck_hs_apply_fn_t *function" "void *argument" +.Sh DESCRIPTION +The +.Fn ck_hs_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_hs_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_hs_apply 3 +returns true and otherwise returns false on failure. +.Sh SEE ALSO +.Xr ck_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr ck_hs_fas 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_count b/doc/ck_hs_count new file mode 100644 index 0000000..c12d8f7 --- /dev/null +++ b/doc/ck_hs_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_HS_COUNT 3 +.Sh NAME +.Nm ck_hs_count +.Nd returns number of entries in hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft unsigned long +.Fn ck_hs_count "ck_hs_t *hs" +.Sh DESCRIPTION +The +.Fn ck_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_destroy b/doc/ck_hs_destroy new file mode 100644 index 0000000..952502b --- /dev/null +++ b/doc/ck_hs_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_HS_DESTROY 3 +.Sh NAME +.Nm ck_hs_destroy +.Nd destroy hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft void +.Fn ck_hs_destroy "ck_hs_t *hs" +.Sh DESCRIPTION +The +.Fn ck_hs_destroy 3 +function will request that the underlying allocator, as specified by the +.Xr ck_hs_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_hs_destroy 3 +is called. +.Sh RETURN VALUES +.Fn ck_hs_destroy 3 +has no return value. +.Sh ERRORS +This function is guaranteed not to fail. +.Sh SEE ALSO +.Xr ck_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_fas b/doc/ck_hs_fas new file mode 100644 index 0000000..69760b5 --- /dev/null +++ b/doc/ck_hs_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_HS_FAS 3 +.Sh NAME +.Nm ck_hs_fas +.Nd fetch and store key in hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_fas "ck_hs_t *hs" "unsigned long hash" "const void *key" "void **previous" +.Sh DESCRIPTION +The +.Fn ck_hs_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_HS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_hs_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_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_gc b/doc/ck_hs_gc new file mode 100644 index 0000000..85abba2 --- /dev/null +++ b/doc/ck_hs_gc @@ -0,0 +1,88 @@ +.\" +.\" 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_HS_GC 3 +.Sh NAME +.Nm ck_hs_gc +.Nd perform maintenance on a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_gc "ck_hs_t *hs" "unsigned long cycles" "unsigned long seed" +.Sh DESCRIPTION +The +.Fn ck_hs_gc 3 +function will perform various maintenance routines on the hash set +pointed to by +.Fa hs , +including defragmentation of probe sequences with respect to tombstones +and in the case that the delete workload hint has been passed, recalculation +of probe sequence bounds. The +.Fa cycles +argument is used to indicate how many hash set entries should be subject +to attempted maintenance. If +.Fa cycles +is 0, then maintenance is performed on the complete hash set. The +.Fa seed +argument determines the start location of the maintenance process. If +.Fa cycles +is non-zero, it is recommended that +.Fa seed +is some random value. If the delete hint has been passed, the function +will require an additional 12% of memory (with respect to existing +memory usage of the set), until operation completion. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_get b/doc/ck_hs_get new file mode 100644 index 0000000..9c1600d --- /dev/null +++ b/doc/ck_hs_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_HS_GET 3 +.Sh NAME +.Nm ck_hs_get +.Nd load a key from a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft void * +.Fn ck_hs_get "ck_hs_t *hs" "unsigned long hash" "const void *key" +.Sh DESCRIPTION +The +.Fn ck_hs_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_HS_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_grow b/doc/ck_hs_grow new file mode 100644 index 0000000..ed35cd0 --- /dev/null +++ b/doc/ck_hs_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_HS_GROW 3 +.Sh NAME +.Nm ck_hs_grow +.Nd enlarge hash set capacity +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_grow "ck_hs_t *hs" "unsigned long capacity" +.Sh DESCRIPTION +The +.Fn ck_hs_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_hs 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_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_init b/doc/ck_hs_init new file mode 100644 index 0000000..cfcbf63 --- /dev/null +++ b/doc/ck_hs_init @@ -0,0 +1,169 @@ +.\" +.\" 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_HS_INIT 3 +.Sh NAME +.Nm ck_hs_init +.Nd initialize a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft typedef unsigned long +.Fn ck_hs_hash_cb_t "const void *key" "unsigned long seed" +.Ft typedef bool +.Fn ck_hs_compare_cb_t "const void *c1" "const void *c2" +.Ft bool +.Fn ck_hs_init "ck_hs_t *hs" "unsigned int mode" "ck_hs_hash_cb_t *hash_function" "ck_hs_compare_cb_t *compare" "struct ck_malloc *allocator" "unsigned long capacity" "unsigned long seed" +.Sh DESCRIPTION +The +.Fn ck_hs_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_HS_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_HS_MODE_DIRECT +The hash set is meant to directly store key values and that all +bits of the key are used to encode values. +.El +.Pp +The concurrent access model is specified by: +.Bl -tag -width indent +.It CK_HS_MODE_SPMC +The hash set should allow for concurrent readers in the +presence of a single writer. +.It CK_HS_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 +.It CK_HS_MODE_DELETE +The hash set is expected to have a delete-heavy workload. +At the cost of approximately 13% increased memory usage, +allow for stronger per-slot probe bounds to combat the +effects of tombstone accumulation. +.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_hs_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_hs_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_hs_init +is undefined if +.Fa hs +is not a pointer to a +.Tn ck_hs_t +object. +.El +.Sh SEE ALSO +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_iterator_init b/doc/ck_hs_iterator_init new file mode 100644 index 0000000..d2c25cc --- /dev/null +++ b/doc/ck_hs_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_HS_ITERATOR_INIT 3 +.Sh NAME +.Nm ck_hs_iterator_init +.Nd initialize hash set iterator +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Pp +.Dv ck_hs_iterator_t iterator = CK_HS_ITERATOR_INITIALIZER +.Pp +.Ft void +.Fn ck_hs_iterator_init "ck_hs_iterator_t *iterator" +.Sh DESCRIPTION +The +.Fn ck_hs_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_HS_ITERATOR_INITIALIZER value. +.Pp +An iterator is used to iterate through hash set entries with the +.Xr ck_hs_next 3 +function. +.Sh RETURN VALUES +.Fn ck_hs_iterator_init 3 +has no return value. +.Sh ERRORS +This function will not fail. +.Sh SEE ALSO +.Xr ck_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_move b/doc/ck_hs_move new file mode 100644 index 0000000..1d30195 --- /dev/null +++ b/doc/ck_hs_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_HS_MOVE 3 +.Sh NAME +.Nm ck_hs_move +.Nd move one from hash set to another +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_move "ck_hs_t *destination" "ck_hs_t *source" "ck_hs_hash_cb_t *hash_cb" "ck_hs_compare_cb_t *compare_cb" "struct ck_malloc *m" +.Sh DESCRIPTION +The +.Fn ck_hs_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_hs_get 3 +and +.Xr ck_hs_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_hs_move 3 +returns true and otherwise returns false to indicate an error. +.Sh SEE ALSO +.Xr ck_hs_init 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_next b/doc/ck_hs_next new file mode 100644 index 0000000..67e083e --- /dev/null +++ b/doc/ck_hs_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_HS_NEXT 3 +.Sh NAME +.Nm ck_hs_next +.Nd iterate to next entry in hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_next "ck_hs_t *hs" "ck_hs_iterator_t *iterator" "void **entry" +.Sh DESCRIPTION +The +.Fn ck_hs_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_hs_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_hs_iterator_init 3 +function or statically initialized using CK_HS_ITERATOR_INITIALIZER. +.Sh RETURN VALUES +If +.Fn ck_hs_next 3 +returns true then the object pointed to by +.Fa entry +points to a valid hash set key. If +.Fn ck_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_put b/doc/ck_hs_put new file mode 100644 index 0000000..8f8f55f --- /dev/null +++ b/doc/ck_hs_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_HS_PUT 3 +.Sh NAME +.Nm ck_hs_put +.Nd store unique key into a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_put "ck_hs_t *hs" "unsigned long hash" "const void *key" +.Sh DESCRIPTION +The +.Fn ck_hs_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_HS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_hs_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_hs_set 3 +function. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_put_unique b/doc/ck_hs_put_unique new file mode 100644 index 0000000..f60c543 --- /dev/null +++ b/doc/ck_hs_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_HS_PUT_UNIQUE 3 +.Sh NAME +.Nm ck_hs_put_unique +.Nd unconditionally store unique key into a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_put_unique "ck_hs_t *hs" "unsigned long hash" "const void *key" +.Sh DESCRIPTION +The +.Fn ck_hs_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_HS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_hs_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_hs_set 3 +function. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_rebuild b/doc/ck_hs_rebuild new file mode 100644 index 0000000..a49bb28 --- /dev/null +++ b/doc/ck_hs_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_HS_REBUILD 3 +.Sh NAME +.Nm ck_hs_rebuild +.Nd rebuild a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_rebuild "ck_hs_t *hs" +.Sh DESCRIPTION +The +.Fn ck_hs_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_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_remove b/doc/ck_hs_remove new file mode 100644 index 0000000..10ccfb6 --- /dev/null +++ b/doc/ck_hs_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_HS_REMOVE 3 +.Sh NAME +.Nm ck_hs_remove +.Nd remove key from a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft void * +.Fn ck_hs_remove "ck_hs_t *hs" "unsigned long hash" "const void *key" +.Sh DESCRIPTION +The +.Fn ck_hs_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_HS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_hs_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_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_reset b/doc/ck_hs_reset new file mode 100644 index 0000000..e6ce72e --- /dev/null +++ b/doc/ck_hs_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_HS_RESET 3 +.Sh NAME +.Nm ck_hs_reset +.Nd remove all keys from a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_reset "ck_hs_t *hs" +.Sh DESCRIPTION +The +.Fn ck_hs_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_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_reset_size b/doc/ck_hs_reset_size new file mode 100644 index 0000000..801c063 --- /dev/null +++ b/doc/ck_hs_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_HS_RESET_SIZE 3 +.Sh NAME +.Nm ck_hs_reset_size +.Nd remove all keys from a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_reset_size "ck_hs_t *hs" "unsigned long size" +.Sh DESCRIPTION +The +.Fn ck_hs_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_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_set b/doc/ck_hs_set new file mode 100644 index 0000000..e9ba9f1 --- /dev/null +++ b/doc/ck_hs_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_HS_SET 3 +.Sh NAME +.Nm ck_hs_set +.Nd store key into a hash set +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft bool +.Fn ck_hs_set "ck_hs_t *hs" "unsigned long hash" "const void *key" "void **previous" +.Sh DESCRIPTION +The +.Fn ck_hs_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_HS_HASH 3 +macro). +.Pp +If the call to +.Fn ck_hs_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_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 , +.Xr ck_hs_stat 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_hs_stat b/doc/ck_hs_stat new file mode 100644 index 0000000..796a894 --- /dev/null +++ b/doc/ck_hs_stat @@ -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_HS_STAT 3 +.Sh NAME +.Nm ck_hs_stat +.Nd get hash set status +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_hs.h +.Ft void +.Fn ck_hs_stat "ck_hs_t *hs" "struct ck_hs_stat *st" +.Sh DESCRIPTION +The +.Fn ck_hs_stat 3 +function will store various hash set statistics in +the object pointed to by +.Fa st . +The ck_hs_stat structure is defined as follows: +.Bd -literal -offset indent +struct ck_hs_stat { + unsigned long tombstones; /* Current number of tombstones in hash set. */ + 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_hs_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_hs_init 3 , +.Xr ck_hs_move 3 , +.Xr ck_hs_destroy 3 , +.Xr CK_HS_HASH 3 , +.Xr ck_hs_iterator_init 3 , +.Xr ck_hs_next 3 , +.Xr ck_hs_get 3 , +.Xr ck_hs_put 3 , +.Xr ck_hs_put_unique 3 , +.Xr ck_hs_set 3 , +.Xr ck_hs_fas 3 , +.Xr ck_hs_remove 3 , +.Xr ck_hs_grow 3 , +.Xr ck_hs_gc 3 , +.Xr ck_hs_rebuild 3 , +.Xr ck_hs_count 3 , +.Xr ck_hs_reset 3 , +.Xr ck_hs_reset_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ht_count b/doc/ck_ht_count new file mode 100644 index 0000000..ba10835 --- /dev/null +++ b/doc/ck_ht_count @@ -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 March 29, 2012 +.Dt CK_HT_COUNT 3 +.Sh NAME +.Nm ck_ht_count +.Nd return count of key-value pairs in hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft uint64_t +.Fn ck_ht_count "ck_ht_t *ht" +.Sh DESCRIPTION +The +.Fn ck_ht_count +function will return the number of entries in the hash table +pointed to be the +.Fa ht +argument. The function may only be called without the presence +of concurrent write operations. +.Sh ERRORS +Behavior is undefined if +.Fa ht +has not been initialized. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_reset_size_spmc 3 , +.Xr ck_ht_reset_spmc 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/ diff --git a/doc/ck_ht_destroy b/doc/ck_ht_destroy new file mode 100644 index 0000000..95e4acb --- /dev/null +++ b/doc/ck_ht_destroy @@ -0,0 +1,87 @@ +.\" +.\" 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 March 29, 2012 +.Dt CK_HT_DESTROY 3 +.Sh NAME +.Nm ck_ht_destroy +.Nd immediately destroy a hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void +.Fn ck_ht_destroy "ck_ht_t *ht" +.Sh DESCRIPTION +The +.Fn ck_ht_destroy +function will request that the underlying allocator, as specified by the +.Xr ck_ht_init 3 +function, immediately destroy the object pointed to by the +.Fa ht +argument. +.Pp +The user must guarantee that no threads are accessing the object pointed to +by +.Fa ht +when +.Fn ck_ht_destroy +is called. +.Sh RETURN VALUES +.Fn ck_ht_destroy +has no return value. +.Sh ERRORS +.Bl -tag -width Er +This function is guaranteed not to fail. +.El +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 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_reset_size_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/ diff --git a/doc/ck_ht_entry_empty b/doc/ck_ht_entry_empty new file mode 100644 index 0000000..9233344 --- /dev/null +++ b/doc/ck_ht_entry_empty @@ -0,0 +1,90 @@ +.\" +.\" 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 March 29, 2012 +.Dt CK_HT_ENTRY_EMPTY 3 +.Sh NAME +.Nm ck_ht_entry_empty +.Nd determine whether entry contains a key-value pair +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_entry_empty "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_empty +function will return +.Dv false +if +.Fa entry +points to a valid key-value pair. If +.Fa entry +does not point to a valid key-value pair it +returns +.Dv true. +It is expected that the object pointed to by +.Fa entry +was initialized by a preceding call to the +.Xr ck_ht_entry_set +family of functions, the +.Xr ck_ht_get_spmc 3 +function or the +.Xr ck_ht_set_spmc 3 +function. +.Sh ERRORS +Behavior is undefined if +.Fa entry +has not been initialized. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 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/ diff --git a/doc/ck_ht_entry_key b/doc/ck_ht_entry_key new file mode 100644 index 0000000..5003a1a --- /dev/null +++ b/doc/ck_ht_entry_key @@ -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 March 30, 2012 +.Dt CK_HT_ENTRY_KEY 3 +.Sh NAME +.Nm ck_ht_entry_key +.Nd return pointer to key as specified in hash table entry +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void * +.Fn ck_ht_entry_key "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_key +function will return the key pointer as specified in the +object pointed to by the +.Fa entry +argument. +.Pp +It is expected that the entry is +associated with a hash table initialized with +.Dv CK_HT_MODE_BYTESTRING +(see +.Xr ck_ht_init 3 +for more information). +.Sh RETURN VALUES +.Fn ck_ht_entry_key +returns +.Dv NULL +if the entry is empty. +.Sh ERRORS +Behavior is undefined if +.Fa entry +has not been initialized. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 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_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/ diff --git a/doc/ck_ht_entry_key_direct b/doc/ck_ht_entry_key_direct new file mode 100644 index 0000000..e0a75a2 --- /dev/null +++ b/doc/ck_ht_entry_key_direct @@ -0,0 +1,91 @@ +.\" +.\" 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 March 30, 2012 +.Dt CK_HT_ENTRY_KEY_DIRECT 3 +.Sh NAME +.Nm ck_ht_entry_key_direct +.Nd return key value as specified in hash table entry +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft uintptr_t +.Fn ck_ht_entry_key_direct "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_key_direct +function will return the key value as specified in the +object pointed to by the +.Fa entry +argument. +.Pp +It is expected that the entry is +associated with a hash table initialized with +.Dv CK_HT_MODE_DIRECT +(see +.Xr ck_ht_init 3 +for more information). +.Sh RETURN VALUES +.Fn ck_ht_entry_key_direct +returns +.Dv 0 +if the entry is empty. Otherwise, it returns the +key value stored in the object pointed to by the +.Fa entry +argument. +.Sh ERRORS +Behavior is undefined if +.Fa entry +has not been initialized. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 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_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 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/ diff --git a/doc/ck_ht_entry_key_length b/doc/ck_ht_entry_key_length new file mode 100644 index 0000000..6ac3ded --- /dev/null +++ b/doc/ck_ht_entry_key_length @@ -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 March 30, 2012 +.Dt CK_HT_ENTRY_KEY_LENGTH 3 +.Sh NAME +.Nm ck_ht_entry_key_length +.Nd returns the length of the key specified in the argument +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft uint16_t +.Fn ck_ht_entry_key_length "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_key_length +function will return the length of the key associated with the +object pointed to by the +.Fa entry +argument. +.Pp +It is expected that the entry is +associated with a hash table initialized with +.Dv CK_HT_MODE_BYTESTRING +(see +.Xr ck_ht_init 3 +for more information). +.Sh RETURN VALUES +.Fn ck_ht_entry_key_length +returns +.Dv 0 +if the entry is empty. +.Sh ERRORS +Behavior is undefined if +.Fa entry +has not been initialized. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 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_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/ diff --git a/doc/ck_ht_entry_key_set b/doc/ck_ht_entry_key_set new file mode 100644 index 0000000..03e53bb --- /dev/null +++ b/doc/ck_ht_entry_key_set @@ -0,0 +1,93 @@ +.\" +.\" 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 March 30, 2012 +.Dt CK_HT_ENTRY_KEY_SET 3 +.Sh NAME +.Nm ck_ht_entry_key_set +.Nd initialize pointer to key in hash table entry +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void +.Fn ck_ht_entry_key_set "ck_ht_entry_t *entry" "const void *key" "uint16_t key_length" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_key_set +function will initialize the object pointed to by +.Fa entry +with a key pointed to by the +.Fa key +argument. The length of the key is specified by +.Fa key_length. +The maximum value of +.Fa key_length +is defined by the CK_HT_KEY_LENGTH macro. +This function is typically used to initialize an +entry for +.Xr ck_ht_get_spmc 3 +and +.Xr ck_ht_remove_spmc 3 +operations. It is expected that the entry will +be associated with a hash table initialized with +.Dv CK_HT_MODE_BYTESTRING +(see +.Xr ck_ht_init 3 +for more information). +.Sh RETURN VALUES +.Fn ck_ht_entry_key_set +has no return value. +.Sh ERRORS +This function will never fail. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 3 , +.Xr ck_ht_entry_empty 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/ diff --git a/doc/ck_ht_entry_key_set_direct b/doc/ck_ht_entry_key_set_direct new file mode 100644 index 0000000..1cd2d6c --- /dev/null +++ b/doc/ck_ht_entry_key_set_direct @@ -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 March 30, 2012 +.Dt CK_HT_ENTRY_KEY_SET_DIRECT 3 +.Sh NAME +.Nm ck_ht_entry_key_set_direct +.Nd initialize key value in hash table entry +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void +.Fn ck_ht_entry_key_set_direct "ck_ht_entry_t *entry" "uintptr_t key" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_key_set_direct +function will initialize the object pointed to by +.Fa entry +with the key value specified in the +.Fa key +argument. This function is typically used to initialize an +entry for +.Xr ck_ht_get_spmc 3 +and +.Xr ck_ht_remove_spmc 3 +operations. It is expected that the entry will +be associated with a hash table initialized with +.Dv CK_HT_MODE_DIRECT +(see +.Xr ck_ht_init 3 +for more information). +.Sh RETURN VALUES +.Fn ck_ht_entry_key_set_direct +has no return value. +.Sh ERRORS +This function will never fail. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 3 , +.Xr ck_ht_entry_empty 3 , +.Xr ck_ht_entry_key_set 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/ diff --git a/doc/ck_ht_entry_set b/doc/ck_ht_entry_set new file mode 100644 index 0000000..b017430 --- /dev/null +++ b/doc/ck_ht_entry_set @@ -0,0 +1,95 @@ +.\" +.\" 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 March 30, 2012 +.Dt CK_HT_ENTRY_SET 3 +.Sh NAME +.Nm ck_ht_entry_set +.Nd initialize a key-value pair +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void +.Fn ck_ht_entry_set "ck_ht_entry_t *entry" "ck_ht_hash_t h" "const void *key" "uint16_t key_length" "const void *value" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_set +function will initialize the object pointed to by +.Fa entry +with a key pointed to by the +.Fa key +argument and a value pointed to by the +.Fa value +argument. The length of the key is specified by +.Fa key_length. +The maximum value of +.Fa key_length +is defined by the CK_HT_KEY_LENGTH macro. +This function is typically used to initialize an +entry for +.Xr ck_ht_set_spmc 3 +and +.Xr ck_ht_put_spmc 3 +operations. It is expected that the entry will +be associated with a hash table initialized with +.Dv CK_HT_MODE_BYTESTRING +(see +.Xr ck_ht_init 3 +for more information). +.Sh RETURN VALUES +.Fn ck_ht_entry_set +has no return value. +.Sh ERRORS +This function will never fail. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 3 , +.Xr ck_ht_entry_empty 3 , +.Xr ck_ht_entry_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_key_set 3 , +.Xr ck_ht_entry_key_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/ diff --git a/doc/ck_ht_entry_set_direct b/doc/ck_ht_entry_set_direct new file mode 100644 index 0000000..9c9bf08 --- /dev/null +++ b/doc/ck_ht_entry_set_direct @@ -0,0 +1,94 @@ +.\" +.\" 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 March 30, 2012 +.Dt CK_HT_ENTRY_SET_DIRECT 3 +.Sh NAME +.Nm ck_ht_entry_set_direct +.Nd initialize a key-value pair +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void +.Fn ck_ht_entry_set_direct "ck_ht_entry_t *entry" "ck_ht_hash_t h" "uintptr_t key" "uintptr_t value" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_set +function will initialize the object pointed to by +.Fa entry +with the hash value specified by the +.Fa h +argument, the key value specified in the +.Fa key +argument and the value specified by the +.Fa value +argument. +.Pp +This function is typically used to initialize an +entry for +.Xr ck_ht_set_spmc 3 +and +.Xr ck_ht_put_spmc 3 +operations. It is expected that the entry will +be associated with a hash table initialized with +.Dv CK_HT_MODE_DIRECT +(see +.Xr ck_ht_init 3 +for more information). +.Sh RETURN VALUES +.Fn ck_ht_entry_set_direct +has no return value. +.Sh ERRORS +This function will never fail. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 3 , +.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 , +.Xr ck_ht_entry_key_set 3 , +.Xr ck_ht_entry_key_set_direct 3 , +.Xr ck_ht_entry_set 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/ diff --git a/doc/ck_ht_entry_value b/doc/ck_ht_entry_value new file mode 100644 index 0000000..2e712e3 --- /dev/null +++ b/doc/ck_ht_entry_value @@ -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 March 30, 2012 +.Dt CK_HT_ENTRY_VALUE 3 +.Sh NAME +.Nm ck_ht_entry_value +.Nd return pointer to value as specified in hash table entry +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void * +.Fn ck_ht_entry_value "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_value +function will return the value pointer as specified in the +object pointed to by the +.Fa entry +argument. +.Pp +It is expected that the entry is +associated with a hash table initialized with +.Dv CK_HT_MODE_BYTESTRING +(see +.Xr ck_ht_init 3 +for more information). +.Sh RETURN VALUES +The +.Fn ck_ht_entry_value +function returns the value pointed to by +.Dv entry. +.Sh ERRORS +Behavior is undefined if +.Fa entry +has not been initialized or if the key is empty. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 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_length 3 , +.Xr ck_ht_entry_key 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/ diff --git a/doc/ck_ht_entry_value_direct b/doc/ck_ht_entry_value_direct new file mode 100644 index 0000000..1a7c28e --- /dev/null +++ b/doc/ck_ht_entry_value_direct @@ -0,0 +1,89 @@ +.\" +.\" 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 March 30, 2012 +.Dt CK_HT_ENTRY_VALUE_DIRECT 3 +.Sh NAME +.Nm ck_ht_entry_value_direct +.Nd return value as specified in hash table entry +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft uintptr_t +.Fn ck_ht_entry_value_direct "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_entry_value_direct +function will return the value of the key-value pair as specified in the +object pointed to by the +.Fa entry +argument. +.Pp +It is expected that the entry is +associated with a hash table initialized with +.Dv CK_HT_MODE_DIRECT +(see +.Xr ck_ht_init 3 +for more information). +.Sh RETURN VALUES +The +.Fn ck_ht_entry_value_direct +function returns the value stored in the object pointed to by the +.Fa entry +argument. +.Sh ERRORS +Behavior is undefined if +.Fa entry +has not been initialized or if the key is empty. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 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_length 3 , +.Xr ck_ht_entry_key 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 3 , +.Xr ck_ht_iterator_init 3 , +.Xr ck_ht_next 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ht_gc b/doc/ck_ht_gc new file mode 100644 index 0000000..8bbad56 --- /dev/null +++ b/doc/ck_ht_gc @@ -0,0 +1,96 @@ +.\" +.\" 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 December 18, 2013 +.Dt CK_HT_GC 3 +.Sh NAME +.Nm ck_ht_gc +.Nd perform maintenance on a hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_gc "ck_ht_t *ht" "unsigned long cycles" "unsigned long seed" +.Sh DESCRIPTION +The +.Fn ck_ht_gc +function will perform various maintenance routines on the hash table +pointed to by +.Fa ht , +including defragmentation of probe sequences with respect to tombstones +and in the case that the delete workload hint has been passed, recalculation +of probe sequence bounds. The +.Fa cycles +argument is used to indicate how many hash table entries should be subject +to attempted maintenance. +If +.Fa cycles +is 0, then maintenance is performed on the complete hash table. The +.Fa seed +argument determines the start location of the maintenance process. If +.Fa cycles +is non-zero, it is recommended that +.Fa seed +is some random value. If the delete hint has been passed, the function +will require an additional 12% of memory (with respect to existing +memory usage of the set), until operation completion. +.Sh RETURN VALUES +Upon successful completion, +.Fn ck_ht_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_ht_count 3 , +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_size_spmc 3 , +.Xr ck_ht_reset_spmc 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/ diff --git a/doc/ck_ht_get_spmc b/doc/ck_ht_get_spmc new file mode 100644 index 0000000..91b9534 --- /dev/null +++ b/doc/ck_ht_get_spmc @@ -0,0 +1,177 @@ +.\" +.\" 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 March 29, 2012 +.Dt CK_HT_GET_SPMC 3 +.Sh NAME +.Nm ck_ht_get_spmc +.Nd load a key-value pair from a hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_get_spmc "ck_ht_t *ht" "ck_ht_hash_t h" "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_get_spmc +function will return the value associated with the key specified in the +.Fa entry +argument in the hash table pointed to by the +.Fa ht +argument. The key specified in +.Fa entry +is expected to have the hash value specified by the +.Fa h +argument. +.Pp +If +.Fa ht +was created with CK_HT_MODE_BYTESTRING then +.Fa entry +must have been initialized with the +.Xr ck_ht_entry_set_key 3 +or +.Xr ck_ht_entry_set 3 +functions. If +.Fa ht +was created with CK_HT_MODE_DIRECT then +.Fa entry +must have been initialized with the +.Xr ck_ht_entry_key_set_direct 3 +or +.Xr ck_ht_entry_set_direct 3 +functions. +.Pp +It is expected that +.Fa h +was initialized with +.Xr ck_ht_hash 3 +if +.Fa ht +was created with CK_HT_MODE_BYTESTRING. If +.Fa ht +was initialized with CK_HT_MODE_DIRECT then it is +expected that +.Fa h +was initialized with the +.Xr ck_ht_hash_direct 3 +function. +.Pp +If the call to +.Fn ck_ht_get_spmc +was successful then the key-value pair in +.Fa entry +was successfully found in the hash table pointed +to by +.Fa h +and will fail if the key specified in +.Fa entry +does not exist in the hash table. If successful +.Fa entry +will contain the key-value pair found in the hash table +pointed to by the +.Fa ht +argument. +.Pp +If +.Fa ht +was initialized with CK_HT_MODE_BYTESTRING then +the key/value pair in +.Fa entry +may be extracted using the +.Xr ck_ht_entry_key 3 +and +.Xr ck_ht_entry_value 3 +functions. The length of the key may be extracted +using the +.Xr ck_ht_entry_key_length 3 +function. +.Pp +If +.Fa ht +was initialized with CK_HT_MODE_DIRECT then the +key/value pair in +.Fa entry +may be extracted using the +.Xr ck_ht_entry_key_direct 3 +and +.Xr ck_ht_entry_value_direct 3 +functions. +.Pp +This function is safe to call in the presence of a concurrent writer. +.Sh RETURN VALUES +Upon successful completion +.Fn ck_ht_get_spmc +returns +.Dv true. +If successful, +.Fa entry +will contain the key/value pair as found +in the hash table. +Otherwise the function returns +.Dv false +on failure. +.Sh ERRORS +.Bl -tag -width Er +Behavior is undefined if +.Fa entry +or +.Fa ht +are uninitialized. The function will return +.Dv false +if the key as specified in +.Fa entry +was not found in the hash table. +.El +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_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/ diff --git a/doc/ck_ht_grow_spmc b/doc/ck_ht_grow_spmc new file mode 100644 index 0000000..70e6055 --- /dev/null +++ b/doc/ck_ht_grow_spmc @@ -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 March 29, 2012 +.Dt CK_HT_GROW_SPMC 3 +.Sh NAME +.Nm ck_ht_grow_spmc +.Nd resize a hash table if necessary +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_grow_spmc "ck_ht_t *ht" "uint64_t capacity" +.Sh DESCRIPTION +The +.Fn ck_ht_grow_spmc +function will resize the hash table in order to be able to +at least store the number of entries specified by +.Fa capacity +at a load factor of one. The default load hash table load factor is +0.5. If you wish to minimize the likelihood of memory allocations +for a hash table meant to store n entries then specify a capacity +of 2n. The default behavior of ck_ht is to round +.Fa capacity +to the next available power of two if it is not already a power +of two. +.Pp +This function is safe to call in the presence of concurrent +.Xr ck_ht_get_spmc 3 +operations. +.Sh RETURN VALUES +Upon successful completion +.Fn ck_ht_grow_spmc +returns +.Dv true +and otherwise returns a +.Dv false +value. +.Sh ERRORS +.Bl -tag -width Er +Behavior is undefined if +.Fa ht +is uninitialized. The function will only return +.Dv false +if there are internal memory allocation failures. +.El +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_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/ diff --git a/doc/ck_ht_hash b/doc/ck_ht_hash new file mode 100644 index 0000000..0ac5db9 --- /dev/null +++ b/doc/ck_ht_hash @@ -0,0 +1,90 @@ +.\" +.\" 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 March 29, 2012 +.Dt CK_HT_HASH 3 +.Sh NAME +.Nm ck_ht_hash +.Nd generate a hash value for a hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void +.Fn ck_ht_hash "ck_ht_hash_t *h" "ck_ht_t *ht" "const void *key" "uint16_t key_length" +.Sh DESCRIPTION +The +.Fn ck_ht_hash +function will generate a hash value in the object pointed to by the +.Fa h +argument. The hash value is valid for use in the hash table pointed to by the +.Fa ht +argument for the key (of bytestring type) specified by the +.Fa key +argument. The length of the key is specified by the +.Fa key_length +argument. +.Sh RETURN VALUES +.Fn ck_ht_hash +has no return value. +.Sh ERRORS +.Bl -tag -width Er +Behavior is undefined if +.Fa key +is +.Dv NULL +or if +.Fa ht +is uninitialized. +.El +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 3 , +.Xr ck_ht_destroy 3 , +.Xr ck_ht_hash_direct 3 , +.Xr ck_ht_set_spmc 3 , +.Xr ck_ht_put_spmc 3 , +.Xr ck_ht_gc 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_reset_size_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/ diff --git a/doc/ck_ht_hash_direct b/doc/ck_ht_hash_direct new file mode 100644 index 0000000..564099c --- /dev/null +++ b/doc/ck_ht_hash_direct @@ -0,0 +1,90 @@ +.\" +.\" 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 March 29, 2012 +.Dt CK_HT_HASH_DIRECT 3 +.Sh NAME +.Nm ck_ht_hash_direct +.Nd generate a hash value for a hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void +.Fn ck_ht_hash_direct "ck_ht_hash_t *h" "ck_ht_t *ht" "uintptr_t key" +.Sh DESCRIPTION +The +.Fn ck_ht_hash_direct +function will generate a hash value in the object pointed to by the +.Fa h +argument. The hash value is valid for use in the hash table pointed to by the +.Fa ht +argument for the key (of direct type) specified by the +.Fa key +argument. +.Sh RETURN VALUES +.Fn ck_ht_hash_direct +has no return value. +.Sh ERRORS +.Bl -tag -width Er +Behavior is undefined if +.Fa key +is a +.Dv 0 +or +.Dv UINTPTR_MAX +value or if +.Fa ht +is uninitialized. +.El +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 3 , +.Xr ck_ht_destroy 3 , +.Xr ck_ht_hash 3 , +.Xr ck_ht_set_spmc 3 , +.Xr ck_ht_put_spmc 3 , +.Xr ck_ht_gc 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_reset_size_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/ diff --git a/doc/ck_ht_init b/doc/ck_ht_init new file mode 100644 index 0000000..757a39a --- /dev/null +++ b/doc/ck_ht_init @@ -0,0 +1,188 @@ +.\" +.\" 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 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 typedef void +.Fn ck_ht_hash_cb_t "ck_ht_hash_t *h" "const void *key" "size_t key_length" "uint64_t seed" +.Ft bool +.Fn 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" +.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. Attempting a hash table operation with a key of value +NULL or (void *)UINTPTR_MAX will result in undefined behavior. +.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. Entries of this hash table are expected to be interacted +with using the +.Xr ck_ht_entry_empty 3 , +.Xr ck_ht_entry_key_direct 3 , +.Xr ck_ht_entry_value_direct 3 +and +.Xr ck_ht_entry_set_direct 3 +functions. Attempting a hash table operation with a key of value of 0 or +UINTPTR_MAX will result in undefined behavior. +.El +.Pp +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 argument +.Fa hash_function +is a pointer to a user-specified hash function. It is optional, +if +.Dv NULL +is specified, then the default hash function implementation will be +used ( +.Xr ck_ht_hash 3 ). +A user-specified hash function takes four arguments. The +.Fa h +argument is a pointer to a hash value object. The hash function +is expected to update the +.Fa value +object of type +.Fa uint64_t +contained with-in the object pointed to by +.Fa h . +The +.Fa key +argument is a pointer to a key, the +.Fa key_length +argument is the length of the key and the +.Fa seed +argument is the initial seed associated with the hash table. +This initial seed is specified by the user in +.Xr ck_ht_init 3 . +.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 table being initialized. +.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. +.El +.Sh SEE ALSO +.Xr ck_ht_stat 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_gc 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_reset_size_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/ diff --git a/doc/ck_ht_iterator_init b/doc/ck_ht_iterator_init new file mode 100644 index 0000000..14f10c6 --- /dev/null +++ b/doc/ck_ht_iterator_init @@ -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 March 30, 2012 +.Dt CK_HT_ITERATOR_INIT 3 +.Sh NAME +.Nm ck_ht_iterator_init +.Nd initialize hash table iterator +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Pp +.Dv ck_ht_iterator_t iterator = CK_HT_ITERATOR_INITIALIZER +.Pp +.Ft void +.Fn ck_ht_iterator_init "ck_ht_iterator_t *iterator" +.Sh DESCRIPTION +The +.Fn ck_ht_iterator_init +function will initialize the object pointed to by +the +.Fa iterator +argument. Alternatively, an iterator may be statically initialized +by assigning it the +.Dv CK_HT_ITERATOR_INITIALIZER +value. +.Pp +An iterator is used to iterate through hash table entries +with the +.Xr ck_ht_next 3 +function. +.Sh RETURN VALUES +The +.Fn ck_ht_iterator_init +function does not return a value. +.Sh ERRORS +This function will not fail. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_size_spmc 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_length 3 , +.Xr ck_ht_entry_key 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 3 , +.Xr ck_ht_entry_value_direct 3 , +.Xr ck_ht_next 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ht_next b/doc/ck_ht_next new file mode 100644 index 0000000..d0365a1 --- /dev/null +++ b/doc/ck_ht_next @@ -0,0 +1,107 @@ +.\" +.\" 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 March 30, 2012 +.Dt CK_HT_NEXT 3 +.Sh NAME +.Nm ck_ht_next +.Nd iterate to next entry in hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_next "ck_ht_t *ht" "ck_ht_iterator_t *iterator" "ck_ht_entry_t **entry" +.Sh DESCRIPTION +The +.Fn ck_ht_next +function will increment the iterator object pointed to by +.Fa iterator +to point to the next non-empty hash table entry. If +.Fn ck_ht_next +returns +.Dv true +then the pointer pointed to by +.Fa entry +is initialized to the current hash table entry pointed to by +the +.Fa iterator +object. +.Pp +It is expected that +.Fa iterator +has been initialized using the +.Xr ck_ht_iterator_init 3 +function or statically initialized using +.Dv CK_HT_ITERATOR_INITIALIZER. +.Sh RETURN VALUES +If +.Fn ck_ht_next +returns +.Dv true +then the object pointed to by +.Fa entry +points to a valid hash table entry. If +.Fn ck_ht_next +returns +.Dv false +then value of the object pointed to by +.Fa entry +is undefined. +.Sh ERRORS +Behavior is undefined if +.Fa iterator +or +.Fa ht +are uninitialized. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_count 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_spmc 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_length 3 , +.Xr ck_ht_entry_key 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 3 , +.Xr ck_ht_entry_value_direct 3 , +.Xr ck_ht_iterator_init 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ht_put_spmc b/doc/ck_ht_put_spmc new file mode 100644 index 0000000..f5a6389 --- /dev/null +++ b/doc/ck_ht_put_spmc @@ -0,0 +1,146 @@ +.\" +.\" 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 March 29, 2012 +.Dt CK_HT_PUT_SPMC 3 +.Sh NAME +.Nm ck_ht_put_spmc +.Nd store unique key-value pair into hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_put_spmc "ck_ht_t *ht" "ck_ht_hash_t h" "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_put_spmc +function will store the key-value pair specified in the +.Fa entry +argument in the hash table pointed to by the +.Fa ht +argument. The key specified in +.Fa entry +is expected to have the hash value specified by the +.Fa h +argument. +.Pp +If +.Fa ht +was created with CK_HT_MODE_BYTESTRING then +.Fa entry +must have been initialized with the +.Xr ck_ht_entry_set 3 +function. If +.Fa ht +was created with CK_HT_MODE_DIRECT then +.Fa entry +must have been initialized with the +.Xr ck_ht_entry_set_direct 3 +function. +.Pp +It is expected that +.Fa h +was initialized with +.Xr ck_ht_hash 3 +if +.Fa ht +was created with CK_HT_MODE_BYTESTRING. If +.Fa ht +was initialized with CK_HT_MODE_DIRECT then it is +expected that +.Fa h +was initialized with the +.Xr ck_ht_hash_direct 3 +function. +.Pp +If the call to +.Fn ck_ht_put_spmc +was successful then the key-value pair in +.Fa entry +was successfully stored in the hash table pointed +to by +.Fa ht +and will fail if the key specified in +.Fa entry +already exists with-in the hash table. Replacement semantics +are provided by the +.Xr ck_ht_set_spmc 3 +function. +.Pp +This function is safe to call in the presence of concurrent +.Xr ck_ht_get_spmc 3 +operations. +.Sh RETURN VALUES +Upon successful completion +.Fn ck_ht_put_spmc +returns +.Dv true +and otherwise returns +.Dv false +on failure. +.Sh ERRORS +.Bl -tag -width Er +Behavior is undefined if +.Fa entry +or +.Fa ht +are uninitialized. The function will return +.Dv false +if the hash table required to be grown but failed +while attempting to grow or if the key specified +in +.Fa entry +was already present in the hash table. +.El +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 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_reset_size_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/ diff --git a/doc/ck_ht_remove_spmc b/doc/ck_ht_remove_spmc new file mode 100644 index 0000000..a263866 --- /dev/null +++ b/doc/ck_ht_remove_spmc @@ -0,0 +1,117 @@ +.\" +.\" 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 March 29, 2012 +.Dt CK_HT_GROW_SPMC 3 +.Sh NAME +.Nm ck_ht_remove_spmc +.Nd resize a hash table if necessary +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_remove_spmc "ck_ht_t *ht" "ck_ht_hash_t h" "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_remove_spmc +function will remove the key-value pair associated with the +key specified by the +.Fa entry +argument. +.Pp +If +.Fa ht +was created with CK_HT_MODE_BYTESTRING then +.Fa entry +must have been initialized with the +.Xr ck_ht_entry_set_key 3 +or +.Xr ck_ht_entry_set 3 +functions. If +.Fa ht +was created with CK_HT_MODE_DIRECT then +.Fa entry +must have been initialized with the +.Xr ck_ht_entry_key_set_direct 3 +or +.Xr ck_ht_entry_set_direct 3 +functions. +.Pp +It is expected that +.Fa h +was initialized with +.Xr ck_ht_hash 3 +if +.Fa ht +was created with CK_HT_MODE_BYTESTRING. If +.Fa ht +was initialized with CK_HT_MODE_DIRECT then it is +expected that +.Fa h +was initialized with the +.Xr ck_ht_hash_direct 3 +function. +.Sh RETURN VALUES +If successful, +.Fa entry +will contain the key-value pair that was found in the hash table +and +.Fn ck_ht_remove_spmc +will return +.Dv true. +If the entry could not be found then +.Fn ck_ht_remove_spmc +will return +.Dv false. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_reset_spmc 3 , +.Xr ck_ht_reset_size_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/ diff --git a/doc/ck_ht_reset_size_spmc b/doc/ck_ht_reset_size_spmc new file mode 100644 index 0000000..4308380 --- /dev/null +++ b/doc/ck_ht_reset_size_spmc @@ -0,0 +1,84 @@ +.\" +.\" 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_HT_RESET_SPMC 3 +.Sh NAME +.Nm ck_ht_reset_size_spmc +.Nd remove all entries from a hash table and reset size +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_reset_size_spmc "ck_ht_t *ht" "uint64_t capacity" +.Sh DESCRIPTION +The +.Fn ck_ht_reset_size_spmc +function will remove all key-value pairs stored in the hash +table pointed to by the +.Fa ht +argument and create a new generation of the hash table that +is preallocated for +.Fa capacity +entries. +.Sh RETURN VALUES +If successful, +.Fn ck_ht_reset_size_spmc +will return +.Dv true +and will otherwise return +.Dv false. +This function will only fail if a replacement hash table +could not be allocated internally. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_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_reset_spmc 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/ diff --git a/doc/ck_ht_reset_spmc b/doc/ck_ht_reset_spmc new file mode 100644 index 0000000..dc2e601 --- /dev/null +++ b/doc/ck_ht_reset_spmc @@ -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 March 29, 2012 +.Dt CK_HT_RESET_SPMC 3 +.Sh NAME +.Nm ck_ht_reset_spmc +.Nd remove all entries from a hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_reset_spmc "ck_ht_t *ht" +.Sh DESCRIPTION +The +.Fn ck_ht_reset_spmc +function will remove all key-value pairs stored in the hash +table pointed to by the +.Fa ht +argument. +.Sh RETURN VALUES +If successful, +.Fn ck_ht_reset_spmc +will return +.Dv true +and will otherwise return +.Dv false. +This function will only fail if a replacement hash table +could not be allocated internally. +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 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_gc 3 , +.Xr ck_ht_get_spmc 3 , +.Xr ck_ht_grow_spmc 3 , +.Xr ck_ht_remove_spmc 3 , +.Xr ck_ht_reset_size_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/ diff --git a/doc/ck_ht_set_spmc b/doc/ck_ht_set_spmc new file mode 100644 index 0000000..e0fe1ae --- /dev/null +++ b/doc/ck_ht_set_spmc @@ -0,0 +1,140 @@ +.\" +.\" 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 March 29, 2012 +.Dt CK_HT_SET_SPMC 3 +.Sh NAME +.Nm ck_ht_set_spmc +.Nd store key-value pair into hash table +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft bool +.Fn ck_ht_set_spmc "ck_ht_t *ht" "ck_ht_hash_t h" "ck_ht_entry_t *entry" +.Sh DESCRIPTION +The +.Fn ck_ht_set_spmc +function will store the key-value pair specified in the +.Fa entry +argument in the hash table pointed to by the +.Fa ht +argument. The key specified in +.Fa entry +is expected to have the hash value specified by the +.Fa h +argument. +.Pp +If +.Fa ht +was created with CK_HT_MODE_BYTESTRING then +.Fa entry +must have been initialized with the +.Xr ck_ht_entry_set 3 +function. If +.Fa ht +was created with CK_HT_MODE_DIRECT then +.Fa entry +must have been initialized with the +.Xr ck_ht_entry_set_direct 3 +function. +.Pp +It is expected that +.Fa h +was initialized with +.Xr ck_ht_hash 3 +if +.Fa ht +was created with CK_HT_MODE_BYTESTRING. If +.Fa ht +was initialized with CK_HT_MODE_DIRECT then it is +expected that +.Fa h +was initialized with the +.Xr ck_ht_hash_direct 3 +function. +.Pp +If the call to +.Fn ck_ht_set_spmc +was successful then the key-value pair in +.Fa entry +will contain the previous key-value pair associated +with the key originally contained in the +.Fa entry +argument. If the operation was unsuccessful then +.Fa entry +is unmodified. +.Pp +This function is safe to call in the presence of concurrent +.Xr ck_ht_get_spmc +operations. +.Sh RETURN VALUES +Upon successful completion +.Fn ck_ht_set_spmc +returns +.Dv true +and otherwise returns +.Dv false +on failure. +.Sh ERRORS +.Bl -tag -width Er +Behavior is undefined if +.Fa entry +or +.Fa ht +are uninitialized. The function will return +.Dv false +if the hash table required to be grown but failed +while attempting to grow. +.El +.Sh SEE ALSO +.Xr ck_ht_stat 3 , +.Xr ck_ht_init 3 , +.Xr ck_ht_destroy 3 , +.Xr ck_ht_hash 3 , +.Xr ck_ht_hash_direct 3 , +.Xr ck_ht_put_spmc 3 , +.Xr ck_ht_gc 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_reset_size_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/ diff --git a/doc/ck_ht_stat b/doc/ck_ht_stat new file mode 100644 index 0000000..6d2f1cd --- /dev/null +++ b/doc/ck_ht_stat @@ -0,0 +1,85 @@ +.\" +.\" 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_HT_STAT 3 +.Sh NAME +.Nm ck_ht_stat +.Nd get hash table status +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ht.h +.Ft void +.Fn ck_ht_stat "ck_ht_t *ht" "struct ck_ht_stat *st" +.Sh DESCRIPTION +The +.Fn ck_ht_stat 3 +function will store various hash set statistics in the object +pointed to by +.Fa st . +The ck_ht_stat structure is defined as follows: +.Bd -literal -offset indent +struct ck_ht_stat { + uint64_t probe_maximum; /* Longest read-side probe sequence. */ + uint64_t n_entries; /* Current number of keys in hash set. */ +}; +.Ed +.Sh RETURN VALUES +.Fn ck_ht_stat 3 +has no return value. +.Sh ERRORS +Behavior is undefined if +.Fa ht +has not been initialized. +.Sh SEE ALSO +.Xr ck_ht_count 3 , +.Xr ck_ht_init 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_gc 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_reset_size_spmc 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/ diff --git a/doc/ck_pflock b/doc/ck_pflock new file mode 100644 index 0000000..6fea701 --- /dev/null +++ b/doc/ck_pflock @@ -0,0 +1,95 @@ +.\" +.\" Copyright 2014 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 April 22, 2014. +.Dt ck_pflock 3 +.Sh NAME +.Nm ck_pflock_init , +.Nm ck_pflock_write_lock , +.Nm ck_pflock_write_unlock , +.Nm ck_pflock_read_lock , +.Nm ck_pflock_read_unlock , +.Nd centralized phase-fair reader-writer locks +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pflock.h +.Pp +.Dv ck_pflock_t lock = CK_PFLOCK_INITIALIZER; +.Pp +.Ft void +.Fn ck_pflock_init "ck_pflock_t *lock" +.Ft void +.Fn ck_pflock_write_lock "ck_pflock_t *lock" +.Ft void +.Fn ck_pflock_write_unlock "ck_pflock_t *lock" +.Ft void +.Fn ck_pflock_read_lock "ck_pflock_t *lock" +.Ft void +.Fn ck_pflock_read_unlock "ck_pflock_t *lock" +.Sh DESCRIPTION +This is a centralized phase-fair reader-writer lock. It +requires little space overhead and has a low latency +fast path. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_pflock.h> + +static ck_pflock_t lock = CK_TFLOCK_INITIALIZER; + +static void +reader(void) +{ + + for (;;) { + ck_pflock_read_lock(&lock); + /* Read-side critical section. */ + ck_pflock_read_unlock(&lock); + } + + return; +} + +static void +writer(void) +{ + + for (;;) { + ck_pflock_write_lock(&lock); + /* Write-side critical section. */ + ck_pflock_write_unlock(&lock); + } + + return; +} +.Ed +.Sh SEE ALSO +.Xr ck_brlock 3 , +.Xr ck_rwlock 3 , +.Xr ck_tflock 3 , +.Xr ck_swlock 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr b/doc/ck_pr new file mode 100644 index 0000000..67c726f --- /dev/null +++ b/doc/ck_pr @@ -0,0 +1,71 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr 3 +.Sh NAME +.Nm ck_pr +.Nd concurrency primitives interface +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Sh DESCRIPTION +ck_pr.h provides an interface to volatile atomic instructions, +memory barriers and busy-wait facilities as provided by the +underlying processor. The presence of an atomic operation +is detected by the presence of a corresponding CK_F_PR macro. +For example, the availability of +.Xr ck_pr_add_16 3 +would be determined by the presence of CK_F_PR_ADD_16. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_acquire 3 , +.Xr ck_pr_fence_release 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_add b/doc/ck_pr_add new file mode 100644 index 0000000..b4d394a --- /dev/null +++ b/doc/ck_pr_add @@ -0,0 +1,93 @@ +.\" +.\" 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 April 11, 2013 +.Dt ck_pr_add 3 +.Sh NAME +.Nm ck_pr_add_ptr , +.Nm ck_pr_add_double , +.Nm ck_pr_add_char , +.Nm ck_pr_add_uint , +.Nm ck_pr_add_int , +.Nm ck_pr_add_64 , +.Nm ck_pr_add_32 , +.Nm ck_pr_add_16 , +.Nm ck_pr_add_8 +.Nd atomic addition operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_add_ptr "void *target" "uintptr_t delta" +.Ft void +.Fn ck_pr_add_double "double *target" "double delta" +.Ft void +.Fn ck_pr_add_char "char *target" "char delta" +.Ft void +.Fn ck_pr_add_uint "unsigned int *target" "unsigned int delta" +.Ft void +.Fn ck_pr_add_int "int *target" "int delta" +.Ft void +.Fn ck_pr_add_64 "uint64_t *target" "uint64_t delta" +.Ft void +.Fn ck_pr_add_32 "uint32_t *target" "uint32_t delta" +.Ft void +.Fn ck_pr_add_16 "uint16_t *target" "uint16_t delta" +.Ft void +.Fn ck_pr_add_8 "uint8_t *target" "uint8_t delta" +.Sh DESCRIPTION +The +.Fn ck_pr_add 3 +family of functions atomically add the value specified by +.Fa delta +to the value pointed to by +.Fa target . +.Sh RETURN VALUES +This family of functions does not have a return value. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_and b/doc/ck_pr_and new file mode 100644 index 0000000..56ce5af --- /dev/null +++ b/doc/ck_pr_and @@ -0,0 +1,93 @@ +.\" +.\" 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 April 11, 2013 +.Dt ck_pr_and 3 +.Sh NAME +.Nm ck_pr_and_ptr , +.Nm ck_pr_and_char , +.Nm ck_pr_and_uint , +.Nm ck_pr_and_int , +.Nm ck_pr_and_64 , +.Nm ck_pr_and_32 , +.Nm ck_pr_and_16 , +.Nm ck_pr_and_8 +.Nd atomic bitwise-and operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_and_ptr "void *target" "uintptr_t delta" +.Ft void +.Fn ck_pr_and_char "char *target" "char delta" +.Ft void +.Fn ck_pr_and_uint "unsigned int *target" "unsigned int delta" +.Ft void +.Fn ck_pr_and_int "int *target" "int delta" +.Ft void +.Fn ck_pr_and_64 "uint64_t *target" "uint64_t delta" +.Ft void +.Fn ck_pr_and_32 "uint32_t *target" "uint32_t delta" +.Ft void +.Fn ck_pr_and_16 "uint16_t *target" "uint16_t delta" +.Ft void +.Fn ck_pr_and_8 "uint8_t *target" "uint8_t delta" +.Sh DESCRIPTION +The +.Fn ck_pr_and 3 +family of functions atomically compute and store the +result of a bitwise-and of the value pointed to by +.Fa target +and +.Fa delta +into the value pointed to by +.Fa target . +.Sh RETURN VALUES +This family of functions does not have a return value. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_barrier b/doc/ck_pr_barrier new file mode 100644 index 0000000..3886729 --- /dev/null +++ b/doc/ck_pr_barrier @@ -0,0 +1,66 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_barrier 3 +.Sh NAME +.Nm ck_pr_barrier +.Nd compiler optimization barrier +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_barrier void +.Sh DESCRIPTION +The +.Fn ck_pr_barrier 3 +function is used to disable code movement optimizations +across the invocation of the function. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_btc b/doc/ck_pr_btc new file mode 100644 index 0000000..5956221 --- /dev/null +++ b/doc/ck_pr_btc @@ -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 April 11, 2013 +.Dt ck_pr_btc 3 +.Sh NAME +.Nm ck_pr_btc_ptr , +.Nm ck_pr_btc_uint , +.Nm ck_pr_btc_int , +.Nm ck_pr_btc_64 , +.Nm ck_pr_btc_32 , +.Nm ck_pr_btc_16 +.Nd atomic bit test-and-complement operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft bool +.Fn ck_pr_btc_ptr "void *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btc_uint "uint *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btc_int "int *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btc_64 "uint64_t *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btc_32 "uint32_t *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btc_16 "uint16_t *target" "unsigned int bit_index" +.Sh DESCRIPTION +The +.Fn ck_pr_btc 3 +family of functions atomically fetch the value +of the bit in +.Fa target +at index +.Fa bit_index +and set that bit to its complement. +.Sh RETURN VALUES +These family of functions return the original value of +the bit at offset +.Fa bit_index +that is in the value pointed to by +.Fa target . +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_btr 3 , +.Xr ck_pr_cas 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_btr b/doc/ck_pr_btr new file mode 100644 index 0000000..d5e03fd --- /dev/null +++ b/doc/ck_pr_btr @@ -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 April 11, 2013 +.Dt ck_pr_btr 3 +.Sh NAME +.Nm ck_pr_btr_ptr , +.Nm ck_pr_btr_uint , +.Nm ck_pr_btr_int , +.Nm ck_pr_btr_64 , +.Nm ck_pr_btr_32 , +.Nm ck_pr_btr_16 +.Nd atomic bit test-and-reset operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft bool +.Fn ck_pr_btr_ptr "void *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btr_uint "uint *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btr_int "int *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btr_64 "uint64_t *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btr_32 "uint32_t *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_btr_16 "uint16_t *target" "unsigned int bit_index" +.Sh DESCRIPTION +The +.Fn ck_pr_btr 3 +family of functions atomically fetch the value +of the bit in +.Fa target +at index +.Fa bit_index +and set that bit to 0. +.Sh RETURN VALUES +This family of functions returns the original value of +the bit at offset +.Fa bit_index +that is in the value pointed to by +.Fa target . +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_cas 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_bts b/doc/ck_pr_bts new file mode 100644 index 0000000..955855d --- /dev/null +++ b/doc/ck_pr_bts @@ -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 April 11, 2013 +.Dt ck_pr_bts 3 +.Sh NAME +.Nm ck_pr_bts_ptr , +.Nm ck_pr_bts_uint , +.Nm ck_pr_bts_int , +.Nm ck_pr_bts_64 , +.Nm ck_pr_bts_32 , +.Nm ck_pr_bts_16 +.Nd atomic bit test-and-set operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft bool +.Fn ck_pr_bts_ptr "void *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_bts_uint "uint *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_bts_int "int *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_bts_64 "uint64_t *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_bts_32 "uint32_t *target" "unsigned int bit_index" +.Ft bool +.Fn ck_pr_bts_16 "uint16_t *target" "unsigned int bit_index" +.Sh DESCRIPTION +The +.Fn ck_pr_bts 3 +family of functions atomically fetch the value +of the bit in +.Fa target +at index +.Fa bit_index +and set that bit to 1. +.Sh RETURN VALUES +This family of functions returns the original value of +the bit at offset +.Fa bit_index +that is in the value pointed to by +.Fa target . +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_btr 3 , +.Xr ck_pr_cas 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_cas b/doc/ck_pr_cas new file mode 100644 index 0000000..9d1d39b --- /dev/null +++ b/doc/ck_pr_cas @@ -0,0 +1,147 @@ +.\" +.\" 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 April 11, 2013 +.Dt ck_pr_cas 3 +.Sh NAME +.Nm ck_pr_cas_ptr , +.Nm ck_pr_cas_ptr_value , +.Nm ck_pr_cas_ptr_2 , +.Nm ck_pr_cas_ptr_2_value , +.Nm ck_pr_cas_double , +.Nm ck_pr_cas_double_value , +.Nm ck_pr_cas_char , +.Nm ck_pr_cas_char_value , +.Nm ck_pr_cas_uint , +.Nm ck_pr_cas_uint_value , +.Nm ck_pr_cas_int , +.Nm ck_pr_cas_int_value , +.Nm ck_pr_cas_64_2 , +.Nm ck_pr_cas_64_2_value , +.Nm ck_pr_cas_64 , +.Nm ck_pr_cas_64_value , +.Nm ck_pr_cas_32 , +.Nm ck_pr_cas_32_value , +.Nm ck_pr_cas_16 , +.Nm ck_pr_cas_16_value , +.Nm ck_pr_cas_8 , +.Nm ck_pr_cas_8_value +.Nd atomic compare-and-swap operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft bool +.Fn ck_pr_cas_ptr "void *target" "void *old_value" "void *new_value" +.Ft bool +.Fn ck_pr_cas_ptr_value "void *target" "void *old_value" "void *new_value" "void *original_value" +.Ft bool +.Fn ck_pr_cas_ptr_2 "void *target" "void *old_value" "void *new_value" +.Ft bool +.Fn ck_pr_cas_ptr_2_value "void *target" "void *old_value" "void *new_value" "void *original_value" +.Ft bool +.Fn ck_pr_cas_double "double *target" "double old_value" "double new_value" +.Ft bool +.Fn ck_pr_cas_double_value "double *target" "double old_value" "double new_value" "double *original_value" +.Ft bool +.Fn ck_pr_cas_char "char *target" "char old_value" "char new_value" +.Ft bool +.Fn ck_pr_cas_char_value "char *target" "char old_value" "char new_value" "char *original_value" +.Ft bool +.Fn ck_pr_cas_uint "unsigned int *target" "unsigned int old_value" "unsigned int new_value" +.Ft bool +.Fn ck_pr_cas_uint_value "unsigned int *target" "unsigned int old_value" "unsigned int new_value" "unsigned int *original_value" +.Ft bool +.Fn ck_pr_cas_int "int *target" "int old_value" "int new_value" +.Ft bool +.Fn ck_pr_cas_int_value "int *target" "int old_value" "int new_value" "int *original_value" +.Ft bool +.Fn ck_pr_cas_64_2 "uint64_t target[static 2]" "uint64_t old_value[static 2]" "uint64_t new_value[static 2]" +.Ft bool +.Fn ck_pr_cas_64_2_value "uint64_t target[static 2]" "uint64_t old_value[static 2]" "uint64_t new_value[static 2]" "uint64_t original_value[static 2]" +.Ft bool +.Fn ck_pr_cas_64 "uint64_t *target" "uint64_t old_value" "uint64_t new_value" +.Ft bool +.Fn ck_pr_cas_64_value "uint64_t *target" "uint64_t old_value" "uint64_t new_value" "uint64_t *original_value" +.Ft bool +.Fn ck_pr_cas_32 "uint32_t *target" "uint32_t old_value" "uint32_t new_value" +.Ft bool +.Fn ck_pr_cas_32_value "uint32_t *target" "uint32_t old_value" "uint32_t new_value" "uint32_t *original_value" +.Ft bool +.Fn ck_pr_cas_16 "uint16_t *target" "uint16_t old_value" "uint16_t new_value" +.Ft bool +.Fn ck_pr_cas_16_value "uint16_t *target" "uint16_t old_value" "uint16_t new_value" "uint16_t *original_value" +.Ft bool +.Fn ck_pr_cas_8 "uint8_t *target" "uint8_t old_value" "uint8_t new_value" +.Ft bool +.Fn ck_pr_cas_8_value "uint8_t *target" "uint8_t old_value" "uint8_t new_value" "uint8_t *original_value" +.Sh DESCRIPTION +The +.Fn ck_pr_cas 3 +family of functions atomically compare the value in +.Fa target +for equality with +.Fa old_value +and if so, replace the value pointed to by +.Fa target +with the value specified by +.Fa new_value . +If the value in +.Fa target +was not equal to the value specified by +.Fa old_value +then no modifications occur to the value in +.Fa target . +The *_value form of these functions unconditionally update +.Fa original_value . +.Sh RETURN VALUES +This family of functions return true if the value in +.Fa target +was modified as a result of the operation. Otherwise, they +return false. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_dec b/doc/ck_pr_dec new file mode 100644 index 0000000..f3d34dd --- /dev/null +++ b/doc/ck_pr_dec @@ -0,0 +1,124 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_dec 3 +.Sh NAME +.Nm ck_pr_dec_ptr , +.Nm ck_pr_dec_ptr_zero , +.Nm ck_pr_dec_double , +.Nm ck_pr_dec_double_zero , +.Nm ck_pr_dec_char , +.Nm ck_pr_dec_char_zero , +.Nm ck_pr_dec_uint , +.Nm ck_pr_dec_uint_zero , +.Nm ck_pr_dec_int , +.Nm ck_pr_dec_int_zero , +.Nm ck_pr_dec_64 , +.Nm ck_pr_dec_64_zero , +.Nm ck_pr_dec_32 , +.Nm ck_pr_dec_32_zero , +.Nm ck_pr_dec_16 , +.Nm ck_pr_dec_16_zero , +.Nm ck_pr_dec_8 , +.Nm ck_pr_dec_8_zero +.Nd atomic decrement operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_dec_ptr "void *target" +.Ft void +.Fn ck_pr_dec_ptr_zero "void *target" "bool *z" +.Ft void +.Fn ck_pr_dec_double "double *target" +.Ft void +.Fn ck_pr_dec_double_zero "double *target" "bool *z" +.Ft void +.Fn ck_pr_dec_char "char *target" +.Ft void +.Fn ck_pr_dec_char_zero "char *target" "bool *z" +.Ft void +.Fn ck_pr_dec_uint "unsigned int *target" +.Ft void +.Fn ck_pr_dec_uint_zero "unsigned int *target" "bool *z" +.Ft void +.Fn ck_pr_dec_int "int *target" +.Ft void +.Fn ck_pr_dec_int_zero "int *target" "bool *z" +.Ft void +.Fn ck_pr_dec_64 "uint64_t *target" +.Ft void +.Fn ck_pr_dec_64_zero "uint64_t *target" "bool *z" +.Ft void +.Fn ck_pr_dec_32 "uint32_t *target" +.Ft void +.Fn ck_pr_dec_32_zero "uint32_t *target" "bool *z" +.Ft void +.Fn ck_pr_dec_16 "uint16_t *target" +.Ft void +.Fn ck_pr_dec_16_zero "uint16_t *target" "bool *z" +.Ft void +.Fn ck_pr_dec_8 "uint8_t *target" +.Ft void +.Fn ck_pr_dec_8_zero "uint8_t *target" "bool *z" +.Sh DESCRIPTION +The +.Fn ck_pr_dec 3 +family of functions atomically decrement the value pointed to +by +.Fa target . +.Sh RETURN VALUES +The ck_pr_dec_zero family of functions set the value pointed to by +.Fa z +to true if the result +of the decrement operation was 0. They set the value pointed to by +.Fa z +to false otherwise. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_faa b/doc/ck_pr_faa new file mode 100644 index 0000000..fbeff01 --- /dev/null +++ b/doc/ck_pr_faa @@ -0,0 +1,99 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_faa 3 +.Sh NAME +.Nm ck_pr_faa_ptr , +.Nm ck_pr_faa_double , +.Nm ck_pr_faa_char , +.Nm ck_pr_faa_uint , +.Nm ck_pr_faa_int , +.Nm ck_pr_faa_64 , +.Nm ck_pr_faa_32 , +.Nm ck_pr_faa_16 , +.Nm ck_pr_faa_8 +.Nd atomic fetch-and-add operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft uintptr_t +.Fn ck_pr_faa_ptr "void *target" "uintptr_t delta" +.Ft double +.Fn ck_pr_faa_double "double *target" "double delta" +.Ft char +.Fn ck_pr_faa_char "char *target" "char delta" +.Ft unsigned int +.Fn ck_pr_faa_uint "unsigned int *target" "unsigned int delta" +.Ft int +.Fn ck_pr_faa_int "int *target" "int delta" +.Ft uint64_t +.Fn ck_pr_faa_64 "uint64_t *target" "uint64_t delta" +.Ft uint32_t +.Fn ck_pr_faa_32 "uint32_t *target" "uint32_t delta" +.Ft uint16_t +.Fn ck_pr_faa_16 "uint16_t *target" "uint16_t delta" +.Ft uint8_t +.Fn ck_pr_faa_8 "uint8_t *target" "uint8_t delta" +.Sh DESCRIPTION +The +.Fn ck_pr_faa 3 +family of functions atomically fetch the value pointed to +by +.Fa target +and add the value specified by +.Fa delta +to the value pointed to by +.Fa target . +.Sh RETURN VALUES +This function returns the value pointed to by +.Fa target +at the time of operation invocation before the +addition operation is applied. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fas b/doc/ck_pr_fas new file mode 100644 index 0000000..037b104 --- /dev/null +++ b/doc/ck_pr_fas @@ -0,0 +1,100 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_fas 3 +.Sh NAME +.Nm ck_pr_fas_ptr , +.Nm ck_pr_fas_double , +.Nm ck_pr_fas_char , +.Nm ck_pr_fas_uint , +.Nm ck_pr_fas_int , +.Nm ck_pr_fas_64 , +.Nm ck_pr_fas_32 , +.Nm ck_pr_fas_16 , +.Nm ck_pr_fas_8 +.Nd atomic swap operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void * +.Fn ck_pr_fas_ptr "void *target" "void *new_value" +.Ft double +.Fn ck_pr_fas_double "double *target" "double new_value" +.Ft char +.Fn ck_pr_fas_char "char *target" "char new_value" +.Ft unsigned int +.Fn ck_pr_fas_uint "unsigned int *target" "unsigned int new_value" +.Ft int +.Fn ck_pr_fas_int "int *target" "int new_value" +.Ft uint64_t +.Fn ck_pr_fas_64 "uint64_t *target" "uint64_t new_value" +.Ft uint32_t +.Fn ck_pr_fas_32 "uint32_t *target" "uint32_t new_value" +.Ft uint16_t +.Fn ck_pr_fas_16 "uint16_t *target" "uint16_t new_value" +.Ft uint8_t +.Fn ck_pr_fas_8 "uint8_t *target" "uint8_t new_value" +.Sh DESCRIPTION +The +.Fn ck_pr_fas 3 +family of functions atomically fetch the value pointed to +by +.Fa target +and replace the value pointed to by +.Fa target +with the value specified by +.Fa new_value . +.Sh RETURN VALUES +This function returns the value pointed to by +.Fa target +at the time of operation invocation before it was +atomically replaced with +.Fa new_value . +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_acquire b/doc/ck_pr_fence_acquire new file mode 100644 index 0000000..2d6b997 --- /dev/null +++ b/doc/ck_pr_fence_acquire @@ -0,0 +1,72 @@ +.\" +.\" Copyright 2014 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 January 2, 2014 +.Dt CK_PR_FENCE_ACQUIRE 3 +.Sh NAME +.Nm ck_pr_fence_acquire +.Nd enforce acquire semantics +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_acquire void +.Sh DESCRIPTION +This function enforces the partial ordering of any loads prior +to invocation with respect to any following stores, loads and +atomic operations. It is typically used to implement critical +sections. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_release 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_atomic b/doc/ck_pr_fence_atomic new file mode 100644 index 0000000..0680328 --- /dev/null +++ b/doc/ck_pr_fence_atomic @@ -0,0 +1,111 @@ +.\" +.\" 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 May 16, 2013 +.Dt CK_PR_FENCE_ATOMIC 3 +.Sh NAME +.Nm ck_pr_fence_atomic +.Nd enforce partial ordering of atomic read-modify-write operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_atomic void +.Ft void +.Fn ck_pr_fence_strict_atomic void +.Sh DESCRIPTION +The +.Fn ck_pr_fence_atomic +function enforces the ordering of any +atomic read-modify-write operations relative to +the invocation of the function. This function +always serve as an implicit compiler barrier. On +architectures implementing CK_MD_TSO, this operation +only serves as a compiler barrier and no fences +are emitted. On architectures implementing +CK_MD_PSO and CK_MD_RMO, a store fence is +emitted. To force the unconditional emission of +a fence, use +.Fn ck_pr_fence_strict_atomic . +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static int a = 0; +static int b = 0; +static int c = 0; + +void +function(void) +{ + + ck_pr_fas_int(&a, 1); + + /* + * Guarantee that the update to a is completed + * with respect to the updates of b and c. + */ + ck_pr_fence_atomic(); + ck_pr_fas_int(&b, 2); + ck_pr_fas_int(&c, 2); + + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_atomic_load b/doc/ck_pr_fence_atomic_load new file mode 100644 index 0000000..77675ce --- /dev/null +++ b/doc/ck_pr_fence_atomic_load @@ -0,0 +1,108 @@ +.\" +.\" 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 May 16, 2013 +.Dt CK_PR_FENCE_ATOMIC_LOAD 3 +.Sh NAME +.Nm ck_pr_fence_atomic_load +.Nd enforce ordering of atomic read-modify-write operations to load operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_atomic_load void +.Ft void +.Fn ck_pr_fence_strict_atomic_load void +.Sh DESCRIPTION +The +.Fn ck_pr_fence_atomic_load +function enforces the ordering of any +atomic read-modify-write operations relative to +any load operations following the function invocation. This function +always serve as an implicit compiler barrier. On +architectures implementing CK_MD_TSO, this operation +only serves as a compiler barrier and no fences +are emitted. To force the unconditional emission of +a fence, use +.Fn ck_pr_fence_strict_atomic_load . +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static int a = 0; +static int b = 0; + +void +function(void) +{ + int c; + + ck_pr_fas_int(&a, 1); + + /* + * Guarantee that the update to a is completed + * with respect to the load of *b. + */ + ck_pr_fence_atomic_load(); + c = ck_pr_load_int(&b); + + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_atomic_store b/doc/ck_pr_fence_atomic_store new file mode 100644 index 0000000..fd02122 --- /dev/null +++ b/doc/ck_pr_fence_atomic_store @@ -0,0 +1,109 @@ +.\" +.\" 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 May 16, 2013 +.Dt CK_PR_FENCE_ATOMIC_STORE 3 +.Sh NAME +.Nm ck_pr_fence_atomic_store +.Nd enforce ordering of atomic read-modify-write operations to store operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_atomic_store void +.Ft void +.Fn ck_pr_fence_strict_atomic_store void +.Sh DESCRIPTION +The +.Fn ck_pr_fence_atomic_store +function enforces the ordering of any +atomic read-modify-write operations relative to +any load operations following the function invocation. This function +always serve as an implicit compiler barrier. On +architectures implementing CK_MD_TSO, this operation +only serves as a compiler barrier and no fences +are emitted. To force the unconditional emission of +a fence, use +.Fn ck_pr_fence_strict_atomic_store . +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static int a = 0; +static int b = 0; + +void +function(void) +{ + int c; + + ck_pr_fas_int(&a, 1); + + /* + * Guarantee that the update to a is completed + * with respect to the store into the value pointed + * to by b. + */ + ck_pr_fence_atomic_store(); + c = ck_pr_store_int(&b, 2); + + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_load b/doc/ck_pr_fence_load new file mode 100644 index 0000000..b6e778d --- /dev/null +++ b/doc/ck_pr_fence_load @@ -0,0 +1,113 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_fence_load 3 +.Sh NAME +.Nm ck_pr_fence_load +.Nd enforce partial ordering of load operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_load void +.Ft void +.Fn ck_pr_fence_strict_load void +.Sh DESCRIPTION +This function enforces the ordering of any memory load +and +.Fn ck_pr_load 3 +operations relative to the invocation of the function. Any +store operations that were committed on remote processors +and received by the calling processor before the invocation of +.Fn ck_pr_fence_load +is also be made visible only after a call to +.Fn ck_pr_fence_load . +This function always serves as an implicit compiler barrier. +On architectures with CK_MD_TSO or CK_MD_PSO specified (total store ordering +and partial store ordering respectively), this operation only serves +as a compiler barrier and no fence instructions will be emitted. To +force the unconditional emission of a load fence, use +.Fn ck_pr_fence_strict_load . +Architectures implementing CK_MD_RMO always emit a load fence. +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static unsigned int a; +static unsigned int b; + +void +function(void) +{ + unsigned int snapshot_a, snapshot_b; + + snapshot_a = ck_pr_load_uint(&a); + + /* + * Guarantee that the load from "a" completes + * before the load from "b". + */ + ck_pr_fence_load(); + snapshot_b = ck_pr_load_uint(&b); + + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_load_atomic b/doc/ck_pr_fence_load_atomic new file mode 100644 index 0000000..c935491 --- /dev/null +++ b/doc/ck_pr_fence_load_atomic @@ -0,0 +1,113 @@ +.\" +.\" 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 May 18, 2013 +.Dt CK_PR_FENCE_LOAD_ATOMIC 3 +.Sh NAME +.Nm ck_pr_fence_load_atomic +.Nd enforce ordering of load operations to atomic read-modify-write operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_load_atomic void +.Ft void +.Fn ck_pr_fence_strict_load_atomic void +.Sh DESCRIPTION +This function enforces the ordering of any memory load +and +.Fn ck_pr_load 3 +operations with respect to store operations relative to +the invocation of the function. Any store operations that +were committed on remote processors +and received by the calling processor before the invocation of +.Fn ck_pr_fence_load_atomic +is also be made visible only after a call to +the ck_pr_fence_load family of functions. +This function always serves as an implicit compiler barrier. +On architectures with CK_MD_TSO or CK_MD_PSO specified (total store ordering +and partial store ordering respectively), this operation only serves +as a compiler barrier and no fence instructions will be emitted. To +force the unconditional emission of a load fence, use +.Fn ck_pr_fence_strict_load_atomic . +Architectures implementing CK_MD_RMO always emit a fence. +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static unsigned int a; +static unsigned int b; + +void +function(void) +{ + unsigned int snapshot_a, snapshot_b; + + snapshot_a = ck_pr_load_uint(&a); + + /* + * Guarantee that the load from "a" completes + * before the update to "b". + */ + ck_pr_fence_load_atomic(); + ck_pr_fas_uint(&b, 1); + + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_load_depends b/doc/ck_pr_fence_load_depends new file mode 100644 index 0000000..0c0ecfa --- /dev/null +++ b/doc/ck_pr_fence_load_depends @@ -0,0 +1,75 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_fence_load_depends 3 +.Sh NAME +.Nm ck_pr_fence_load_depends +.Nd data dependency barrier +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_load_depends void +.Sh DESCRIPTION +The +.Fn ck_pr_fence_load_depends 3 +emits necessary fences for pure data-dependent loads. It currently only serves as a compiler +barrier for Concurrency Kit's supported platforms. Unless you're on architecture +which re-orders data-dependent loads (such as the defunct Alpha), this function is unnecessary. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_load_store b/doc/ck_pr_fence_load_store new file mode 100644 index 0000000..4abce99 --- /dev/null +++ b/doc/ck_pr_fence_load_store @@ -0,0 +1,113 @@ +.\" +.\" 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 May 18, 2013 +.Dt CK_PR_FENCE_LOAD_STORE 3 +.Sh NAME +.Nm ck_pr_fence_load_store +.Nd enforce ordering of load operations to store operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_load_store void +.Ft void +.Fn ck_pr_fence_strict_load_store void +.Sh DESCRIPTION +This function enforces the ordering of any memory load +and +.Fn ck_pr_load 3 +operations with respect to store operations relative to +the invocation of the function. Any store operations that +were committed on remote processors +and received by the calling processor before the invocation of +.Fn ck_pr_fence_load_store +is also be made visible only after a call to +the ck_pr_fence_load family of functions. +This function always serves as an implicit compiler barrier. +On architectures with CK_MD_TSO or CK_MD_PSO specified (total store ordering +and partial store ordering respectively), this operation only serves +as a compiler barrier and no fence instructions will be emitted. To +force the unconditional emission of a load fence, use +.Fn ck_pr_fence_strict_load_store . +Architectures implementing CK_MD_RMO always emit a fence. +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static unsigned int a; +static unsigned int b; + +void +function(void) +{ + unsigned int snapshot_a; + + snapshot_a = ck_pr_load_uint(&a); + + /* + * Guarantee that the load from "a" completes + * before the store to "b". + */ + ck_pr_fence_load_store(); + ck_pr_store_uint(&b, 1); + + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_memory b/doc/ck_pr_fence_memory new file mode 100644 index 0000000..0dfc81b --- /dev/null +++ b/doc/ck_pr_fence_memory @@ -0,0 +1,113 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_fence_memory 3 +.Sh NAME +.Nm ck_pr_fence_memory +.Nd enforce partial ordering of all memory operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_memory +.Ft void +.Fn ck_pr_fence_strict_memory +.Sh DESCRIPTION +The +.Fn ck_pr_fence_memory 3 +function enforces the ordering of any memory operations +with respect to the invocation of the function. This function +always serves as an implicit compiler barrier. +Achitectures implementing CK_MD_TSO do not emit +a barrier, but compiler barrier semantics remain. +Architectures implementing CK_MD_PSO and CK_MD_RMO always emit +an instructions which provides the specified ordering +guarantees. To force the unconditional emission of a memory +fence, use +.Fn ck_pr_fence_strict_memory . +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static int a = 0; +static int b; +static int c; +static int d; + +void +function(void) +{ + int snapshot_a; + + ck_pr_store_int(&b, 1); + snapshot_a = ck_pr_load_int(&a); + + /* + * Make sure previous memory operations are + * ordered with respect to memory operations + * following the ck_pr_fence_memory. + */ + ck_pr_fence_memory(); + + ck_pr_store_int(&d, 3); + ck_pr_store_int(&c, 2); + + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_release b/doc/ck_pr_fence_release new file mode 100644 index 0000000..214917c --- /dev/null +++ b/doc/ck_pr_fence_release @@ -0,0 +1,71 @@ +.\" +.\" Copyright 2014 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 January 2, 2014 +.Dt CK_PR_FENCE_RELEASE 3 +.Sh NAME +.Nm ck_pr_fence_release +.Nd enforce release semantics +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_release void +.Sh DESCRIPTION +This function enforces the partial ordering of any loads prior +to invocation with respect to any following stores and any stores +prior to invocation with respect to any following stores. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_acquire 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_store b/doc/ck_pr_fence_store new file mode 100644 index 0000000..d94e9f1 --- /dev/null +++ b/doc/ck_pr_fence_store @@ -0,0 +1,112 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_fence_store 3 +.Sh NAME +.Nm ck_pr_fence_store +.Nd enforce partial ordering of store operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_store void +.Ft void +.Fn ck_pr_fence_strict_store void +.Sh DESCRIPTION +The +.Fn ck_pr_fence_store +function enforces the ordering of any memory store, +.Fn ck_pr_store +and atomic read-modify-write operations relative to +the invocation of the function. This function +always serve as an implicit compiler barrier. On +architectures implementing CK_MD_TSO, this operation +only serves as a compiler barrier and no fences +are emitted. On architectures implementing +CK_MD_PSO and CK_MD_RMO, a store fence is +emitted. To force the unconditional emission of +a store fence, use +.Fn ck_pr_fence_strict_store . +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static int a = 0; +static int b = 0; +static int c = 0; + +void +function(void) +{ + + ck_pr_store_int(&a, 1); + + /* + * Guarantee that the store to a is completed + * with respect to the stores of b and c. + */ + ck_pr_fence_store(); + ck_pr_store_int(&b, 2); + ck_pr_store_int(&c, 2); + + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_store_atomic b/doc/ck_pr_fence_store_atomic new file mode 100644 index 0000000..309c804 --- /dev/null +++ b/doc/ck_pr_fence_store_atomic @@ -0,0 +1,108 @@ +.\" +.\" 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 May 18, 2013 +.Dt CK_PR_FENCE_STORE_ATOMIC 3 +.Sh NAME +.Nm ck_pr_fence_store_atomic +.Nd enforce ordering of store operations to load operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_store_atomic void +.Ft void +.Fn ck_pr_fence_strict_store_atomic void +.Sh DESCRIPTION +The +.Fn ck_pr_fence_store_atomic +function enforces the ordering of any memory store, +.Fn ck_pr_store +and atomic read-modify-write operations to atomic read-modify-write +operations relative to the invocation of the function. This function +always serve as an implicit compiler barrier. +This functions will emit a fence for PSO and RMO +targets. In order to force the emission of a fence use the +.Fn ck_pr_fence_strict_store_atomic +function. +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static int a = 0; +static int b = 0; + +void +function(void) +{ + + ck_pr_store_int(&a, 1); + + /* + * Guarantee that the store to a is completed + * with respect to the update of b. + */ + ck_pr_fence_store_atomic(); + ck_pr_add_int(&b, 2); + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_store_load 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_store_load b/doc/ck_pr_fence_store_load new file mode 100644 index 0000000..b595739 --- /dev/null +++ b/doc/ck_pr_fence_store_load @@ -0,0 +1,107 @@ +.\" +.\" 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 May 18, 2013 +.Dt CK_PR_FENCE_STORE_LOAD 3 +.Sh NAME +.Nm ck_pr_fence_store_load +.Nd enforce ordering of store operations to load operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_store_load void +.Ft void +.Fn ck_pr_fence_strict_store_load void +.Sh DESCRIPTION +The +.Fn ck_pr_fence_store_load +function enforces the ordering of any memory store, +.Fn ck_pr_store +and atomic read-modify-write operations to load +operations relative to the invocation of the function. This function +always serve as an implicit compiler barrier. +A fence will currently always be emitted for this +operation, including for TSO memory model targets. +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static int a = 0; +static int b = 0; + +void +function(void) +{ + unsigned int snapshot_b; + + ck_pr_store_int(&a, 1); + + /* + * Guarantee that the store to a is completed + * with respect to load from b. + */ + ck_pr_fence_store_load(); + snapshot_b = ck_pr_load_int(&b, 2); + return; +} +.Ed +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_stall 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_store_atomic 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_inc b/doc/ck_pr_inc new file mode 100644 index 0000000..72a3e70 --- /dev/null +++ b/doc/ck_pr_inc @@ -0,0 +1,124 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_inc 3 +.Sh NAME +.Nm ck_pr_inc_ptr , +.Nm ck_pr_inc_ptr_zero , +.Nm ck_pr_inc_double , +.Nm ck_pr_inc_double_zero , +.Nm ck_pr_inc_char , +.Nm ck_pr_inc_char_zero , +.Nm ck_pr_inc_uint , +.Nm ck_pr_inc_uint_zero , +.Nm ck_pr_inc_int , +.Nm ck_pr_inc_int_zero , +.Nm ck_pr_inc_64 , +.Nm ck_pr_inc_64_zero , +.Nm ck_pr_inc_32 , +.Nm ck_pr_inc_32_zero , +.Nm ck_pr_inc_16 , +.Nm ck_pr_inc_16_zero , +.Nm ck_pr_inc_8 , +.Nm ck_pr_inc_8_zero +.Nd atomic increment operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_inc_ptr "void *target" +.Ft void +.Fn ck_pr_inc_ptr_zero "void *target" "bool *z" +.Ft void +.Fn ck_pr_inc_double "double *target" +.Ft void +.Fn ck_pr_inc_double_zero "double *target" "bool *z" +.Ft void +.Fn ck_pr_inc_char "char *target" +.Ft void +.Fn ck_pr_inc_char_zero "char *target" "bool *z" +.Ft void +.Fn ck_pr_inc_uint "unsigned int *target" +.Ft void +.Fn ck_pr_inc_uint_zero "unsigned int *target" "bool *z" +.Ft void +.Fn ck_pr_inc_int "int *target" +.Ft void +.Fn ck_pr_inc_int_zero "int *target" "bool *z" +.Ft void +.Fn ck_pr_inc_64 "uint64_t *target" +.Ft void +.Fn ck_pr_inc_64_zero "uint64_t *target" "bool *z" +.Ft void +.Fn ck_pr_inc_32 "uint32_t *target" +.Ft void +.Fn ck_pr_inc_32_zero "uint32_t *target" "bool *z" +.Ft void +.Fn ck_pr_inc_16 "uint16_t *target" +.Ft void +.Fn ck_pr_inc_16_zero "uint16_t *target" "bool *z" +.Ft void +.Fn ck_pr_inc_8 "uint8_t *target" +.Ft void +.Fn ck_pr_inc_8_zero "uint8_t *target" "bool *z" +.Sh DESCRIPTION +The +.Fn ck_pr_inc 3 +family of functions atomically increment the value pointed to +by +.Fa target . +.Sh RETURN VALUES +The ck_pr_inc_zero family of functions set the value pointed to by +.Fa z +to true if the result of the increment operation was 0. The functions set +the value pointed to by +.Fa z +false otherwise. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_load b/doc/ck_pr_load new file mode 100644 index 0000000..ed615d3 --- /dev/null +++ b/doc/ck_pr_load @@ -0,0 +1,96 @@ +.\" +.\" 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 April 15, 2013 +.Dt ck_pr_load 3 +.Sh NAME +.Nm ck_pr_load_ptr , +.Nm ck_pr_load_double , +.Nm ck_pr_load_uint , +.Nm ck_pr_load_int , +.Nm ck_pr_load_char , +.Nm ck_pr_load_64 , +.Nm ck_pr_load_32 , +.Nm ck_pr_load_16 , +.Nm ck_pr_load_8 +.Nd atomic volatile load operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void * +.Fn ck_pr_load_ptr "const void *target" +.Ft double +.Fn ck_pr_load_double "const double *target" +.Ft unsigned int +.Fn ck_pr_load_uint "const unsigned int *target" +.Ft int +.Fn ck_pr_load_int "const int *target" +.Ft char +.Fn ck_pr_load_char "const char *target" +.Ft uint64_t +.Fn ck_pr_load_64 "const uint64_t *target" +.Ft uint32_t +.Fn ck_pr_load_32 "const uint32_t *target" +.Ft uint16_t +.Fn ck_pr_load_16 "const uint16_t *target" +.Ft uint8_t +.Fn ck_pr_load_8 "const uint8_t *target" +.Sh DESCRIPTION +The +.Fn ck_pr_load 3 +family of functions atomically loads the value +pointed to by +.Fa target +and returns it. This family of functions always +serves as an implicit compiler barrier and is not +susceptible to re-ordering by the compiler. +.Sh RETURN VALUES +This family of functions returns the value contained +in the location pointed to by the first argument. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_neg b/doc/ck_pr_neg new file mode 100644 index 0000000..38f9a0a --- /dev/null +++ b/doc/ck_pr_neg @@ -0,0 +1,122 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_neg 3 +.Sh NAME +.Nm ck_pr_neg_ptr , +.Nm ck_pr_neg_ptr_zero , +.Nm ck_pr_neg_double , +.Nm ck_pr_neg_double_zero , +.Nm ck_pr_neg_char , +.Nm ck_pr_neg_char_zero , +.Nm ck_pr_neg_uint , +.Nm ck_pr_neg_uint_zero , +.Nm ck_pr_neg_int , +.Nm ck_pr_neg_int_zero , +.Nm ck_pr_neg_64 , +.Nm ck_pr_neg_64_zero , +.Nm ck_pr_neg_32 , +.Nm ck_pr_neg_32_zero , +.Nm ck_pr_neg_16 , +.Nm ck_pr_neg_16_zero , +.Nm ck_pr_neg_8 , +.Nm ck_pr_neg_8_zero +.Nd atomic negation operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_neg_ptr "void *target" +.Ft void +.Fn ck_pr_neg_ptr_zero "void *target" "bool *z" +.Ft void +.Fn ck_pr_neg_double "double *target" +.Ft void +.Fn ck_pr_neg_double_zero "double *target" "bool *z" +.Ft void +.Fn ck_pr_neg_char "char *target" +.Ft void +.Fn ck_pr_neg_char_zero "char *target" "bool *z" +.Ft void +.Fn ck_pr_neg_uint "unsigned int *target" +.Ft void +.Fn ck_pr_neg_uint_zero "unsigned int *target" "bool *z" +.Ft void +.Fn ck_pr_neg_int "int *target" +.Ft void +.Fn ck_pr_neg_int_zero "int *target" "bool *z" +.Ft void +.Fn ck_pr_neg_64 "uint64_t *target" +.Ft void +.Fn ck_pr_neg_64_zero "uint64_t *target" "bool *z" +.Ft void +.Fn ck_pr_neg_32 "uint32_t *target" +.Ft void +.Fn ck_pr_neg_32_zero "uint32_t *target" "bool *z" +.Ft void +.Fn ck_pr_neg_16 "uint16_t *target" +.Ft void +.Fn ck_pr_neg_16_zero "uint16_t *target" "bool *z" +.Ft void +.Fn ck_pr_neg_8 "uint8_t *target" +.Ft void +.Fn ck_pr_neg_8_zero "uint8_t *target" "bool *z" +.Sh DESCRIPTION +The +.Fn ck_pr_neg 3 +family of functions atomically negate the value pointed to +by +.Fa target . +.Sh RETURN VALUES +The ck_pr_neg_zero functions set the value pointed to by +.Fa z +if the result of the negation operation was 0. They set the +pointed to value to false otherwise. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_not b/doc/ck_pr_not new file mode 100644 index 0000000..b0a38b2 --- /dev/null +++ b/doc/ck_pr_not @@ -0,0 +1,92 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_not 3 +.Sh NAME +.Nm ck_pr_not_ptr , +.Nm ck_pr_not_double , +.Nm ck_pr_not_char , +.Nm ck_pr_not_uint , +.Nm ck_pr_not_int , +.Nm ck_pr_not_64 , +.Nm ck_pr_not_32 , +.Nm ck_pr_not_16 , +.Nm ck_pr_not_8 +.Nd atomic complement operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_not_ptr "void *target" +.Ft void +.Fn ck_pr_not_double "double *target" +.Ft void +.Fn ck_pr_not_char "char *target" +.Ft void +.Fn ck_pr_not_uint "unsigned int *target" +.Ft void +.Fn ck_pr_not_int "int *target" +.Ft void +.Fn ck_pr_not_64 "uint64_t *target" +.Ft void +.Fn ck_pr_not_32 "uint32_t *target" +.Ft void +.Fn ck_pr_not_16 "uint16_t *target" +.Ft void +.Fn ck_pr_not_8 "uint8_t *target" +.Sh DESCRIPTION +The +.Fn ck_pr_not 3 +family of functions atomically complement the value pointed to +by +.Fa target . +.Sh RETURN VALUES +These functions have no return value. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_or b/doc/ck_pr_or new file mode 100644 index 0000000..2a68330 --- /dev/null +++ b/doc/ck_pr_or @@ -0,0 +1,93 @@ +.\" +.\" 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 April 11, 2013 +.Dt ck_pr_or 3 +.Sh NAME +.Nm ck_pr_or_ptr , +.Nm ck_pr_or_char , +.Nm ck_pr_or_uint , +.Nm ck_pr_or_int , +.Nm ck_pr_or_64 , +.Nm ck_pr_or_32 , +.Nm ck_pr_or_16 , +.Nm ck_pr_or_8 +.Nd atomic bitwise-or operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_or_ptr "void *target" "uintptr_t delta" +.Ft void +.Fn ck_pr_or_char "char *target" "char delta" +.Ft void +.Fn ck_pr_or_uint "unsigned int *target" "unsigned int delta" +.Ft void +.Fn ck_pr_or_int "int *target" "int delta" +.Ft void +.Fn ck_pr_or_64 "uint64_t *target" "uint64_t delta" +.Ft void +.Fn ck_pr_or_32 "uint32_t *target" "uint32_t delta" +.Ft void +.Fn ck_pr_or_16 "uint16_t *target" "uint16_t delta" +.Ft void +.Fn ck_pr_or_8 "uint8_t *target" "uint8_t delta" +.Sh DESCRIPTION +The +.Fn ck_pr_or 3 +family of functions atomically compute and store the +result of a bitwise-or of the value pointed to by +.Fa target +and +.Fa delta +into the value pointed to by +.Fa target . +.Sh RETURN VALUES +This family of functions does not have a return value. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_rtm b/doc/ck_pr_rtm new file mode 100644 index 0000000..53c31b6 --- /dev/null +++ b/doc/ck_pr_rtm @@ -0,0 +1,112 @@ +.\" +.\" 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_pr_rtm 3 +.Sh NAME +.Nm ck_pr_rtm_begin , +.Nm ck_pr_rtm_end , +.Nm ck_pr_rtm_abort , +.Nm ck_pr_rtm_test +.Nd restricted transactional memory +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft unsigned int +.Fn ck_pr_rtm_begin "void" +.Ft void +.Fn ck_pr_rtm_end "void" +.Ft void +.Fn ck_pr_rtm_abort "const unsigned int status" +.Ft bool +.Fn ck_pr_rtm_test "void" +.Sh DESCRIPTION +These family of functions implement support for restricted +transactional memory, if available on the underlying platform. +Currently, support is only provided for Intel Haswell and +newer x86 microarchitectures that have the TSX-NI feature. +.Pp +The +.Fn ck_pr_rtm_begin +function returns CK_PR_RTM_STARTED if a transaction was successfully +started. In case of an abort, either internal (through a ck_pr_rtm_abort) +or external, program flow will return to the point which the function +was called except the return value will consist of a bitmap with one or +more of the following bits set: +.Bl -tag -width indent +.It CK_PR_RTM_EXPLICIT +Set if the transactionally was explicitly aborted through +.Fn ck_pr_rtm_abort . +.It CK_PR_RTM_RETRY +Set if the transaction failed but can still succeed if +retried. +.It CK_PR_RTM_CONFLICT +The transaction failed due to a conflict in one of the memory +addresses that are part of the working set of the transaction. +.It CK_PR_RTM_CAPACITY +Set if the architecture-defined transaction size limit was exceeded. +.It CK_PR_RTM_DEBUG +Set if a hardware breakpoint was triggered. +.It CK_PR_RTM_NESTED +Set if a nested transaction failed. +.El +.Pp +The user is also able to specify a one byte abort status +by calling +.Fn ck_pr_rtm_abort . +This status byte can be extracted by calling the +.Fn CK_PR_RTM_CODE +function with the return value of +.Fn ck_pr_rtm_begin +as an argument. The return value of +.Fn CK_PR_RTM_CODE +will be the value of this status byte. +For additional information, please see the Intel instruction +set manuals. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_stall b/doc/ck_pr_stall new file mode 100644 index 0000000..bc46647 --- /dev/null +++ b/doc/ck_pr_stall @@ -0,0 +1,86 @@ +.\" +.\" 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 April 7, 2013 +.Dt ck_pr_stall 3 +.Sh NAME +.Nm ck_pr_stall +.Nd busy-wait primitive +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_stall void +.Sh DESCRIPTION +The +.Fn ck_pr_stall 3 +function should be used inside retry paths of busy-wait loops. +It not only serves as a compiler barrier, but on some architectures +it emits cycle-saving instructions. +.Sh EXAMPLE +.Bd -literal -offset indent + +#include <ck_pr.h> + +static int ready = 0; + +void +function(void) +{ + + /* Busy-wait until ready is non-zero. */ + while (ck_pr_load_int(&ready) == 0) + ck_pr_stall(); + + return; +} +.Ed +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_barrier 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_store b/doc/ck_pr_store new file mode 100644 index 0000000..462cf7b --- /dev/null +++ b/doc/ck_pr_store @@ -0,0 +1,96 @@ +.\" +.\" 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 April 15, 2013 +.Dt ck_pr_store 3 +.Sh NAME +.Nm ck_pr_store_ptr , +.Nm ck_pr_store_double , +.Nm ck_pr_store_uint , +.Nm ck_pr_store_int , +.Nm ck_pr_store_char , +.Nm ck_pr_store_64 , +.Nm ck_pr_store_32 , +.Nm ck_pr_store_16 , +.Nm ck_pr_store_8 +.Nd atomic volatile store operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_store_ptr "void *target" "void *value" +.Ft void +.Fn ck_pr_store_double "double *target" "double value" +.Ft void +.Fn ck_pr_store_uint "unsigned int *target" "unsigned int value" +.Ft void +.Fn ck_pr_store_int "int *target" "int value" +.Ft void +.Fn ck_pr_store_char "char *target" "char value" +.Ft void +.Fn ck_pr_store_64 "uint64_t *target" "uint64_t value" +.Ft void +.Fn ck_pr_store_32 "uint32_t *target" "uint32_t value" +.Ft void +.Fn ck_pr_store_16 "uint16_t *target" "uint16_t value" +.Ft void +.Fn ck_pr_store_8 "uint8_t *target" "uint8_t value" +.Sh DESCRIPTION +The +.Fn ck_pr_store 3 +family of functions atomically stores the value specified +by +.Fa value +into the location pointed to by +.Fa target . +This family of functions always serves as an implicit compiler +barrier and is not susceptible to compiler re-ordering. +.Sh RETURN VALUES +This family of functions has no return value. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_sub b/doc/ck_pr_sub new file mode 100644 index 0000000..5eee170 --- /dev/null +++ b/doc/ck_pr_sub @@ -0,0 +1,93 @@ +.\" +.\" 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 April 11, 2013 +.Dt ck_pr_sub 3 +.Sh NAME +.Nm ck_pr_sub_ptr , +.Nm ck_pr_sub_double , +.Nm ck_pr_sub_char , +.Nm ck_pr_sub_uint , +.Nm ck_pr_sub_int , +.Nm ck_pr_sub_64 , +.Nm ck_pr_sub_32 , +.Nm ck_pr_sub_16 , +.Nm ck_pr_sub_8 +.Nd atomic subtraction operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_sub_ptr "void *target" "uintptr_t delta" +.Ft void +.Fn ck_pr_sub_double "double *target" "double delta" +.Ft void +.Fn ck_pr_sub_char "char *target" "char delta" +.Ft void +.Fn ck_pr_sub_uint "unsigned int *target" "unsigned int delta" +.Ft void +.Fn ck_pr_sub_int "int *target" "int delta" +.Ft void +.Fn ck_pr_sub_64 "uint64_t *target" "uint64_t delta" +.Ft void +.Fn ck_pr_sub_32 "uint32_t *target" "uint32_t delta" +.Ft void +.Fn ck_pr_sub_16 "uint16_t *target" "uint16_t delta" +.Ft void +.Fn ck_pr_sub_8 "uint8_t *target" "uint8_t delta" +.Sh DESCRIPTION +The +.Fn ck_pr_sub 3 +family of functions atomically subtract the value specified by +.Fa delta +from the value pointed to by +.Fa target . +.Sh RETURN VALUES +This family of functions does not have a return value. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_xor b/doc/ck_pr_xor new file mode 100644 index 0000000..509f60d --- /dev/null +++ b/doc/ck_pr_xor @@ -0,0 +1,93 @@ +.\" +.\" 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 April 11, 2013 +.Dt ck_pr_xor 3 +.Sh NAME +.Nm ck_pr_xor_ptr , +.Nm ck_pr_xor_char , +.Nm ck_pr_xor_uint , +.Nm ck_pr_xor_int , +.Nm ck_pr_xor_64 , +.Nm ck_pr_xor_32 , +.Nm ck_pr_xor_16 , +.Nm ck_pr_xor_8 +.Nd atomic bitwise-xor operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_xor_ptr "void *target" "uintptr_t delta" +.Ft void +.Fn ck_pr_xor_char "char *target" "char delta" +.Ft void +.Fn ck_pr_xor_uint "unsigned int *target" "unsigned int delta" +.Ft void +.Fn ck_pr_xor_int "int *target" "int delta" +.Ft void +.Fn ck_pr_xor_64 "uint64_t *target" "uint64_t delta" +.Ft void +.Fn ck_pr_xor_32 "uint32_t *target" "uint32_t delta" +.Ft void +.Fn ck_pr_xor_16 "uint16_t *target" "uint16_t delta" +.Ft void +.Fn ck_pr_xor_8 "uint8_t *target" "uint8_t delta" +.Sh DESCRIPTION +The +.Fn ck_pr_xor 3 +family of functions atomically compute and store the +result of a bitwise-xor of the value pointed to by +.Fa target +and +.Fa delta +into the value pointed to by +.Fa target . +.Sh RETURN VALUES +This family of functions does not have a return value. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_cas 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_queue b/doc/ck_queue new file mode 100644 index 0000000..a27ec15 --- /dev/null +++ b/doc/ck_queue @@ -0,0 +1,147 @@ +.\" +.\" 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 28, 2013. +.Dt ck_queue 3 +.Sh NAME +.Nm CK_LIST_EMPTY , +.Nm CK_LIST_ENTRY , +.Nm CK_LIST_FIRST , +.Nm CK_LIST_FOREACH , +.Nm CK_LIST_FOREACH_SAFE , +.Nm CK_LIST_HEAD , +.Nm CK_LIST_HEAD_INITIALIZER , +.Nm CK_LIST_INIT , +.Nm CK_LIST_INSERT_AFTER , +.Nm CK_LIST_INSERT_BEFORE , +.Nm CK_LIST_INSERT_HEAD , +.Nm CK_LIST_MOVE , +.Nm CK_LIST_NEXT , +.Nm CK_LIST_REMOVE , +.Nm CK_LIST_SWAP , +.Nm CK_SLIST_EMPTY , +.Nm CK_SLIST_ENTRY , +.Nm CK_SLIST_FIRST , +.Nm CK_SLIST_FOREACH , +.Nm CK_SLIST_FOREACH_PREVPTR , +.Nm CK_SLIST_FOREACH_SAFE , +.Nm CK_SLIST_HEAD , +.Nm CK_SLIST_HEAD_INITIALIZER , +.Nm CK_SLIST_INIT , +.Nm CK_SLIST_INSERT_AFTER , +.Nm CK_SLIST_INSERT_HEAD , +.Nm CK_SLIST_MOVE , +.Nm CK_SLIST_NEXT , +.Nm CK_SLIST_REMOVE , +.Nm CK_SLIST_REMOVE_AFTER , +.Nm CK_SLIST_REMOVE_HEAD , +.Nm CK_SLIST_SWAP , +.Nm CK_STAILQ_CONCAT , +.Nm CK_STAILQ_EMPTY , +.Nm CK_STAILQ_ENTRY , +.Nm CK_STAILQ_FIRST , +.Nm CK_STAILQ_FOREACH , +.Nm CK_STAILQ_FOREACH_SAFE , +.Nm CK_STAILQ_HEAD , +.Nm CK_STAILQ_HEAD_INITIALIZER , +.Nm CK_STAILQ_INIT , +.Nm CK_STAILQ_INSERT_AFTER , +.Nm CK_STAILQ_INSERT_HEAD , +.Nm CK_STAILQ_INSERT_TAIL , +.Nm CK_STAILQ_MOVE , +.Nm CK_STAILQ_NEXT , +.Nm CK_STAILQ_REMOVE , +.Nm CK_STAILQ_REMOVE_AFTER , +.Nm CK_STAILQ_REMOVE_HEAD , +.Nm CK_STAILQ_SWAP +.Nd multi-reader single-writer singly-linked lists, singly-linked tail queues and lists +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_queue.h +.Fn CK_LIST_EMPTY +.Fn CK_LIST_ENTRY +.Fn CK_LIST_FIRST +.Fn CK_LIST_FOREACH +.Fn CK_LIST_FOREACH_SAFE +.Fn CK_LIST_HEAD +.Fn CK_LIST_HEAD_INITIALIZER +.Fn CK_LIST_INIT +.Fn CK_LIST_INSERT_AFTER +.Fn CK_LIST_INSERT_BEFORE +.Fn CK_LIST_INSERT_HEAD +.Fn CK_LIST_MOVE +.Fn CK_LIST_NEXT +.Fn CK_LIST_REMOVE +.Fn CK_LIST_SWAP +.Fn CK_SLIST_EMPTY +.Fn CK_SLIST_ENTRY +.Fn CK_SLIST_FIRST +.Fn CK_SLIST_FOREACH +.Fn CK_SLIST_FOREACH_PREVPTR +.Fn CK_SLIST_FOREACH_SAFE +.Fn CK_SLIST_HEAD +.Fn CK_SLIST_HEAD_INITIALIZER +.Fn CK_SLIST_INIT +.Fn CK_SLIST_INSERT_AFTER +.Fn CK_SLIST_INSERT_HEAD +.Fn CK_SLIST_MOVE +.Fn CK_SLIST_NEXT +.Fn CK_SLIST_REMOVE +.Fn CK_SLIST_REMOVE_AFTER +.Fn CK_SLIST_REMOVE_HEAD +.Fn CK_SLIST_SWAP +.Fn CK_STAILQ_CONCAT +.Fn CK_STAILQ_EMPTY +.Fn CK_STAILQ_ENTRY +.Fn CK_STAILQ_FIRST +.Fn CK_STAILQ_FOREACH +.Fn CK_STAILQ_FOREACH_SAFE +.Fn CK_STAILQ_HEAD +.Fn CK_STAILQ_HEAD_INITIALIZER +.Fn CK_STAILQ_INIT +.Fn CK_STAILQ_INSERT_AFTER +.Fn CK_STAILQ_INSERT_HEAD +.Fn CK_STAILQ_INSERT_TAIL +.Fn CK_STAILQ_MOVE +.Fn CK_STAILQ_NEXT +.Fn CK_STAILQ_REMOVE +.Fn CK_STAILQ_REMOVE_AFTER +.Fn CK_STAILQ_REMOVE_HEAD +.Fn CK_STAILQ_SWAP +.Sh DESCRIPTION +See your system's manual page for +.Xr queue +for additional information. ck_queue is a queue.h-compatible +implementation of many-reader-single-writer queues. It allows +for safe concurrent iteration, peeking and read-side access +in the presence of a single concurrent writer without any +usage of locks. In many cases, adoption of ck_queue will +simply require prefixing all queue operations with CK_. +.Sh SEE ALSO +.Xr queue +.Pp +Additional information available at http://concurrencykit.org/ 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_set_load_factor b/doc/ck_rhs_set_load_factor new file mode 100644 index 0000000..4ecb847 --- /dev/null +++ b/doc/ck_rhs_set_load_factor @@ -0,0 +1,72 @@ +.\" +.\" Copyright 2015 Olivier Houchard. +.\" 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 16, 2015 +.Dt CK_RHS_SET_LOAD_FACTOR 3 +.Sh NAME +.Nm ck_rhs_set_load_factor +.Nd change the hash set load factor +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rhs.h +.Ft bool +.Fn ck_rhs_set_load_factor "ck_rhs_t *hs" "unsigned int load_factor" +.Sh DESCRIPTION +The +.Fn ck_rhs_set_load_factor 3 +function will change the load factor of the hash set. The hash set will grow if it is load_factor% filled. +.Ed +.Sh RETURN VALUES +.Fn ck_rhs_set_load_factor 3 +returns true on success, or false if either the load factor is invalid (0 or > 100), or if growing was required, but failed. +.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/ 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/ diff --git a/doc/ck_ring_capacity b/doc/ck_ring_capacity new file mode 100644 index 0000000..645b54b --- /dev/null +++ b/doc/ck_ring_capacity @@ -0,0 +1,58 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_CAPACITY 3 +.Sh NAME +.Nm ck_ring_capacity +.Nd returns number of pointer slots in bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft unsigned int +.Fn ck_ring_capacity "ck_ring_t *ring" +.Sh DESCRIPTION +The +.Fn ck_ring_capacity 3 +function returns the number of pointers that can be +held in the buffer pointed to by +.Fa ring . +Note that a ring can only hold +.Fn ck_ring_capacity 3 +minus one entries at a time. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_dequeue_spmc b/doc/ck_ring_dequeue_spmc new file mode 100644 index 0000000..7fd7d9b --- /dev/null +++ b/doc/ck_ring_dequeue_spmc @@ -0,0 +1,117 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_DEQUEUE_SPMC 3 +.Sh NAME +.Nm ck_ring_dequeue_spmc +.Nd dequeue pointer from bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_dequeue_spmc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *result" +.Sh DESCRIPTION +The +.Fn ck_ring_dequeue_spmc 3 +function dequeues a pointer from the bounded buffer +pointed to by +.Fa ring +in FIFO fashion. The pointer is stored in the pointer +pointed to by +.Fa result . +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring . +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa result . +This function is safe to call without locking for UINT_MAX +concurrent invocations of +.Fn ck_ring_dequeue_spmc 3 +or +.Fn ck_ring_trydequeue_spmc 3 +and up to one concurrent +.Fn ck_ring_enqueue_spmc 3 +or +.Fn ck_ring_tryenqueue_spmc 3 +invocation. This function provides lock-free progress +guarantees. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_ring.h> + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + +void +dequeue(void) +{ + void *result; + + /* Dequeue from ring until it is empty. */ + while (ck_ring_dequeue_spmc(&ring, &buffer, &result) == true) { + /* + * Results contains the oldest pointer in ring + * since the dequeue operation returned true. + */ + operation(result); + } + + /* An empty ring was encountered, leave. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the buffer was non-empty. +The result of the dequeue operation is stored in the +value pointed to by +.Fa result . +The function will return false if the buffer was empty +and the value in +.Fa result +will be undefined. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_dequeue_spsc b/doc/ck_ring_dequeue_spsc new file mode 100644 index 0000000..069dc7f --- /dev/null +++ b/doc/ck_ring_dequeue_spsc @@ -0,0 +1,115 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_DEQUEUE_SPSC 3 +.Sh NAME +.Nm ck_ring_dequeue_spsc +.Nd dequeue pointer from bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_dequeue_spsc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *result" +.Sh DESCRIPTION +The +.Fn ck_ring_dequeue_spsc 3 +function dequeues a pointer from the bounded buffer +pointed to by +.Fa ring +in FIFO fashion. The pointer is stored in the pointer +pointed to by +.Fa result . +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa result . +This function is safe to call without locking for one +concurrent invocation of +.Fn ck_ring_dequeue_spsc 3 +and up to one concurrent +.Fn ck_ring_enqueue_spsc 3 +invocation. This function provides wait-free progress +guarantees. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_ring.h> + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + +void +dequeue(void) +{ + void *result; + + /* Dequeue from ring until it is empty. */ + while (ck_ring_dequeue_spsc(&ring, &buffer, &result) == true) { + /* + * Results contains the oldest pointer in ring + * since the dequeue operation returned true. + */ + operation(result); + } + + /* An empty ring was encountered, leave. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the buffer was non-empty. +The result of the dequeue operation is stored in the +value pointed to by +.Fa result . +The function will return false if the buffer was empty +and the value in +.Fa result +will be undefined. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_enqueue_spmc b/doc/ck_ring_enqueue_spmc new file mode 100644 index 0000000..ba99199 --- /dev/null +++ b/doc/ck_ring_enqueue_spmc @@ -0,0 +1,115 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_ENQUEUE_SPMC 3 +.Sh NAME +.Nm ck_ring_enqueue_spmc +.Nd enqueue pointer into bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_enqueue_spmc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *entry" +.Sh DESCRIPTION +The +.Fn ck_ring_enqueue_spmc 3 +function enqueues the pointer +.Fa entry +into the bounded buffer pointed to by +.Fa ring +in FIFO fashion. +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa entry . +This function is safe to call without locking for UINT_MAX +concurrent invocations of +.Fn ck_ring_dequeue_spmc 3 +or +.Fn ck_ring_trydequeue_spmc 3 . +This function provides wait-free progress +guarantees for one active invocation. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_ring.h> + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + +void +enqueue(void) +{ + void *entry = some_object; + + /* Attempt to enqueue pointer to some_object into buffer. */ + if (ck_ring_enqueue_spmc(&ring, &buffer, &entry) == false) { + /* + * The buffer was full and the enqueue operation + * has failed. + */ + return; + } + + /* Enqueue operation completed successfully. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the value of +.Fa entry +was successfully enqueued into +.Fa ring . +The function will return false if the value of +.Fa entry +could not be enqueued which only occurs if +.Fa ring +was full. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_enqueue_spmc_size b/doc/ck_ring_enqueue_spmc_size new file mode 100644 index 0000000..eb30cab --- /dev/null +++ b/doc/ck_ring_enqueue_spmc_size @@ -0,0 +1,127 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_ENQUEUE_SPMC_SIZE 3 +.Sh NAME +.Nm ck_ring_enqueue_spmc_size +.Nd enqueue pointer into bounded FIFO and return size of buffer +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_enqueue_spmc_size "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *entry" "unsigned int *length" +.Sh DESCRIPTION +The +.Fn ck_ring_enqueue_spmc 3 +function enqueues the pointer +.Fa entry +into the bounded buffer pointed to by +.Fa ring +in FIFO fashion. +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa entry . +This function is safe to call without locking for UINT_MAX +concurrent invocations of +.Fn ck_ring_dequeue_spmc 3 +or +.Fn ck_ring_trydequeue_spmc 3 . +This function provides wait-free progress +guarantees for one active invocation. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_ring.h> + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + +void +enqueue(void) +{ + void *entry = some_object; + unsigned int length; + + /* Attempt to enqueue pointer to some_object into buffer. */ + if (ck_ring_enqueue_spmc_size(&ring, &buffer, &entry, &length) == false) { + /* + * The buffer was full and the enqueue operation + * has failed. + */ + return; + } + + /* + * If entry was the 101st or greater pointer in the buffer, + * do something. + */ + if (length > 100) { + do_something; + } + + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the value of +.Fa entry +was successfully enqueued into +.Fa ring . +The function will return false if the value of +.Fa entry +could not be enqueued which only occurs if +.Fa ring +was full. The number of entries in the buffer +with respect to the point in time that +.Fa entry +is enqueued is stored in the integer pointed to by +.Fa length . +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_enqueue_spsc b/doc/ck_ring_enqueue_spsc new file mode 100644 index 0000000..2493059 --- /dev/null +++ b/doc/ck_ring_enqueue_spsc @@ -0,0 +1,113 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_ENQUEUE_SPSC 3 +.Sh NAME +.Nm ck_ring_enqueue_spsc +.Nd enqueue pointer into bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_enqueue_spsc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *entry" +.Sh DESCRIPTION +The +.Fn ck_ring_enqueue_spsc 3 +function enqueues the pointer +.Fa entry +into the bounded buffer pointed to by +.Fa ring +in FIFO fashion. +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa entry . +This function is safe to call without locking for up to +one concurrent invocation of +.Fn ck_ring_dequeue_spsc 3 . +This function provides wait-free progress +guarantees. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_ring.h> + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + +void +enqueue(void) +{ + void *entry = some_object; + + /* Attempt to enqueue pointer to some_object into buffer. */ + if (ck_ring_enqueue_spsc(&ring, &buffer, &entry) == false) { + /* + * The buffer was full and the enqueue operation + * has failed. + */ + return; + } + + /* Enqueue operation completed successfully. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the value of +.Fa entry +was successfully enqueued into +.Fa ring . +The function will return false if the value of +.Fa entry +could not be enqueued which only occurs if +.Fa ring +was full. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_enqueue_spsc_size b/doc/ck_ring_enqueue_spsc_size new file mode 100644 index 0000000..7048ea1 --- /dev/null +++ b/doc/ck_ring_enqueue_spsc_size @@ -0,0 +1,128 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_ENQUEUE_SPSC_SIZE 3 +.Sh NAME +.Nm ck_ring_enqueue_spsc_size +.Nd enqueue pointer into bounded FIFO and return size of buffer +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_enqueue_spsc_size "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *entry" "unsigned int *size" +.Sh DESCRIPTION +The +.Fn ck_ring_enqueue_spsc_size 3 +function enqueues the pointer +.Fa entry +into the bounded buffer pointed to by +.Fa ring +in FIFO fashion. +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa entry . +This function is safe to call without locking for up to +one concurrent invocation of +.Fn ck_ring_dequeue_spsc 3 . +This function provides wait-free progress +guarantees. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_ring.h> + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + +void +enqueue(void) +{ + void *entry = some_object; + unsigned int length; + + /* Attempt to enqueue pointer to some_object into buffer. */ + if (ck_ring_enqueue_spsc(&ring, &buffer, &entry, &length) == false) { + /* + * The buffer was full and the enqueue operation + * has failed. + */ + return; + } + + /* + * If buffer length was 100 items or more at the time entry was + * enqueued, do something. + */ + if (length > 100) { + do_something; + } + + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the value of +.Fa entry +was successfully enqueued into +.Fa ring . +This function will return the number of items +in +.Fa ring +with respect to the linearization point (the +point in item that +.Fa entry +is enqueued). +The function will return false if the value of +.Fa entry +could not be enqueued which only occurs if +.Fa ring +was full. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_init b/doc/ck_ring_init new file mode 100644 index 0000000..914d1bb --- /dev/null +++ b/doc/ck_ring_init @@ -0,0 +1,62 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_INIT 3 +.Sh NAME +.Nm ck_ring_init +.Nd initialize bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft void +.Fn ck_ring_init "ck_ring_t *ring" "unsigned int size" +.Sh DESCRIPTION +The +.Fn ck_ring_init +function initializes a bounded FIFO buffer pointed to by +.Fa ring +for the storage of up to +.Fa size +number of pointers. +The +.Fa size +argument must be a power-of-two greater than or equal to 4. +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_size b/doc/ck_ring_size new file mode 100644 index 0000000..7ec69f4 --- /dev/null +++ b/doc/ck_ring_size @@ -0,0 +1,55 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_SIZE 3 +.Sh NAME +.Nm ck_ring_size +.Nd return number of pointers enqueued in bounded FIFO +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft unsigned int +.Fn ck_ring_size "ck_ring_t *ring" +.Sh DESCRIPTION +The +.Fn ck_ring_size 3 +function returns the number of pointers currently +enqueued in the buffer pointed to by +.Fa ring . +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_trydequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_ring_trydequeue_spmc b/doc/ck_ring_trydequeue_spmc new file mode 100644 index 0000000..16f83ee --- /dev/null +++ b/doc/ck_ring_trydequeue_spmc @@ -0,0 +1,126 @@ +.\" +.\" 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 April 20, 2013 +.Dt CK_RING_TRYDEQUEUE_SPMC 3 +.Sh NAME +.Nm ck_ring_trydequeue_spmc +.Nd dequeue from bounded FIFO and allow for spurious failure +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_ring.h +.Ft bool +.Fn ck_ring_trydequeue_spmc "ck_ring_t *ring" "ck_ring_buffer_t *buffer" "void *result" +.Sh DESCRIPTION +The +.Fn ck_ring_trydequeue_spmc 3 +function attempts to dequeue a pointer from the bounded buffer +pointed to by +.Fa ring +in FIFO fashion. The pointer is stored in the pointer +pointed to by +.Fa result . +The buffer pointed to by +.Fa buffer +must be unique to +.Fa ring +and point to an array of ck_ring_buffer_t of sufficient +length (according to the power-of-2 elements in the buffer). +The decoupling of the ring from the buffer serves +to address use-cases involving multiple address spaces +and DMA, among others. +If you are on non-POSIX platforms or wish for strict +compliance with C, then it is recommended to pass a +pointer of type void ** for +.Fa result . +This function is safe to call without locking for UINT_MAX +concurrent +.Fn ck_ring_dequeue_spmc 3 +or +.Fn ck_ring_trydequeue_spmc 3 +invocations and up to one concurrent +.Fn ck_ring_enqueue_spmc 3 +or +.Fn ck_ring_tryenqueue_spmc 3 +invocation. This operation will always complete +in a bounded number of steps. It is +possible for the function to return false even +if +.Fa ring +is non-empty. This +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_ring.h> + +/* This ring was previously initialized with ck_ring_init. */ +ck_ring_t ring; + +/* The ring was initialized for 1023 elements. */ +ck_ring_buffer_t buffer[1024]; + +void +dequeue(void) +{ + void *result; + + /* Dequeue from ring until contention is actively observed. */ + while (ck_ring_trydequeue_spmc(&ring, &buffer, &result) == true) { + /* + * Results contains the oldest pointer in ring + * since the dequeue operation returned true. + */ + operation(result); + } + + /* An empty ring was encountered, leave. */ + return; +} +.Ed +.Sh RETURN VALUES +The function returns true if the dequeue operation +completely successfully in a bounded number of steps. +The result of the dequeue operation is stored in the +value pointed to by +.Fa result . +Otherwise, the function will return false if the buffer was empty +or if the operation could not be completed in a bounded +number of steps. If the function returns false, then the contents +of +.Fa result +are undefined. +.Sh SEE ALSO +.Xr ck_ring_init 3 , +.Xr ck_ring_dequeue_spmc 3 , +.Xr ck_ring_enqueue_spmc 3 , +.Xr ck_ring_enqueue_spmc_size 3 , +.Xr ck_ring_dequeue_spsc 3 , +.Xr ck_ring_enqueue_spsc 3 , +.Xr ck_ring_enqueue_spsc_size 3 , +.Xr ck_ring_capacity 3 , +.Xr ck_ring_size 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_rwcohort b/doc/ck_rwcohort new file mode 100644 index 0000000..ba2b5f9 --- /dev/null +++ b/doc/ck_rwcohort @@ -0,0 +1,203 @@ +.\" +.\" Copyright 2013 Brendon Scheinman. +.\" 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 April 23, 2013. +.Dt ck_rwcohort 3 +.Sh NAME +.Nm ck_rwcohort +.Nd generalized interface for reader-writer locks using cohort locks +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rwcohort.h +In each of the following macros, "STRATEGY" should be replaced with either "NEUTRAL", "RP", or "WP" +depending on which locking strategy the user prefers. RP and WP represent reader preference and +writer preference, respectively, while NEUTRAL represents a strategy neutral to reads vs. writes. +.Fn CK_RWCOHORT_STRATEGY_PROTOTYPE "COHORT_NAME cohort_name" +.Fn CK_RWCOHORT_STRATEGY_NAME "COHORT_NAME cohort_name" +.Fn CK_RWCOHORT_STRATEGY_INSTANCE "COHORT_NAME cohort_name" +.Fn CK_RWCOHORT_STRATEGY_INIT "COHORT_NAME cohort_name" "RWCOHORT lock" "unsigned int wait_limit" +Note: the wait_limit argument should be omitted for locks using the neutral strategy +.Fn CK_RWCOHORT_STRATEGY_READ_LOCK "COHORT_NAME cohort_name" "RWCOHORT lock" "COHORT cohort" \ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_STRATEGY_READ_UNLOCK "COHORT_NAME cohort_name" "RWCOHORT lock" "COHORT cohort" \ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_STRATEGY_WRITE_LOCK "COHORT_NAME cohort_name" "RWCOHORT lock" "COHORT cohort" \ +"void *global_context" "void *local_context" +.Fn CK_RWCOHORT_STRATEGY_WRITE_UNLOCK "COHORT_NAME cohort_name" "RWCOHORT lock" "COHORT cohort" \ +"void *global_context" "void *local_context" +.Pp +Arguments of type RWCOHORT must be pointers to structs defined using the +.Xr CK_RWCOHORT_STRATEGY_PROTOTYPE 3 +macro with the same strategy and cohort name as the current call. +.Pp +Arguments of type COHORT must be pointers to structs defined using the +.Xr CK_COHORT_PROTOTYPE 3 +macro. +.Sh DESCRIPTION +ck_rwcohort.h provides an interface for defining reader-writer locks +that use cohort locks internally to increase performance on NUMA +architectures. See +.Xr ck_cohort 3 +for more information about cohort locks. +.Pp +Before using a reader-writer cohort lock, the user must define a cohort type using +either the +.Xr CK_COHORT_PROTOTYPE 3 +or the +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 +macros, and define a reader-writer lock type using the +.Xr CK_RWCOHORT_PROTOTYPE 3 +macro. +.Pp +.Sh EXAMPLE +.Bd -literal -offset indent +#include <stdlib.h> +#include <pthread.h> + +#include <ck_pr.h> +#include <ck_cohort.h> +#include <ck_rwcohort.h> +#include <ck_spinlock.h> + +/* Create cohort methods with signatures that match the required signature */ + +static void +ck_spinlock_lock_with_context(ck_spinlock_t *lock, void *context) +{ + (void)context; + ck_spinlock_lock(lock); + return; +} + +static void +ck_spinlock_unlock_with_context(ck_spinlock_t *lock, void *context) +{ + (void)context; + ck_spinlock_unlock(lock); + return; +} + +static bool +ck_spinlock_locked_with_context(ck_spinlock_t *lock, void *context) +{ + (void)context; + return ck_spinlock_locked(lock); +} + +/* + * define a cohort type named "test_cohort" that will use + * the above methods for both its global and local locks + */ +CK_COHORT_PROTOTYPE(test_cohort, + ck_spinlock_lock_with_context, ck_spinlock_unlock_with_context, ck_spinlock_locked_with_context, + ck_spinlock_lock_with_context, ck_spinlock_unlock_with_context, ck_spinlock_locked_with_context) + +/* define a reader-writer type using the same cohort type */ +CK_RWCOHORT_WP_PROTOTYPE(test_cohort) + +static ck_spinlock_t global_lock = CK_SPINLOCK_INITIALIZER; +static CK_COHORT_INSTANCE(test_cohort) *cohorts; +static CK_RWCOHORT_WP_INSTANCE(test_cohort) rw_cohort = CK_RWCOHORT_WP_INITIALIZER; +static unsigned int ready; + +static void * +function(void *context) +{ + CK_COHORT_INSTANCE(test_cohort) *cohort = context; + + while (ck_pr_load_uint(&ready) == 0); + + while (ck_pr_load_uint(&ready) > 0) { + /* + * acquire the cohort lock before performing critical section. + * note that we pass NULL for both the global and local context + * arguments because neither the lock nor unlock functions + * will use them. + */ + CK_COHORT_LOCK(test_cohort, cohort, NULL, NULL); + + /* perform critical section */ + + /* relinquish cohort lock */ + CK_COHORT_UNLOCK(test_cohort, cohort, NULL, NULL); + } + + return NULL; +} + +int +main(void) +{ + unsigned int nthr = 4; + unsigned int n_cohorts = 2; + unsigned int i; + + /* allocate 2 cohorts of the defined type */ + CK_COHORT_INSTANCE(test_cohort) *cohorts = + calloc(n_cohorts, sizeof(CK_COHORT_INSTANCE(test_cohort))); + + /* create local locks to use with each cohort */ + ck_spinlock_t *local_locks = + calloc(n_cohorts, sizeof(ck_spinlock_t)); + + pthread_t *threads = + calloc(nthr, sizeof(pthread_t)); + + /* initialize each of the cohorts before using them */ + for (i = 0 ; i < n_cohorts ; ++i) { + CK_COHORT_INIT(test_cohort, cohorts + i, &global_lock, local_locks + i, + CK_COHORT_DEFAULT_LOCAL_PASS_LIMIT); + } + + /* start each thread and assign cohorts equally */ + for (i = 0 ; i < nthr ; ++i) { + pthread_create(threads + i, NULL, function, cohorts + (i % n_cohorts)); + } + + ck_pr_store_uint(&ready, 1); + sleep(10); + ck_pr_store_uint(&ready, 0); + + for (i = 0 ; i < nthr ; ++i) { + pthread_join(threads[i], NULL); + } + + return 0; +} +.Ed +.Sh SEE ALSO +.Xr CK_COHORT_PROTOTYPE 3 , +.Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 , +.Xr CK_COHORT_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_rwlock b/doc/ck_rwlock new file mode 100644 index 0000000..60a18ab --- /dev/null +++ b/doc/ck_rwlock @@ -0,0 +1,143 @@ +.\" +.\" 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 26, 2013. +.Dt ck_rwlock 3 +.Sh NAME +.Nm ck_rwlock_init , +.Nm ck_rwlock_write_lock , +.Nm ck_rwlock_write_unlock , +.Nm ck_rwlock_write_trylock , +.Nm ck_rwlock_write_downgrade , +.Nm ck_rwlock_locked_writer , +.Nm ck_rwlock_read_lock , +.Nm ck_rwlock_read_trylock , +.Nm ck_rwlock_read_unlock , +.Nm ck_rwlock_locked_reader , +.Nm ck_rwlock_recursive_write_lock , +.Nm ck_rwlock_recursive_write_trylock , +.Nm ck_rwlock_recurisve_write_unlock , +.Nm ck_rwlock_recursive_read_lock , +.Nm ck_rwlock_recursive_read_trylock , +.Nm ck_rwlock_recursive_read_unlock +.Nd centralized write-biased reader-writer locks +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_rwlock.h +.Pp +.Dv ck_rwlock_t lock = CK_RWLOCK_INITIALIZER; +.Pp +.Ft void +.Fn ck_rwlock_init "ck_rwlock_t *lock" +.Ft void +.Fn ck_rwlock_write_lock "ck_rwlock_t *lock" +.Ft void +.Fn ck_rwlock_write_unlock "ck_rwlock_t *lock" +.Ft bool +.Fn ck_rwlock_write_trylock "ck_rwlock_t *lock" +.Ft bool +.Fn ck_rwlock_write_downgrade "ck_rwlock_t *lock" +.Ft bool +.Fn ck_rwlock_locked_writer "ck_rwlock_t *lock" +.Ft void +.Fn ck_rwlock_read_lock "ck_rwlock_t *lock" +.Ft bool +.Fn ck_rwlock_read_trylock "ck_rwlock_t *lock" +.Ft void +.Fn ck_rwlock_read_unlock "ck_rwlock_t *lock" +.Ft bool +.Fn ck_rwlock_locked_reader "ck_rwlock_t *lock" +.Pp +.Dv ck_rwlock_recursive_t lock = CK_RWLOCK_RECURSIVE_INITIALIZER; +.Pp +.Ft void +.Fn ck_rwlock_recursive_write_lock "ck_rwlock_recursive_t *lock" "unsigned int tid" +.Ft bool +.Fn ck_rwlock_recursive_write_trylock "ck_rwlock_recursive_t *lock" "unsigned int tid" +.Ft void +.Fn ck_rwlock_recurisve_write_unlock "ck_rwlock_recursive_t *lock" +.Ft void +.Fn ck_rwlock_recursive_read_lock "ck_rwlock_recursive_t *lock" +.Ft bool +.Fn ck_rwlock_recursive_read_trylock "ck_rwlock_recursive_t *lock" +.Ft void +.Fn ck_rwlock_recursive_read_unlock "ck_rwlock_recursive_t *lock" +.Sh DESCRIPTION +This is a centralized write-biased reader-writer lock. It +requires very little space overhead and has a low latency +fast path. Write-side recursion requires usage of ck_rwlock_recursive. +Read-side recursion is disallowed. The +.Fn ck_rwlock_write_downgrade +function degrades the caller's write-side acquisition to a read-side +acquisition without forfeit of current critical section. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_rwlock.h> + +static ck_rwlock_t lock = CK_RWLOCK_INITIALIZER; + +static void +reader(void) +{ + + for (;;) { + ck_rwlock_read_lock(&lock); + /* Read-side critical section. */ + ck_rwlock_read_unlock(&lock); + + if (ck_rwlock_read_trylock(&lock) == true) { + /* Read-side critical section. */ + ck_rwlock_read_unlock(&lock); + } + } + + return; +} + +static void +writer(void) +{ + + for (;;) { + ck_rwlock_write_lock(&lock); + /* Write-side critical section. */ + ck_rwlock_write_unlock(&lock); + + if (ck_rwlock_write_trylock(&lock, 1) == true) { + /* Write-side critical section. */ + ck_rwlock_write_unlock(&lock); + } + } + + return; +} +.Ed +.Sh SEE ALSO +.Xr ck_brlock 3 , +.Xr ck_elide 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_sequence b/doc/ck_sequence new file mode 100644 index 0000000..faa1631 --- /dev/null +++ b/doc/ck_sequence @@ -0,0 +1,144 @@ +.\" +.\" 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 26, 2013. +.Dt ck_sequence 3 +.Sh NAME +.Nm ck_sequence_init , +.Nm ck_sequence_read_begin , +.Nm ck_sequence_read_retry , +.Nm ck_sequence_write_begin , +.Nm ck_sequence_write_end +.Nd sequence locks +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_sequence.h +.Pp +.Dv ck_sequence_t seqlock = CK_SEQUENCE_INITIALIZER; +.Pp +.Ft void +.Fn ck_sequence_init "ck_sequence_t *sq" +.Ft unsigned int +.Fn ck_sequence_read_begin "const ck_sequence_t *sq" +.Ft bool +.Fn ck_sequence_read_retry "const ck_sequence_t *sq" "unsigned int version" +.Ft void +.Fn ck_sequence_write_begin "ck_sequence_t *sq" +.Ft void +.Fn ck_sequence_write_end "ck_sequence_t *sq" +.Sh DESCRIPTION +It is recommended to use ck_sequence when a small amount of data that cannot be +accessed atomically has to be synchronized with readers in a fashion that does +not block any writer. Readers are able to execute their read-side critical +sections without any atomic operations. A ck_sequence_t must be initialized +before use. It may be initialized using either a static initializer +(CK_SEQUENCE_INITIALIZER) or using +.Fn ck_sequence_init . +Before readers attempt to +read data that may be concurrently modified they must first save the return +value of +.Fn ck_sequence_read_begin . +While or after a reader has completed copying +the data associated with a ck_sequence_t it must pass the earlier return value +of +.Fn ck_sequence_read_begin +to +.Fn "ck_sequence_read_retry". If +.Fn ck_sequence_read_retry +returns true then the copy of data may be inconsistent and the read process +must be retried. Writers must rely on their own synchronization primitives. +Once a writer has entered its respective critical section, it must call +.Fn ck_sequence_write_begin +to signal intent to update the data protected +by the ck_sequence_t. Before the writer leaves its critical section it must +execute +.Fn ck_sequence_write_end +to indicate that the updates have left respective objects in a consistent state. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_sequence.h> +#include <stdlib.h> + +static struct example { + int a; + int b; + int c; +} global; + +static ck_sequence_t seqlock = CK_SEQUENCE_INITIALIZER; + +void +reader(void) +{ + struct example copy; + unsigned int version; + + /* + * Attempt a read of the data structure. If the structure + * has been modified between ck_sequence_read_begin and + * ck_sequence_read_retry then attempt another read since + * the data may be in an inconsistent state. + */ + do { + version = ck_sequence_read_begin(&seqlock); + copy = global; + } while (ck_sequence_read_retry(&seqlock, version)); + + /* + * The previous may also be expressed using CK_SEQUENCE_READ. + * Generally recommend to only use ck_sequence_read_retry + * if you would like to detect a conflicting write at some + * higher granularity. + */ + CK_SEQUENCE_READ(&seqlock, &version) { + copy = global; + } + + return; +} + +void +writer(void) +{ + + for (;;) { + ck_sequence_write_begin(&seqlock); + global.a = rand(); + global.b = global.a + global.b; + global.c = global.b + global.c; + ck_sequence_write_end(&seqlock); + } + + return; +} +.Ed +.Sh SEE ALSO +.Xr ck_brlock 3 , +.Xr ck_bytelock 3 , +.Xr ck_rwlock 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_spinlock b/doc/ck_spinlock new file mode 100644 index 0000000..564d185 --- /dev/null +++ b/doc/ck_spinlock @@ -0,0 +1,259 @@ +.\" +.\" 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 26, 2013. +.Dt ck_spinlock 3 +.Sh NAME +.Nm ck_spinlock_init , +.Nm ck_spinlock_lock , +.Nm ck_spinlock_unlock , +.Nm ck_spinlock_locked , +.Nm ck_spinlock_trylock , +.Nm ck_spinlock_anderson_init , +.Nm ck_spinlock_anderson_locked , +.Nm ck_spinlock_anderson_lock , +.Nm ck_spinlock_anderson_unlock , +.Nm ck_spinlock_cas_init , +.Nm ck_spinlock_cas_locked , +.Nm ck_spinlock_cas_lock , +.Nm ck_spinlock_cas_lock_eb , +.Nm ck_spinlock_cas_trylock , +.Nm ck_spinlock_cas_unlock , +.Nm ck_spinlock_clh_init , +.Nm ck_spinlock_clh_locked , +.Nm ck_spinlock_clh_lock , +.Nm ck_spinlock_clh_unlock , +.Nm ck_spinlock_dec_init , +.Nm ck_spinlock_dec_locked , +.Nm ck_spinlock_dec_lock , +.Nm ck_spinlock_dec_lock_eb , +.Nm ck_spinlock_dec_trylock , +.Nm ck_spinlock_dec_unlock , +.Nm ck_spinlock_fas_init , +.Nm ck_spinlock_fas_lock , +.Nm ck_spinlock_fas_lock_eb , +.Nm ck_spinlock_fas_locked , +.Nm ck_spinlock_fas_trylock , +.Nm ck_spinlock_fas_unlock , +.Nm ck_spinlock_hclh_init , +.Nm ck_spinlock_hclh_locked , +.Nm ck_spinlock_hclh_lock , +.Nm ck_spinlock_hclh_unlock , +.Nm ck_spinlock_mcs_init , +.Nm ck_spinlock_mcs_locked , +.Nm ck_spinlock_mcs_lock , +.Nm ck_spinlock_mcs_trylock , +.Nm ck_spinlock_mcs_unlock , +.Nm ck_spinlock_ticket_init , +.Nm ck_spinlock_ticket_locked , +.Nm ck_spinlock_ticket_lock , +.Nm ck_spinlock_ticket_lock_pb , +.Nm ck_spinlock_ticket_trylock , +.Nm ck_spinlock_ticket_unlock +.Nd spinlock implementations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_spinlock.h +.Pp +.Dv ck_spinlock_t spinlock = CK_SPINLOCK_INITIALIZER; +.Ft void +.Fn ck_spinlock_init "ck_spinlock_t *lock" +.Ft void +.Fn ck_spinlock_lock "ck_spinlock_t *lock" +.Ft void +.Fn ck_spinlock_unlock "ck_spinlock_t *lock" +.Ft bool +.Fn ck_spinlock_locked "ck_spinlock_t *lock" +.Ft bool +.Fn ck_spinlock_trylock "ck_spinlock_t *lock" +.Ft void +.Fn ck_spinlock_anderson_init "ck_spinlock_anderson_t *lock" "ck_spinlock_anderson_thread_t *slots" "unsigned int count" +.Ft bool +.Fn ck_spinlock_anderson_locked "ck_spinlock_anderson_t *lock" +.Ft void +.Fn ck_spinlock_anderson_lock "ck_spinlock_anderson_t *lock" "ck_spinlock_anderson_thread_t **slot" +.Ft void +.Fn ck_spinlock_anderson_unlock "ck_spinlock_anderson_t *lock" "ck_spinlock_anderson_thread_t *slot" +.Pp +.Dv ck_spinlock_cas_t spinlock = CK_SPINLOCK_CAS_INITIALIZER; +.Ft void +.Fn ck_spinlock_cas_init "ck_spinlock_cas_t *lock" +.Ft bool +.Fn ck_spinlock_cas_locked "ck_spinlock_cas_t *lock" +.Ft void +.Fn ck_spinlock_cas_lock "ck_spinlock_cas_t *lock" +.Ft void +.Fn ck_spinlock_cas_lock_eb "ck_spinlock_cas_t *lock" +.Ft bool +.Fn ck_spinlock_cas_trylock "ck_spinlock_cas_t *lock" +.Ft void +.Fn ck_spinlock_cas_unlock "ck_spinlock_cas_t *lock" +.Ft void +.Fn ck_spinlock_clh_init "ck_spinlock_clh_t **lock" "ck_spinlock_clh_t *unowned" +.Ft bool +.Fn ck_spinlock_clh_locked "ck_spinlock_clh_t **lock" +.Ft void +.Fn ck_spinlock_clh_lock "ck_spinlock_clh_t **lock" "ck_spinlock_clh_t *node" +.Ft void +.Fn ck_spinlock_clh_unlock "ck_spinlock_clh_t **node" +.Pp +.Dv ck_spinlock_dec_t spinlock = CK_SPINLOCK_DEC_INITIALIZER; +.Ft void +.Fn ck_spinlock_dec_init "ck_spinlock_dec_t *lock" +.Ft bool +.Fn ck_spinlock_dec_locked "ck_spinlock_dec_t *lock" +.Ft void +.Fn ck_spinlock_dec_lock "ck_spinlock_dec_t *lock" +.Ft void +.Fn ck_spinlock_dec_lock_eb "ck_spinlock_dec_t *lock" +.Ft bool +.Fn ck_spinlock_dec_trylock "ck_spinlock_dec_t *lock" +.Ft void +.Fn ck_spinlock_dec_unlock "ck_spinlock_dec_t *lock" +.Pp +.Dv ck_spinlock_fas_t spinlock = CK_SPINLOCK_FAS_INITIALIZER; +.Ft void +.Fn ck_spinlock_fas_init "ck_spinlock_fas_t *lock" +.Ft void +.Fn ck_spinlock_fas_lock "ck_spinlock_fas_t *lock" +.Ft void +.Fn ck_spinlock_fas_lock_eb "ck_spinlock_fas_t *lock" +.Ft bool +.Fn ck_spinlock_fas_locked "ck_spinlock_fas_t *lock" +.Ft bool +.Fn ck_spinlock_fas_trylock "ck_spinlock_fas_t *lock" +.Ft void +.Fn ck_spinlock_fas_unlock "ck_spinlock_fas_t *lock" +.Pp +.Ft void +.Fn ck_spinlock_hclh_init "ck_spinlock_hclh_t **lock" "ck_spinlock_hclh_t *unowned" +.Ft bool +.Fn ck_spinlock_hclh_locked "ck_spinlock_hclh_t **lock" +.Ft void +.Fn ck_spinlock_hclh_lock "ck_spinlock_hclh_t **lock" "ck_spinlock_hclh_t *node" +.Ft void +.Fn ck_spinlock_hclh_unlock "ck_spinlock_hclh_t **node" +.Pp +.Dv ck_spinlock_mcs_t spinlock = CK_SPINLOCK_MCS_INITIALIZER; +.Ft void +.Fn ck_spinlock_mcs_init "ck_spinlock_mcs_t **lock" +.Ft bool +.Fn ck_spinlock_mcs_locked "ck_spinlock_mcs_t **lock" +.Ft void +.Fn ck_spinlock_mcs_lock "ck_spinlock_mcs_t **lock" "ck_spinlock_mcs_t *node" +.Ft bool +.Fn ck_spinlock_mcs_trylock "ck_spinlock_mcs_t **lock" "ck_spinlock_mcs_t *node" +.Ft void +.Fn ck_spinlock_mcs_unlock "ck_spinlock_mcs_t **lock" "ck_spinlock_mcs_t *node" +.Pp +.Dv ck_spinlock_ticket_t spinlock = CK_SPINLOCK_TICKET_INITIALIZER; +.Ft void +.Fn ck_spinlock_ticket_init "ck_spinlock_ticket_t *lock" +.Ft bool +.Fn ck_spinlock_ticket_locked "ck_spinlock_ticket_t *lock" +.Ft void +.Fn ck_spinlock_ticket_lock "ck_spinlock_ticket_t *lock" +.Ft void +.Fn ck_spinlock_ticket_lock_pb "ck_spinlock_ticket_t *lock" "unsigned int period" +.Ft bool +.Fn ck_spinlock_ticket_trylock "ck_spinlock_ticket_t *lock" +.Ft void +.Fn ck_spinlock_ticket_unlock "ck_spinlock_ticket_t *lock" +.Sh DESCRIPTION +A family of busy-wait spinlock implementations. The ck_spinlock_t implementation is simply +a wrapper around the fetch-and-swap (ck_spinlock_fas_t) implementation. The table below +provides a summary of the current implementations. +.Bd -literal +| Namespace | Algorithm | Type | Restrictions | Fair | +\'----------------------|-----------------------------|---------------|-------------------------|--------' + ck_spinlock_anderson Anderson Array Fixed number of threads Yes + ck_spinlock_cas Compare-and-Swap Centralized None No + ck_spinlock_clh Craig, Landin and Hagersten Queue Lifetime requirements Yes + ck_spinlock_dec Decrement (Linux kernel) Centralized UINT_MAX concurrency No + ck_spinlock_fas Fetch-and-store Centralized None No + ck_spinlock_hclh Hierarchical CLH Queue Lifetime requirements Yes * + ck_spinlock_mcs Mellor-Crummey and Scott Queue None Yes + ck_spinlock_ticket Ticket Centralized None Yes +.Ed +.Pp +* Hierarchical CLH only offers weak fairness for threads accross cluster +nodes. +.Pp +If contention is low and there is no hard requirement for starvation-freedom +then a centralized greedy (unfair) spinlock is recommended. If contention is +high and there is no requirement for starvation-freedom then a centralized +greedy spinlock is recommended to be used with an exponential backoff +mechanism. If contention is generally low and there is a hard requirement for +starvation-freedom then the ticket lock is recommended. If contention is high +and there is a hard requirement for starvation-freedom then the Craig and +Landin and Hagersten queue spinlock is recommended unless stack allocation is +necessary or NUMA factor is high, in which case the Mellor-Crummey and Scott +spinlock is recommended. If you cannot afford O(n) space-usage from array +or queue spinlocks but still require fairness under high contention then +the ticket lock with proportional back-off is recommended. +If NUMA factor is high but prefer a greedy lock, then please see +.Xr ck_cohort 3 . +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_spinlock.h> +#include <stdbool.h> + +/* + * Alternatively, the mutex may be initialized at run-time with + * ck_spinlock_init(&mutex). + */ +ck_spinlock_t mutex = CK_SPINLOCK_INITIALIZER; + +void +example(void) +{ + + ck_spinlock_lock(&mutex); + /* + * Critical section. + */ + ck_spinlock_unlock(&mutex); + + ck_spinlock_lock_eb(&mutex); + /* + * Critical section. + */ + ck_spinlock_unlock(&mutex); + + if (ck_spinlock_trylock(&mutex) == true) { + /* + * Critical section. + */ + ck_spinlock_unlock(&mutex); + } +} +.Ed +.Sh SEE ALSO +.Xr ck_cohort 3 , +.Xr ck_elide 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_swlock b/doc/ck_swlock new file mode 100644 index 0000000..e101334 --- /dev/null +++ b/doc/ck_swlock @@ -0,0 +1,138 @@ +.\" +.\" Copyright 2014 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 April 22, 2014. +.Dt ck_swlock 3 +.Sh NAME +.Nm ck_swlock_init , +.Nm ck_swlock_write_latch , +.Nm ck_swlock_write_unlatch , +.Nm ck_swlock_write_lock , +.Nm ck_swlock_write_unlock , +.Nm ck_swlock_write_trylock , +.Nm ck_swlock_write_downgrade , +.Nm ck_swlock_locked_writer , +.Nm ck_swlock_read_lock , +.Nm ck_swlock_read_trylock , +.Nm ck_swlock_read_unlock , +.Nm ck_swlock_locked_reader +.Nd centralized copy-safe write-biased single-writer read-write locks +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_swlock.h +.Pp +.Dv ck_swlock_t lock = CK_SWLOCK_INITIALIZER; +.Pp +.Ft void +.Fn ck_swlock_init "ck_swlock_t *lock" +.Ft void +.Fn ck_swlock_write_lock "ck_swlock_t *lock" +.Ft void +.Fn ck_swlock_write_unlock "ck_swlock_t *lock" +.Ft void +.Fn ck_swlatch_write_latch "ck_swlatch_t *latch" +.Ft void +.Fn ck_swlatch_write_unlatch "ck_swlatch_t *latch" +.Ft bool +.Fn ck_swlock_write_trylock "ck_swlock_t *lock" +.Ft bool +.Fn ck_swlock_write_downgrade "ck_swlock_t *lock" +.Ft bool +.Fn ck_swlock_locked_writer "ck_swlock_t *lock" +.Ft void +.Fn ck_swlock_read_lock "ck_swlock_t *lock" +.Ft bool +.Fn ck_swlock_read_trylock "ck_swlock_t *lock" +.Ft void +.Fn ck_swlock_read_unlock "ck_swlock_t *lock" +.Ft bool +.Fn ck_swlock_locked_reader "ck_swlock_t *lock" +.Sh DESCRIPTION +This is a centralized write-biased single-writer reader-writer lock. It +requires half the space that ck_rwlock does and has a low latency +fast path. The lock supports latch and unlatch operations that +allow it to be used in a copy-safe manner (reader-bits may be +over-written safely). +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_swlock.h> + +static ck_swlock_t lock = CK_SWLOCK_INITIALIZER; + +static void +reader(void) +{ + + for (;;) { + ck_swlock_read_lock(&lock); + /* Read-side critical section. */ + ck_swlock_read_unlock(&lock); + + if (ck_swlock_read_trylock(&lock) == true) { + /* Read-side critical section. */ + ck_swlock_read_unlock(&lock); + } + } + + return; +} + +static void +writer(void) +{ + ck_swlock_t contrived; + + for (;;) { + ck_swlock_write_lock(&lock); + /* Write-side critical section. */ + ck_swlock_write_unlock(&lock); + + if (ck_swlock_write_trylock(&lock) == true) { + /* Write-side critical section. */ + ck_swlock_write_unlock(&lock); + } + + ck_swlock_write_latch(&lock); + /* Write-side critical section. */ + + /* This is safe to do with-in a latch. */ + contrived = lock; + lock = contrived; + ck_swlock_write_unlatch(&lock); + } + + return; +} +.Ed +.Sh SEE ALSO +.Xr ck_brlock 3 , +.Xr ck_elide 3 , +.Xr ck_pflock 3 , +.Xr ck_rwlock 3 , +.Xr ck_tflock 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_tflock b/doc/ck_tflock new file mode 100644 index 0000000..629dbd4 --- /dev/null +++ b/doc/ck_tflock @@ -0,0 +1,95 @@ +.\" +.\" Copyright 2014 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 April 22, 2014. +.Dt ck_tflock 3 +.Sh NAME +.Nm ck_tflock_ticket_init , +.Nm ck_tflock_ticket_write_lock , +.Nm ck_tflock_ticket_write_unlock , +.Nm ck_tflock_ticket_read_lock , +.Nm ck_tflock_ticket_read_unlock , +.Nd centralized task-fair reader-writer locks +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_tflock.h +.Pp +.Dv ck_tflock_ticket_t lock = CK_TFLOCK_TICKET_INITIALIZER; +.Pp +.Ft void +.Fn ck_tflock_ticket_init "ck_tflock_ticket_t *lock" +.Ft void +.Fn ck_tflock_ticket_write_lock "ck_tflock_ticket_t *lock" +.Ft void +.Fn ck_tflock_ticket_write_unlock "ck_tflock_ticket_t *lock" +.Ft void +.Fn ck_tflock_ticket_read_lock "ck_tflock_ticket_t *lock" +.Ft void +.Fn ck_tflock_ticket_read_unlock "ck_tflock_ticket_t *lock" +.Sh DESCRIPTION +This is a centralized task-fair reader-writer lock. It +requires little space overhead and has a low latency +fast path. +.Sh EXAMPLE +.Bd -literal -offset indent +#include <ck_tflock.h> + +static ck_tflock_ticket_t lock = CK_TFLOCK_INITIALIZER; + +static void +reader(void) +{ + + for (;;) { + ck_tflock_ticket_read_lock(&lock); + /* Read-side critical section. */ + ck_tflock_ticket_read_unlock(&lock); + } + + return; +} + +static void +writer(void) +{ + + for (;;) { + ck_tflock_ticket_write_lock(&lock); + /* Write-side critical section. */ + ck_tflock_ticket_write_unlock(&lock); + } + + return; +} +.Ed +.Sh SEE ALSO +.Xr ck_brlock 3 , +.Xr ck_rwlock 3 , +.Xr ck_pflock 3 , +.Xr ck_swlock 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/refcheck.pl b/doc/refcheck.pl new file mode 100755 index 0000000..1ed3a65 --- /dev/null +++ b/doc/refcheck.pl @@ -0,0 +1,27 @@ +#!/usr/bin/perl + +use warnings; +use strict; + +my @files = @ARGV; + +my $h; + +foreach my $file (@files) { + $h->{$file} = 1; +} + +foreach my $file (@files) { + open(my $fh, "<", $file) or die "cannot open < $file: $!"; + while (<$fh>) { + chomp; + if ($_ =~ /\.Xr ((ck|CK)_[a-zA-Z_]+) ([0-9])/) { + my $name = $1; + my $section = $3; + if (!$h->{$name}) { + print STDERR "$file: ref to missing ${name}($section)\n"; + } + } + } + close($fh) or die("cannot close $file: $!"); +} |