1.\" $NetBSD: atomic_ops.3,v 1.2 2009/05/18 12:37:28 wiz Exp $ 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.\" 30.Dd February 11, 2007 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 41The 42.Nm atomic_ops 43family of functions provide atomic memory operations. 44There are 7 classes of atomic memory operations available 45: 46.Pp 47.Bl -tag -width "atomic_swap(3)" 48.It Xr atomic_add 3 49These functions perform atomic addition. 50.It Xr atomic_and 3 51These functions perform atomic logical 52.Dq and . 53.It Xr atomic_cas 3 54These functions perform atomic compare-and-swap. 55.It Xr atomic_dec 3 56These functions perform atomic decrement. 57.It Xr atomic_inc 3 58These functions perform atomic increment. 59.It Xr atomic_or 3 60These functions perform atomic logical 61.Dq or . 62.It Xr atomic_swap 3 63These functions perform atomic swap. 64.El 65.Pp 66.Bl -tag -width aa 67.It Synchronization mechanisms 68.Pp 69Where the architecture does not provide hardware support for atomic compare 70and swap (CAS), atomicity is provided by a restartable sequence or by a 71spinlock. 72The chosen method is not ordinarily distinguishable by or visible to users 73of the interface. 74The following architectures can be assumed to provide CAS in hardware: 75alpha, amd64, i386, powerpc, powerpc64, sparc64. 76.It Scope and restrictions 77.Pp 78If hardware CAS is available, the atomic operations are globally atomic: 79operations within a memory region shared between processes are 80guaranteed to be performed atomically. 81If hardware CAS is not available, it may only be assumed that the operations 82are atomic with respect to threads in the same process. 83Additionally, if hardware CAS is not available, the atomic operations must 84not be used within a signal handler. 85.Pp 86Users of atomic memory operations should not make assumptions about how 87the memory access is performed 88.Pq specifically, the width of the memory access . 89For this reason, applications making use of atomic memory operations should 90limit their use to regular memory. 91The results of using atomic memory operations on anything other than 92regular memory are undefined. 93.Pp 94Users of atomic memory operations should take care to modify any given 95memory location either entirely with atomic operations or entirely with 96some other synchronization mechanism. 97Intermixing of atomic operations with other synchronization mechanisms 98for the same memory location results in undefined behavior. 99.It Visibility and ordering of memory accesses 100.Pp 101If hardware CAS is available, stores to the target memory location by an 102atomic operation will reach global visibility before the operation 103completes. 104If hardware CAS is not available, the store may not reach global visibility 105until some time after the atomic operation has completed. 106However, in all cases a subsequent atomic operation on the same memory cell 107will be delayed until the result of any preceeding operation has reached 108global visibility. 109.Pp 110Atomic operations are strongly ordered with respect to each other. 111The global visibility of other loads and stores before and after an atomic 112operation is undefined. 113Applications that require synchronization of loads and stores with respect 114to an atomic operation must use memory barriers. 115See 116.Xr membar_ops 3 . 117.It Performance 118.Pp 119Because atomic memory operations require expensive synchronization at the 120hardware level, applications should take care to minimize their use. 121In certain cases, it may be more appropriate to use a mutex, especially 122if more than one memory location will be modified. 123.El 124.Sh SEE ALSO 125.Xr atomic_add 3 , 126.Xr atomic_and 3 , 127.Xr atomic_cas 3 , 128.Xr atomic_dec 3 , 129.Xr atomic_inc 3 , 130.Xr atomic_or 3 , 131.Xr atomic_swap 3 , 132.Xr membar_ops 3 133.Sh HISTORY 134The 135.Nm atomic_ops 136functions first appeared in 137.Nx 5.0 . 138