atomic_ops(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
ATOMIC_OPS(3)           NetBSD Library Functions Manual          ATOMIC_OPS(3)


NAME

     atomic_ops -- atomic memory operations


SYNOPSIS

     #include <sys/atomic.h>


DESCRIPTION

     The atomic_ops family of functions provide atomic memory operations.
     There are 7 classes of atomic memory operations available:

           atomic_add(3)   These functions perform atomic addition.

           atomic_and(3)   These functions perform atomic bitwise ``and''.

           atomic_cas(3)   These functions perform atomic compare-and-swap.

           atomic_dec(3)   These functions perform atomic decrement.

           atomic_inc(3)   These functions perform atomic increment.

           atomic_or(3)    These functions perform atomic bitwise ``or''.

           atomic_swap(3)  These functions perform atomic swap.

   Synchronization Mechanisms
     Where the architecture does not provide hardware support for atomic com-
     pare 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: aarch64, alpha, amd64, i386, powerpc,
     powerpc64, sparc64.

   Scope and Restrictions
     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.

     Users of atomic memory operations should not make assumptions about how
     the memory access is performed (specifically, the width of the memory
     access).  For this reason, applications making use of atomic memory oper-
     ations should limit their use to regular memory.  The results of using
     atomic memory operations on anything other than regular memory are unde-
     fined.

     Users of atomic memory operations should take care to modify any given
     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.

   Visibility and Ordering of Memory Accesses
     If hardware CAS is available, stores to the target memory location by an
     atomic operation will reach global visibility before the operation com-
     pletes.  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 preceding operation has
     reached global visibility.

     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 bar-
     riers.  See membar_ops(3).

   Performance
     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.


SEE ALSO

     atomic_add(3), atomic_and(3), atomic_cas(3), atomic_dec(3),
     atomic_inc(3), atomic_or(3), atomic_swap(3), membar_ops(3)


HISTORY

     The atomic_ops functions first appeared in NetBSD 5.0.

NetBSD 10.1                    September 6, 2023                   NetBSD 10.1