Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Note many of the restrictions, and clarify the section on global 

visibility.
This commit is contained in:
ad 2008-02-11 15:01:24 +00:00
parent b3193dc791
commit 1b2aff1f03
1 changed files with 48 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
common/lib/libc/atomic/atomic_ops.3
View File

@ -1,6 +1,6 @@
.\" $NetBSD: atomic_ops.3,v 1.3 2007/12/02 18:57:56 wiz Exp $
.\" $NetBSD: atomic_ops.3,v 1.4 2008/02/11 15:01:24 ad Exp $
.\"
.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
.\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
@ -34,7 +34,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 11, 2007
.Dd Febuary 11, 2007
.Dt ATOMIC_OPS 3
.Os
.Sh NAME
@ -48,7 +48,8 @@
The
.Nm atomic_ops
family of functions provide atomic memory operations.
There are 7 classes of atomic memory operations available:
There are 7 classes of atomic memory operations available
:
.Pp
.Bl -tag -width "atomic_swap(3)"
.It Xr atomic_add 3
@ -69,19 +70,25 @@ These functions perform atomic logical
These functions perform atomic swap.
.El
.Pp
After an atomic operation is complete, the store to the target memory
location will have global visibility.
The global visibility of other loads and stores before and after the atomic
operation are undefined.
Applications that require synchronization of loads and stores with respect
to an atomic operation must use memory barriers.
See
.Xr membar_ops 3 .
.Bl -tag -width aa
.It Synchronization mechanisms
.Pp
Because atomic memory operations require expensive synchronization at the
hardware level, applications should take care to minimize their use.
In certain cases, it may be more appropriate to use a mutex, especially
if more than one memory location will be modified.
Where the architecture does not provide hardware support for atomic compare
and swap (CAS), atomicity is provided by a restartable sequence or by a
spinlock.
The chosen method is not ordinarily distinguishable by or visible to users
of the interface.
The following architectures can be assumed to provide CAS in hardware:
alpha, amd64, i386, powerpc, powerpc64, sparc64.
.It Scope and restrictions
.Pp
If hardware CAS is available, the atomic operations are globally atomic:
operations within a memory region shared between processes are
guaranteed to be performed atomically.
If hardware CAS is not available, it may only be assumed that the operations
are atomic with respect to threads in the same process.
Additionally, if hardware CAS is not available, the atomic operations must
not be used within a signal handler.
.Pp
Users of atomic memory operations should not make assumptions about how
the memory access is performed
@ -96,6 +103,31 @@ memory location either entirely with atomic operations or entirely with
some other synchronization mechanism.
Intermixing of atomic operations with other synchronization mechanisms
for the same memory location results in undefined behavior.
.It Visibility and ordering of memory accesses
.Pp
If hardware CAS is available, stores to the target memory location by an
atomic operation will reach global visibility before the operation
completes.
If hardware CAS is not available, the store may not reach global visibility
until some time after the atomic operation has completed.
However, in all cases a subsequent atomic operation on the same memory cell
will be delayed until the result of any preceeding operation has reached
global visibility.
.Pp
Atomic operations are strongly ordered with respect to each other.
The global visibility of other loads and stores before and after an atomic
operation is undefined.
Applications that require synchronization of loads and stores with respect
to an atomic operation must use memory barriers.
See
.Xr membar_ops 3 .
.It Performance
.Pp
Because atomic memory operations require expensive synchronization at the
hardware level, applications should take care to minimize their use.
In certain cases, it may be more appropriate to use a mutex, especially
if more than one memory location will be modified.
.El
.Sh SEE ALSO
.Xr atomic_add 3 ,
.Xr atomic_and 3 ,