From owner-svn-src-all@FreeBSD.ORG Tue Dec 27 12:58:55 2011 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id DD675106564A; Tue, 27 Dec 2011 12:58:54 +0000 (UTC) (envelope-from ed@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id C0AA88FC0C; Tue, 27 Dec 2011 12:58:54 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id pBRCwsWf053724; Tue, 27 Dec 2011 12:58:54 GMT (envelope-from ed@svn.freebsd.org) Received: (from ed@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id pBRCwsrU053722; Tue, 27 Dec 2011 12:58:54 GMT (envelope-from ed@svn.freebsd.org) Message-Id: <201112271258.pBRCwsrU053722@svn.freebsd.org> From: Ed Schouten Date: Tue, 27 Dec 2011 12:58:54 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r228912 - head/share/man/man3 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 27 Dec 2011 12:58:55 -0000 Author: ed Date: Tue Dec 27 12:58:54 2011 New Revision: 228912 URL: http://svn.freebsd.org/changeset/base/228912 Log: Add manual page for atomic operations. Added: head/share/man/man3/ATOMIC_VAR_INIT.3 (contents, props changed) Modified: head/share/man/man3/Makefile Added: head/share/man/man3/ATOMIC_VAR_INIT.3 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man3/ATOMIC_VAR_INIT.3 Tue Dec 27 12:58:54 2011 (r228912) @@ -0,0 +1,295 @@ +.\" Copyright (c) 2011 Ed Schouten +.\" 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 AUTHOR 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 AUTHOR 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. +.\" +.\" $FreeBSD$ +.\" +.Dd December 27, 2011 +.Dt ATOMIC_VAR_INIT 3 +.Os +.Sh NAME +.Nm ATOMIC_VAR_INIT , +.Nm atomic_init , +.Nm atomic_load , +.Nm atomic_store , +.Nm atomic_exchange , +.Nm atomic_compare_exchange_strong , +.Nm atomic_compare_exchange_weak , +.Nm atomic_fetch_add , +.Nm atomic_fetch_and , +.Nm atomic_fetch_or , +.Nm atomic_fetch_sub , +.Nm atomic_fetch_xor , +.Nm atomic_is_lock_free +.Nd type-generic atomic operations +.Sh SYNOPSIS +.In stdatomic.h +.Pp +_Atomic(T) +.Fa v += ATOMIC_VAR_INIT(c); +.Ft void +.Fn atomic_init "_Atomic(T) *object" "T value" +.Ft T +.Fn atomic_load "_Atomic(T) *object" +.Ft T +.Fn atomic_load_explicit "_Atomic(T) *object" "memory_order order" +.Ft void +.Fn atomic_store "_Atomic(T) *object" "T desired" +.Ft void +.Fn atomic_store_explicit "_Atomic(T) *object" "T desired" "memory_order order" +.Ft T +.Fn atomic_exchange "_Atomic(T) *object" "T desired" +.Ft T +.Fn atomic_exchange_explicit "_Atomic(T) *object" "T desired" "memory_order order" +.Ft _Bool +.Fn atomic_compare_exchange_strong "_Atomic(T) *object" "T *expected" "T desired" +.Ft _Bool +.Fn atomic_compare_exchange_strong_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure" +.Ft _Bool +.Fn atomic_compare_exchange_weak "_Atomic(T) *object" "T *expected" "T desired" +.Ft _Bool +.Fn atomic_compare_exchange_weak_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure" +.Ft T +.Fn atomic_fetch_add "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_add_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_and "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_and_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_or "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_or_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_sub "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_sub_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_xor "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_xor_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft _Bool +.Fn atomic_is_lock_free "const _Atomic(T) *object" +.Sh DESCRIPTION +The header +.In stdatomic.h +provides type-generic macros for atomic operations. +Atomic operations can be used by multithreaded programs to provide +shared variables between threads that in most cases may be modified +without acquiring locks. +.Pp +Atomic variables are declared using the +.Fn _Atomic +type specifier. +These variables are not type-compatible with their non-atomic +counterparts. +Depending on the compiler used, atomic variables may be opaque and can +therefore only be influenced using the macros described. +.Pp +The +.Fn atomic_init +macro initializes the atomic variable +.Fa object +with a +.Fa value . +Atomic variables can be initialized while being declared using +.Fn ATOMIC_VAR_INIT . +.Pp +The +.Fn atomic_load +macro returns the value of atomic variable +.Fa object . +The +.Fn atomic_store +macro sets the atomic variable +.Fa object +to its +.Fa desired +value. +.Pp +The +.Fn atomic_exchange +macro combines the behaviour of +.Fn atomic_load +and +.Fn atomic_store . +It sets the atomic variable +.Fa object +to its desired +.Fa value +and returs the original contents of the atomic variable. +.Pp +The +.Fn atomic_compare_exchange_strong +macro stores a +.Fa desired +value into atomic variable +.Fa object , +only if the atomic variable is equal to its +.Fa expected +value. +Upon success, the macro returns +.Dv true . +Upon failure, the +.Fa desired +value is overwritten with the value of the atomic variable and +.Dv false +is returned. +The +.Fn atomic_compare_exchange_weak +macro is identical to +.Fn atomic_compare_exchange_strong , +but is allowed to fail even if atomic variable +.Fa object +is equal to its +.Fa expected +value. +.Pp +The +.Fn atomic_fetch_add +macro adds the value +.Fa operand +to atomic variable +.Fa object +and returns the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_and +macro applies the +.Em and +operator to atomic variable +.Fa object +and +.Fa operand +and stores the value into +.Fa object , +while returning the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_or +macro applies the +.Em or +operator to atomic variable +.Fa object +and +.Fa operand +and stores the value into +.Fa object , +while returning the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_sub +macro subtracts the value +.Fa operand +to atomic variable +.Fa object +and returns the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_xor +macro applies the +.Em xor +operator to atomic variable +.Fa object +and +.Fa operand +and stores the value into +.Fa object , +while returning the original contents of the atomic variable. +.Pp +The +.Fn atomic_is_lock_free +macro returns whether atomic variable +.Fa object +uses locks when using atomic operations. +.Sh BARRIERS +The atomic operations described previously are implemented in such a way +that they disallow both the compiler and the executing processor to +re-order any nearby memory operations across the atomic operation. +In certain cases this behaviour may cause suboptimal performance. +To mitigate this, every atomic operation has an +.Fn _explicit +version that allows the re-ordering to be configured. +.Pp +The +.Fa order +parameter of these +.Fn _explicit +macros can have one of the following values. +.Bl -tag -width memory_order_relaxed +.It Dv memory_order_relaxed +No operation orders memory. +.It Dv memory_order_consume +Perform consume operation. +.It Dv memory_order_acquire +Acquire fence. +.It Dv memory_order_release +Release fence. +.It Dv memory_order_acq_rel +Acquire and release fence. +.It Dv memory_order_seq_cst +Sequentially consistent acquire and release fence. +.El +.Pp +The previously described macros are identical to the +.Fn _explicit +macros, when +.Fa order +is +.Dv memory_order_seq_cst . +.Sh COMPILER SUPPORT +These atomic operations are typically implemented by the compiler, as +they must be implemented type-generically and must often use special +hardware instructions. +As this interface has not been adopted by most compilers yet, the +.In stdatomic.h +header implements these macros on top of existing compiler intrinsics to +provide forward compatibility. +.Pp +This means that certain aspects of the interface, such as support for +different barrier types may simply be ignored. +When using GCC, all atomic operations are executed as if they are using +.Dv memory_order_seq_cst . +.Pp +Instead of using the atomic operations provided by this interface, +.St -isoC-11 +allows the atomic variables to be modified directly using built-in +language operators. +This behaviour cannot be emulated for older compilers. +To prevent unintended non-atomic access to these variables, this header +file places the atomic variable in a structure when using an older +compiler. +.Sh SEE ALSO +.Xr pthread 3 , +.Xr atomic 9 +.Sh STANDARDS +These macros attempt to conform to +.St -isoC-11 . +.Sh HISTORY +These macros appeared in +.Fx 10.0 . +.Sh AUTHORS +.An Ed Schouten Aq ed@FreeBSD.org , +.An David Chisnall Aq theraven@FreeBSD.org Modified: head/share/man/man3/Makefile ============================================================================== --- head/share/man/man3/Makefile Tue Dec 27 10:36:56 2011 (r228911) +++ head/share/man/man3/Makefile Tue Dec 27 12:58:54 2011 (r228912) @@ -4,6 +4,7 @@ .include MAN= assert.3 \ + ATOMIC_VAR_INIT.3 \ bitstring.3 \ end.3 \ fpgetround.3 \ @@ -18,7 +19,29 @@ MAN= assert.3 \ timeradd.3 \ tree.3 -MLINKS= bitstring.3 bit_alloc.3 \ +MLINKS= ATOMIC_VAR_INIT.3 atomic_compare_exchange_strong.3 \ + ATOMIC_VAR_INIT.3 atomic_compare_exchange_strong_explicit.3 \ + ATOMIC_VAR_INIT.3 atomic_compare_exchange_weak.3 \ + ATOMIC_VAR_INIT.3 atomic_compare_exchange_weak_explicit.3 \ + ATOMIC_VAR_INIT.3 atomic_exchange.3 \ + ATOMIC_VAR_INIT.3 atomic_exchange_explicit.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_add.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_add_explicit.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_and.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_and_explicit.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_or.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_or_explicit.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_sub.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_sub_explicit.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_xor.3 \ + ATOMIC_VAR_INIT.3 atomic_fetch_xor_explicit.3 \ + ATOMIC_VAR_INIT.3 atomic_init.3 \ + ATOMIC_VAR_INIT.3 atomic_is_lock_free.3 + ATOMIC_VAR_INIT.3 atomic_load.3 \ + ATOMIC_VAR_INIT.3 atomic_load_explicit.3 \ + ATOMIC_VAR_INIT.3 atomic_store.3 \ + ATOMIC_VAR_INIT.3 atomic_store_explicit.3 +MLINKS+= bitstring.3 bit_alloc.3 \ bitstring.3 bit_clear.3 \ bitstring.3 bit_decl.3 \ bitstring.3 bit_ffc.3 \