libplatform-254.40.4.tar.gz

[apple/libplatform.git] / man / stdatomic.3

.\" 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 .