[BACK]Return to atomic_ops.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / atomic

Annotation of src/lib/libc/atomic/atomic_ops.3, Revision 1.7.2.1

1.7.2.1 ! pgoyette    1: .\"    $NetBSD: atomic_ops.3,v 1.8 2018/06/16 08:11:32 dholland Exp $
1.1       ad          2: .\"
                      3: .\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc.
                      4: .\" All rights reserved.
                      5: .\"
                      6: .\" This code is derived from software contributed to The NetBSD Foundation
                      7: .\" by Jason R. Thorpe.
                      8: .\"
                      9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\" notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\" notice, this list of conditions and the following disclaimer in the
                     16: .\" documentation and/or other materials provided with the distribution.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
                     19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
                     20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
                     21: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
                     22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
                     23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
                     24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                     25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                     26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
                     27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
                     28: .\" POSSIBILITY OF SUCH DAMAGE.
                     29: .\"
1.7       martin     30: .Dd February 7, 2018
1.1       ad         31: .Dt ATOMIC_OPS 3
                     32: .Os
                     33: .Sh NAME
                     34: .Nm atomic_ops
                     35: .Nd atomic memory operations
                     36: .\" .Sh LIBRARY
                     37: .\" .Lb libc
                     38: .Sh SYNOPSIS
                     39: .In sys/atomic.h
                     40: .Sh DESCRIPTION
                     41: The
                     42: .Nm atomic_ops
                     43: family of functions provide atomic memory operations.
1.3       wiz        44: There are 7 classes of atomic memory operations available:
1.1       ad         45: .Pp
1.4       jruoho     46: .Bl -tag -width "atomic_swap(3)" -offset indent
1.1       ad         47: .It Xr atomic_add 3
                     48: These functions perform atomic addition.
                     49: .It Xr atomic_and 3
1.7.2.1 ! pgoyette   50: These functions perform atomic bitwise
1.1       ad         51: .Dq and .
                     52: .It Xr atomic_cas 3
                     53: These functions perform atomic compare-and-swap.
                     54: .It Xr atomic_dec 3
                     55: These functions perform atomic decrement.
                     56: .It Xr atomic_inc 3
                     57: These functions perform atomic increment.
                     58: .It Xr atomic_or 3
1.7.2.1 ! pgoyette   59: These functions perform atomic bitwise
1.1       ad         60: .Dq or .
                     61: .It Xr atomic_swap 3
                     62: These functions perform atomic swap.
                     63: .El
1.4       jruoho     64: .Ss Synchronization Mechanisms
1.1       ad         65: Where the architecture does not provide hardware support for atomic compare
                     66: and swap (CAS), atomicity is provided by a restartable sequence or by a
                     67: spinlock.
                     68: The chosen method is not ordinarily distinguishable by or visible to users
                     69: of the interface.
                     70: The following architectures can be assumed to provide CAS in hardware:
                     71: alpha, amd64, i386, powerpc, powerpc64, sparc64.
1.4       jruoho     72: .Ss Scope and Restrictions
1.1       ad         73: If hardware CAS is available, the atomic operations are globally atomic:
                     74: operations within a memory region shared between processes are
                     75: guaranteed to be performed atomically.
                     76: If hardware CAS is not available, it may only be assumed that the operations
                     77: are atomic with respect to threads in the same process.
                     78: Additionally, if hardware CAS is not available, the atomic operations must
                     79: not be used within a signal handler.
                     80: .Pp
                     81: Users of atomic memory operations should not make assumptions about how
                     82: the memory access is performed
                     83: .Pq specifically, the width of the memory access .
                     84: For this reason, applications making use of atomic memory operations should
                     85: limit their use to regular memory.
                     86: The results of using atomic memory operations on anything other than
                     87: regular memory are undefined.
                     88: .Pp
                     89: Users of atomic memory operations should take care to modify any given
                     90: memory location either entirely with atomic operations or entirely with
                     91: some other synchronization mechanism.
                     92: Intermixing of atomic operations with other synchronization mechanisms
                     93: for the same memory location results in undefined behavior.
1.4       jruoho     94: .Ss Visibility and Ordering of Memory Accesses
1.1       ad         95: If hardware CAS is available, stores to the target memory location by an
                     96: atomic operation will reach global visibility before the operation
                     97: completes.
                     98: If hardware CAS is not available, the store may not reach global visibility
                     99: until some time after the atomic operation has completed.
                    100: However, in all cases a subsequent atomic operation on the same memory cell
1.6       martin    101: will be delayed until the result of any preceding operation has reached
1.1       ad        102: global visibility.
                    103: .Pp
                    104: Atomic operations are strongly ordered with respect to each other.
                    105: The global visibility of other loads and stores before and after an atomic
                    106: operation is undefined.
                    107: Applications that require synchronization of loads and stores with respect
                    108: to an atomic operation must use memory barriers.
                    109: See
                    110: .Xr membar_ops 3 .
1.4       jruoho    111: .Ss Performance
1.1       ad        112: Because atomic memory operations require expensive synchronization at the
                    113: hardware level, applications should take care to minimize their use.
                    114: In certain cases, it may be more appropriate to use a mutex, especially
                    115: if more than one memory location will be modified.
                    116: .Sh SEE ALSO
                    117: .Xr atomic_add 3 ,
                    118: .Xr atomic_and 3 ,
                    119: .Xr atomic_cas 3 ,
                    120: .Xr atomic_dec 3 ,
                    121: .Xr atomic_inc 3 ,
                    122: .Xr atomic_or 3 ,
                    123: .Xr atomic_swap 3 ,
                    124: .Xr membar_ops 3
                    125: .Sh HISTORY
                    126: The
                    127: .Nm atomic_ops
                    128: functions first appeared in
                    129: .Nx 5.0 .

CVSweb <webmaster@jp.NetBSD.org>