From 366440cd64818e69a88e3fc00b9e1723a0b900e2 Mon Sep 17 00:00:00 2001 From: Luca Burlacu <64703924+LucaJetB@users.noreply.github.com> Date: Fri, 13 Dec 2024 21:43:36 -0500 Subject: [PATCH] Added man pages for fence types (#239) Added new man pages for ck_pr_fence_lock(), ck_pr_fence_unlock(), and ck_pr_fence_acqrel() Resolves #239 --------- Authored-by: Luca Burlacu Authored-by: Luca Burlacu --- doc/ck_pr_fence_acqrel | 70 ++++++++++++++++++++++++++++++++++++++++++ doc/ck_pr_fence_lock | 69 +++++++++++++++++++++++++++++++++++++++++ doc/ck_pr_fence_unlock | 70 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 209 insertions(+) create mode 100644 doc/ck_pr_fence_acqrel create mode 100644 doc/ck_pr_fence_lock create mode 100644 doc/ck_pr_fence_unlock diff --git a/doc/ck_pr_fence_acqrel b/doc/ck_pr_fence_acqrel new file mode 100644 index 00000000..303a68d2 --- /dev/null +++ b/doc/ck_pr_fence_acqrel @@ -0,0 +1,70 @@ +.\" +.\" Copyright 2024 Luca Burlacu. +.\" 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 November 24, 2024 +.Dt ck_pr_fence_acqrel 3 +.Sh NAME +.Nm ck_pr_fence_acqrel +.Nd enforce ordering of acquire and release operations +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_acqrel void +.Ft void +.Fn ck_pr_fence_strict_acqrel void +.Sh DESCRIPTION +This function enforces memory using both acquire and release ordering relative +to the invocation of the function. Acquire ordering will prevent reordering +of preceding reads with subsequent reads or writes. Release ordering will +prevent reordering of preceding reads or writes with subsequent writes. +On architectures with CK_MD_TSO (total store ordering), this operation only serves +as a compiler barrier and no fence instructions will be emitted. +Architectures implementing CK_MD_PSO or CK_MD_RMO (partial store ordering and relaxed memory ordering respectively) +always emit a fence. + +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_fence_acquire 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_lock 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_fence_release 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_store_atomic 3 , +.Xr ck_pr_fence_store_load 3 , +.Xr ck_pr_fence_unlock 3 , + +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_lock b/doc/ck_pr_fence_lock new file mode 100644 index 00000000..b73a63fb --- /dev/null +++ b/doc/ck_pr_fence_lock @@ -0,0 +1,69 @@ +.\" +.\" Copyright 2024 Luca Burlacu. +.\" 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 November 24, 2024 +.Dt ck_pr_fence_lock 3 +.Sh NAME +.Nm ck_pr_fence_lock +.Nd enforce memory ordering when acquiring a lock +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_lock void +.Sh DESCRIPTION +This function serves as an implicit compiler barrier. +On architectures with CK_MD_TSO (total store ordering), +this operation only serves as a compiler barrier and no fence instructions +will be emitted. Architectures implementing CK_MD_PSO or CK_MD_RMO +(partial store ordering and relaxed memory ordering respectively) +always emit a fence. On SPARCv9, +.Fn ck_pr_fence_lock +enforces ordering of load-load, load-store, store-store, and store-load. +To force the unconditional emission of a fence, use +.Fn ck_pr_fence_strict_lock . + +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_fence_acqrel 3 , +.Xr ck_pr_fence_acquire 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_fence_release 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_store_atomic 3 , +.Xr ck_pr_fence_store_load 3 , +.Xr ck_pr_fence_unlock 3 +.Pp +Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_pr_fence_unlock b/doc/ck_pr_fence_unlock new file mode 100644 index 00000000..925cc1d0 --- /dev/null +++ b/doc/ck_pr_fence_unlock @@ -0,0 +1,70 @@ +.\" +.\" Copyright 2024 Luca Burlacu. +.\" 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 November 24, 2024 +.Dt ck_pr_fence_unlock 3 +.Sh NAME +.Nm ck_pr_fence_unlock +.Nd enforce memory ordering when releasing a lock +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft void +.Fn ck_pr_fence_unlock void +.Sh DESCRIPTION +This function serves as an implicit compiler barrier. +On architectures with CK_MD_TSO (total store ordering), this operation only serves +as a compiler barrier and no fence instructions will be emitted. +Architectures implementing CK_MD_PSO or CK_MD_RMO +(partial store ordering and relaxed memory ordering respectively) +always emit a fence. On SPARCv9 +.Fn ck_pr_fence_unlock +enforces ordering on load-store and store-load, instead of the full range that +.Fn ck_pr_fence_lock +does. To force the unconditional emission of a fence, use +.Fn ck_pr_fence_strict_unlock . + +.Sh RETURN VALUES +This function has no return value. +.Sh SEE ALSO +.Xr ck_pr_fence_acqrel 3 , +.Xr ck_pr_fence_acquire 3 , +.Xr ck_pr_fence_atomic 3 , +.Xr ck_pr_fence_atomic_load 3 , +.Xr ck_pr_fence_atomic_store 3 , +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_atomic 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_load_store 3 , +.Xr ck_pr_fence_lock 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_fence_release 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_store_atomic 3 , +.Xr ck_pr_fence_store_load 3 +.Pp +Additional information available at http://concurrencykit.org/