diff --git a/.gitignore b/.gitignore index 4e9157b..05a48ab 100644 --- a/.gitignore +++ b/.gitignore @@ -143,12 +143,12 @@ regressions/ck_queue/validate/ck_slist regressions/ck_cohort/validate/validate regressions/ck_cohort/benchmark/ck_cohort.LATENCY regressions/ck_cohort/benchmark/ck_cohort.THROUGHPUT -regressions/ck_rw_cohort/validate/ck_neutral -regressions/ck_rw_cohort/validate/ck_rp -regressions/ck_rw_cohort/validate/ck_wp -regressions/ck_rw_cohort/benchmark/ck_neutral.LATENCY -regressions/ck_rw_cohort/benchmark/ck_neutral.THROUGHPUT -regressions/ck_rw_cohort/benchmark/ck_rp.LATENCY -regressions/ck_rw_cohort/benchmark/ck_rp.THROUGHPUT -regressions/ck_rw_cohort/benchmark/ck_wp.LATENCY -regressions/ck_rw_cohort/benchmark/ck_wp.THROUGHPUT +regressions/ck_rwcohort/validate/ck_neutral +regressions/ck_rwcohort/validate/ck_rp +regressions/ck_rwcohort/validate/ck_wp +regressions/ck_rwcohort/benchmark/ck_neutral.LATENCY +regressions/ck_rwcohort/benchmark/ck_neutral.THROUGHPUT +regressions/ck_rwcohort/benchmark/ck_rp.LATENCY +regressions/ck_rwcohort/benchmark/ck_rp.THROUGHPUT +regressions/ck_rwcohort/benchmark/ck_wp.LATENCY +regressions/ck_rwcohort/benchmark/ck_wp.THROUGHPUT diff --git a/doc/CK_RWCOHORT_INIT b/doc/CK_RWCOHORT_INIT new file mode 100644 index 0000000..1d543e8 --- /dev/null +++ b/doc/CK_RWCOHORT_INIT @@ -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_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_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. 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_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..c4e7f10 --- /dev/null +++ b/doc/CK_RWCOHORT_INSTANCE @@ -0,0 +1,62 @@ +.\" +.\" 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_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_INSTANCE(foo) *cohorts = malloc(4 * sizeof(CK_RWCOHORT_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..cd8710d --- /dev/null +++ b/doc/CK_RWCOHORT_PROTOTYPE @@ -0,0 +1,63 @@ +.\" +.\" 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_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..68e8da0 --- /dev/null +++ b/doc/CK_RWCOHORT_READ_LOCK @@ -0,0 +1,62 @@ +.\" +.\" 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_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..04f2ff9 --- /dev/null +++ b/doc/CK_RWCOHORT_READ_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_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_READ_LOCK "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..724d4b5 --- /dev/null +++ b/doc/CK_RWCOHORT_WRITE_LOCK @@ -0,0 +1,62 @@ +.\" +.\" 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 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_READ_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..4d063f8 --- /dev/null +++ b/doc/CK_RWCOHORT_WRITE_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_RWCOHORT_READ_LOCK 3 +.Sh NAME +.Nm CK_RWCOHORT_READ_LOCK +.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_READ_LOCK "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/ck_rwcohort b/doc/ck_rwcohort new file mode 100644 index 0000000..d948db6 --- /dev/null +++ b/doc/ck_rwcohort @@ -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 +#include + +#include +#include +#include + +/* + * 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/include/ck_rwcohort.h b/include/ck_rwcohort.h index 67a2d1f..76fb9cb 100644 --- a/include/ck_rwcohort.h +++ b/include/ck_rwcohort.h @@ -67,7 +67,7 @@ } \ \ CK_CC_INLINE static void \ - ck_rwcohort_wp_##N##_write_lock(CK_RWCOHORT_WP_INSTANCE(N) *rw_cohort, \ + ck_rwcohort_wp_##N##_write_lock(CK_RWCOHORT_WP_INSTANCE(N) *rw_cohort, \ CK_COHORT_INSTANCE(N) *cohort, void *global_context, \ void *local_context) \ { \ @@ -165,7 +165,7 @@ } \ \ CK_CC_INLINE static void \ - ck_rwcohort_rp_##N##_write_lock(CK_RWCOHORT_RP_INSTANCE(N) *rw_cohort, \ + ck_rwcohort_rp_##N##_write_lock(CK_RWCOHORT_RP_INSTANCE(N) *rw_cohort, \ CK_COHORT_INSTANCE(N) *cohort, void *global_context, \ void *local_context) \ { \ @@ -176,16 +176,16 @@ CK_COHORT_LOCK(N, cohort, global_context, local_context); \ if (ck_pr_load_uint(&rw_cohort->read_counter) == 0) { \ break; \ - } else { \ - CK_COHORT_UNLOCK(N, cohort, global_context, local_context); \ - while (ck_pr_load_uint(&rw_cohort->read_counter) > 0) { \ - ck_pr_stall(); \ - if (++wait_count > rw_cohort->wait_limit && raised == false) {\ - ck_pr_inc_uint(&rw_cohort->read_barrier); \ - raised = true; \ - } \ - } \ } \ + \ + CK_COHORT_UNLOCK(N, cohort, global_context, local_context); \ + while (ck_pr_load_uint(&rw_cohort->read_counter) > 0) { \ + ck_pr_stall(); \ + if (++wait_count > rw_cohort->wait_limit && raised == false) { \ + ck_pr_inc_uint(&rw_cohort->read_barrier); \ + raised = true; \ + } \ + } \ } \ \ if (raised == true) { \ @@ -277,7 +277,7 @@ } \ \ CK_CC_INLINE static void \ - ck_rwcohort_neutral_##N##_read_lock(CK_RWCOHORT_NEUTRAL_INSTANCE(N) *rw_cohort, \ + ck_rwcohort_neutral_##N##_read_lock(CK_RWCOHORT_NEUTRAL_INSTANCE(N) *rw_cohort, \ CK_COHORT_INSTANCE(N) *cohort, void *global_context, \ void *local_context) \ { \ @@ -290,7 +290,7 @@ \ \ CK_CC_INLINE static void \ - ck_rwcohort_neutral_##N##_read_unlock(CK_RWCOHORT_NEUTRAL_INSTANCE(N) *cohort) \ + ck_rwcohort_neutral_##N##_read_unlock(CK_RWCOHORT_NEUTRAL_INSTANCE(N) *cohort) \ { \ ck_pr_dec_uint(&cohort->read_counter); \ } diff --git a/regressions/ck_rwcohort/validate/Makefile b/regressions/ck_rwcohort/validate/Makefile index 9e86021..af9826d 100644 --- a/regressions/ck_rwcohort/validate/Makefile +++ b/regressions/ck_rwcohort/validate/Makefile @@ -14,7 +14,9 @@ ck_wp: ck_wp.c ../../../include/ck_rwcohort.h $(CC) $(CFLAGS) -o ck_wp ck_wp.c -g check: all - ./validate $(CORES) 1 + ./ck_neutral `expr $(CORES) / 2` 2 1 + ./ck_rp `expr $(CORES) / 2` 2 1 + ./ck_wp `expr $(CORES) / 2` 2 1 clean: rm -rf *.dSYM *~ *.o $(OBJECTS)