diff --git a/doc/CK_COHORT_INIT b/doc/CK_COHORT_INIT new file mode 100644 index 0000000..60b3f75 --- /dev/null +++ b/doc/CK_COHORT_INIT @@ -0,0 +1,66 @@ +.\" +.\" Copyright 2013 Samy Al Bahra. +.\" 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 an 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. +Cohort instances do not allocate any new memory during initialization, so they +can be freed later without using an explicit dispose method. +.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_LOCK 3 , +.Xr CK_COHORT_UNLOCK 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..9ed728d --- /dev/null +++ b/doc/CK_COHORT_INSTANCE @@ -0,0 +1,57 @@ +.\" +.\" Copyright 2013 Samy Al Bahra. +.\" 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_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 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..6d3af0c --- /dev/null +++ b/doc/CK_COHORT_LOCK @@ -0,0 +1,59 @@ +.\" +.\" Copyright 2013 Samy Al Bahra. +.\" 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 a cohort's locks +.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_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_UNLOCK 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..2e559cb --- /dev/null +++ b/doc/CK_COHORT_PROTOTYPE @@ -0,0 +1,86 @@ +.\" +.\" Copyright 2013 Samy Al Bahra. +.\" 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 a cohort type with the given 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" +.Pp +where LOCK_FXN refers to a method with the signature +.br +void(void *lock, void *context) +.Pp +The +.Fa context +argument is used to pass along any additional information that +the lock might need for its lock and unlock methods. The values for this +argument are provided to each call to +.Xr CK_COHORT_LOCK 3 +and +.Xr CK_COHORT_UNLOCK 3 +. +.br +.Sh DESCRIPTION +The ck_cohort.h header file does not define any cohort types. Instead, the user must use +the CK_COHORT_PROTOTYPE macro to define any types they want to use. This macro takes the +following arguments: +.Pp +.Fa COHORT_NAME 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 LOCK_FXN global_lock_method +: The method that should be called to acquire the global lock +.br +.Fa LOCK_FXN global_unlock_method +: The method that should be called to relinquish the global lock +.br +.Fa LOCK_FXN local_lock_method +: The method that should be called to acquire the local lock +.br +.Fa LOCK_FXN 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_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 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..0ee95bc --- /dev/null +++ b/doc/CK_COHORT_UNLOCK @@ -0,0 +1,59 @@ +.\" +.\" Copyright 2013 Samy Al Bahra. +.\" 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 Acquire a cohort's locks +.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_INSTANCE 3 , +.Xr CK_COHORT_INITIALIZER 3 , +.Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_LOCK 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..037388d --- /dev/null +++ b/doc/ck_cohort @@ -0,0 +1,67 @@ +.\" +.\" Copyright 2013 Samy Al Bahra. +.\" 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" "global_lock_type" "global_lock_method" \ +"global_unlock_method" "local_lock_type" "local_lock_method" "local_unlock_method" +.Fn CK_COHORT_INSTANCE "cohort_name" +.Fn CK_COHORT_INIT "name" "ck_cohort *cohort" "global_lock" "local_lock" "unsigned int pass_limit" +.Fn CK_COHORT_LOCK "name" "ck_cohort *cohort" "void *global_context" "void *local_context" +.Fn CK_COHORT_UNLOCK "name" "ck_cohort *cohort" "void *global_context" "void *local_context" +.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 +the +.Fn CK_COHORT_PROTOTYPE +macro. This macro allows the user to specify the lock types that +they would like the cohort to use. See the +.Xr CK_COHORT_PROTOTYPE 3 +man page for more details. +Cohort instances do not allocate any new memory, so they +can be freed after use without using an explicit dispose method. +.Pp +.Sh SEE ALSO +.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 , +.Pp +Additional information available at http://concurrencykit.org/