--- /dev/null
+.\" Copyright (c) 2011 Ed Schouten <ed@FreeBSD.org>
+.\" 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 stdatomic 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
+.Vt _Atomic(T) Va v No = \*[Fn-font]ATOMIC_VAR_INIT\*[No-font] Ns Pq Fa c ;
+.Vt _Atomic T Va v No = \*[Fn-font]ATOMIC_VAR_INIT\*[No-font] Ns Pq Fa 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 operations on atomic operations.
+.Pp
+Atomic variables are declared using the
+.Vt _Atomic()
+type specifier or the
+.Vt _Atomic
+type qualifier.
+Such variables are not type-compatible with their non-atomic
+counterparts and may have different alignment.
+.Pp
+Operations on atomic variables that do not use the
+.Fn atomic_
+interfaces, including compound assignment operations, will behave as if the
+.Pf non- Fn _explicit
+versions of those interfaces had been used.
+.Pp
+The
+.Fn atomic_init
+operation initializes the atomic variable
+.Fa object
+with
+.Fa value .
+Atomic variables can be initialized while being declared using
+.Fn ATOMIC_VAR_INIT .
+.Pp
+The
+.Fn atomic_load
+operation returns the value of atomic variable
+.Fa object .
+The
+.Fn atomic_store
+operation sets the atomic variable
+.Fa object
+to the
+.Fa desired
+value.
+.Pp
+The
+.Fn atomic_exchange
+operation combines the behaviour of
+.Fn atomic_load
+and
+.Fn atomic_store .
+It sets the atomic variable
+.Fa object
+to the desired
+.Fa value
+and returns the original contents of the atomic variable.
+.Pp
+The
+.Fn atomic_compare_exchange_strong
+operation stores the
+.Fa desired
+value into atomic variable
+.Fa object ,
+but only if the atomic variable is equal to the
+.Fa expected
+value.
+Upon success, the operation returns
+.Dv true .
+Upon failure, the
+.Fa expected
+value is overwritten with the contents of the atomic variable and
+.Dv false
+is returned.
+.Pp
+The
+.Fn atomic_compare_exchange_weak
+operation is identical to
+.Fn atomic_compare_exchange_strong ,
+but is allowed to fail even if atomic variable
+.Fa object
+is equal to the
+.Fa expected
+value. When an
+.Fn atomic_compare_exchange
+operation is in a loop, the weak version will yield better performance on
+some platforms. When
+.Fn atomic_compare_exchange_weak
+would require a loop and
+.Fn atomic_compare_exchange_strong
+would not, the strong version is preferable.
+.Pp
+The
+.Fn atomic_fetch_add
+operation 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
+operation applies the
+.Em and
+operator to atomic variable
+.Fa object
+and value
+.Fa operand
+and stores the result into
+.Fa object ,
+while returning the original contents of the atomic variable.
+.Pp
+The
+.Fn atomic_fetch_or
+operation applies the
+.Em or
+operator to atomic variable
+.Fa object
+and value
+.Fa operand
+and stores the result into
+.Fa object ,
+while returning the original contents of the atomic variable.
+.Pp
+The
+.Fn atomic_fetch_sub
+operation subtracts the value
+.Fa operand
+from atomic variable
+.Fa object
+and returns the original contents of the atomic variable.
+.Pp
+The
+.Fn atomic_fetch_xor
+operation applies the
+.Em xor
+operator to atomic variable
+.Fa object
+and value
+.Fa operand
+and stores the result into
+.Fa object ,
+while returning the original contents of the atomic variable.
+.Pp
+The
+.Fn atomic_is_lock_free
+operation returns whether atomic variable
+.Fa object
+uses locks to implement atomic operations.
+.Sh MEMORY ORDER
+C11 defines a memory model that may allow for the reordering of operations in the
+absence of fences or explicit memory ordering operations.
+The
+.Pf non- Fn _explicit
+interfaces use the strictest available memory order: sequential
+consistency. The
+.Fn _explicit
+interfaces allow for configuration of the memory order operation which is
+present. The types of available memory order operations are explained in
+more detail in
+.St -isoC-2011 .
+.Pp
+The
+.Fa order
+parameter of the
+.Fn _explicit
+interfaces can have one of the following values:
+.Bl -tag -width memory_order_relaxed
+.It Dv memory_order_relaxed
+Operation does not order memory.
+.It Dv memory_order_consume
+Performs a consume operation.
+.It Dv memory_order_acquire
+Performs an acquire operation.
+.It Dv memory_order_release
+Performs a release operation.
+.It Dv memory_order_acq_rel
+Performs both an acquire and a release operation.
+.It Dv memory_order_seq_cst
+Provides sequential consistency.
+.El
+.Sh SEE ALSO
+.Xr atomic 3 ,
+.Xr pthread 3
+.Sh STANDARDS
+These interfaces conform to
+.St -isoC-2011 .
projects / apple / libplatform.git / blobdiff