Add manual page for atomic operations.
This commit is contained in:
Ed Schouten
parent
73278c5812
commit
4d8a7eab01
295
share/man/man3/ATOMIC_VAR_INIT.3
Normal file
295
share/man/man3/ATOMIC_VAR_INIT.3
Normal file
@ -0,0 +1,295 @@
|
||||
.\" 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 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
|
||||
@ -4,6 +4,7 @@
|
||||
.include <bsd.own.mk>
|
||||
|
||||
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 \
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user