share/man/man9/atomic.9

   1 .\" Copyright (c) 2000-2001 John H. Baldwin <jhb@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  14 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  15 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  16 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  17 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  18 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  19 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  20 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  21 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  22 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd August 14, 2015
  27 .Dt ATOMIC 9
  28 .Os
  29 .Sh NAME
  30 .Nm atomic_add ,
  31 .Nm atomic_clear ,
  32 .Nm atomic_cmpset ,
  33 .Nm atomic_fetchadd ,
  34 .Nm atomic_load ,
  35 .Nm atomic_readandclear ,
  36 .Nm atomic_set ,
  37 .Nm atomic_subtract ,
  38 .Nm atomic_store
  39 .Nd atomic operations
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In machine/atomic.h
  43 .Ft void
  44 .Fn atomic_add_[acq_|rel_]<type> "volatile <type> *p" "<type> v"
  45 .Ft void
  46 .Fn atomic_clear_[acq_|rel_]<type> "volatile <type> *p" "<type> v"
  47 .Ft int
  48 .Fo atomic_cmpset_[acq_|rel_]<type>
  49 .Fa "volatile <type> *dst"
  50 .Fa "<type> old"
  51 .Fa "<type> new"
  52 .Fc
  53 .Ft <type>
  54 .Fn atomic_fetchadd_<type> "volatile <type> *p" "<type> v"
  55 .Ft <type>
  56 .Fn atomic_load_acq_<type> "volatile <type> *p"
  57 .Ft <type>
  58 .Fn atomic_readandclear_<type> "volatile <type> *p"
  59 .Ft void
  60 .Fn atomic_set_[acq_|rel_]<type> "volatile <type> *p" "<type> v"
  61 .Ft void
  62 .Fn atomic_subtract_[acq_|rel_]<type> "volatile <type> *p" "<type> v"
  63 .Ft void
  64 .Fn atomic_store_rel_<type> "volatile <type> *p" "<type> v"
  65 .Ft <type>
  66 .Fn atomic_swap_<type> "volatile <type> *p" "<type> v"
  67 .Ft int
  68 .Fn atomic_testandset_<type> "volatile <type> *p" "u_int v"
  69 .Sh DESCRIPTION
  70 Each of the atomic operations is guaranteed to be atomic across multiple
  71 threads and in the presence of interrupts.
  72 They can be used to implement reference counts or as building blocks for more
  73 advanced synchronization primitives such as mutexes.
  74 .Ss Types
  75 Each atomic operation operates on a specific
  76 .Fa type .
  77 The type to use is indicated in the function name.
  78 The available types that can be used are:
  79 .Pp
  80 .Bl -tag -offset indent -width short -compact
  81 .It Li int
  82 unsigned integer
  83 .It Li long
  84 unsigned long integer
  85 .It Li ptr
  86 unsigned integer the size of a pointer
  87 .It Li 32
  88 unsigned 32-bit integer
  89 .It Li 64
  90 unsigned 64-bit integer
  91 .El
  92 .Pp
  93 For example, the function to atomically add two integers is called
  94 .Fn atomic_add_int .
  95 .Pp
  96 Certain architectures also provide operations for types smaller than
  97 .Dq Li int .
  98 .Pp
  99 .Bl -tag -offset indent -width short -compact
 100 .It Li char
 101 unsigned character
 102 .It Li short
 103 unsigned short integer
 104 .It Li 8
 105 unsigned 8-bit integer
 106 .It Li 16
 107 unsigned 16-bit integer
 108 .El
 109 .Pp
 110 These must not be used in MI code because the instructions to implement them
 111 efficiently might not be available.
 112 .Ss Acquire and Release Operations
 113 By default, a thread's accesses to different memory locations might not be
 114 performed in
 115 .Em program order ,
 116 that is, the order in which the accesses appear in the source code.
 117 To optimize the program's execution, both the compiler and processor might
 118 reorder the thread's accesses.
 119 However, both ensure that their reordering of the accesses is not visible to
 120 the thread.
 121 Otherwise, the traditional memory model that is expected by single-threaded
 122 programs would be violated.
 123 Nonetheless, other threads in a multithreaded program, such as the
 124 .Fx
 125 kernel, might observe the reordering.
 126 Moreover, in some cases, such as the implementation of synchronization between
 127 threads, arbitrary reordering might result in the incorrect execution of the
 128 program.
 129 To constrain the reordering that both the compiler and processor might perform
 130 on a thread's accesses, the thread should use atomic operations with
 131 .Em acquire
 132 and
 133 .Em release
 134 semantics.
 135 .Pp
 136 Most of the atomic operations on memory have three variants.
 137 The first variant performs the operation without imposing any ordering
 138 constraints on memory accesses to other locations.
 139 The second variant has acquire semantics, and the third variant has release
 140 semantics.
 141 In effect, operations with acquire and release semantics establish one-way
 142 barriers to reordering.
 143 .Pp
 144 When an atomic operation has acquire semantics, the effects of the operation
 145 must have completed before any subsequent load or store (by program order) is
 146 performed.
 147 Conversely, acquire semantics do not require that prior loads or stores have
 148 completed before the atomic operation is performed.
 149 To denote acquire semantics, the suffix
 150 .Dq Li _acq
 151 is inserted into the function name immediately prior to the
 152 .Dq Li _ Ns Aq Fa type
 153 suffix.
 154 For example, to subtract two integers ensuring that subsequent loads and
 155 stores happen after the subtraction is performed, use
 156 .Fn atomic_subtract_acq_int .
 157 .Pp
 158 When an atomic operation has release semantics, the effects of all prior
 159 loads or stores (by program order) must have completed before the operation
 160 is performed.
 161 Conversely, release semantics do not require that the effects of the
 162 atomic operation must have completed before any subsequent load or store is
 163 performed.
 164 To denote release semantics, the suffix
 165 .Dq Li _rel
 166 is inserted into the function name immediately prior to the
 167 .Dq Li _ Ns Aq Fa type
 168 suffix.
 169 For example, to add two long integers ensuring that all prior loads and
 170 stores happen before the addition, use
 171 .Fn atomic_add_rel_long .
 172 .Pp
 173 The one-way barriers provided by acquire and release operations allow the
 174 implementations of common synchronization primitives to express their
 175 ordering requirements without also imposing unnecessary ordering.
 176 For example, for a critical section guarded by a mutex, an acquire operation
 177 when the mutex is locked and a release operation when the mutex is unlocked
 178 will prevent any loads or stores from moving outside of the critical
 179 section.
 180 However, they will not prevent the compiler or processor from moving loads
 181 or stores into the critical section, which does not violate the semantics of
 182 a mutex.
 183 .Ss Multiple Processors
 184 In multiprocessor systems, the atomicity of the atomic operations on memory
 185 depends on support for cache coherence in the underlying architecture.
 186 In general, cache coherence on the default memory type,
 187 .Dv VM_MEMATTR_DEFAULT ,
 188 is guaranteed by all architectures that are supported by
 189 .Fx .
 190 For example, cache coherence is guaranteed on write-back memory by the
 191 .Tn amd64
 192 and
 193 .Tn i386
 194 architectures.
 195 However, on some architectures, cache coherence might not be enabled on all
 196 memory types.
 197 To determine if cache coherence is enabled for a non-default memory type,
 198 consult the architecture's documentation.
 199 .Ss Semantics
 200 This section describes the semantics of each operation using a C like notation.
 201 .Bl -hang
 202 .It Fn atomic_add p v
 203 .Bd -literal -compact
 204 *p += v;
 205 .Ed
 206 .It Fn atomic_clear p v
 207 .Bd -literal -compact
 208 *p &= ~v;
 209 .Ed
 210 .It Fn atomic_cmpset dst old new
 211 .Bd -literal -compact
 212 if (*dst == old) {
 213         *dst = new;
 214         return (1);
 215 } else
 216         return (0);
 217 .Ed
 218 .El
 219 .Pp
 220 The
 221 .Fn atomic_cmpset
 222 functions are not implemented for the types
 223 .Dq Li char ,
 224 .Dq Li short ,
 225 .Dq Li 8 ,
 226 and
 227 .Dq Li 16 .
 228 .Bl -hang
 229 .It Fn atomic_fetchadd p v
 230 .Bd -literal -compact
 231 tmp = *p;
 232 *p += v;
 233 return (tmp);
 234 .Ed
 235 .El
 236 .Pp
 237 The
 238 .Fn atomic_fetchadd
 239 functions are only implemented for the types
 240 .Dq Li int ,
 241 .Dq Li long
 242 and
 243 .Dq Li 32
 244 and do not have any variants with memory barriers at this time.
 245 .Bl -hang
 246 .It Fn atomic_load p
 247 .Bd -literal -compact
 248 return (*p);
 249 .Ed
 250 .El
 251 .Pp
 252 The
 253 .Fn atomic_load
 254 functions are only provided with acquire memory barriers.
 255 .Bl -hang
 256 .It Fn atomic_readandclear p
 257 .Bd -literal -compact
 258 tmp = *p;
 259 *p = 0;
 260 return (tmp);
 261 .Ed
 262 .El
 263 .Pp
 264 The
 265 .Fn atomic_readandclear
 266 functions are not implemented for the types
 267 .Dq Li char ,
 268 .Dq Li short ,
 269 .Dq Li ptr ,
 270 .Dq Li 8 ,
 271 and
 272 .Dq Li 16
 273 and do not have any variants with memory barriers at this time.
 274 .Bl -hang
 275 .It Fn atomic_set p v
 276 .Bd -literal -compact
 277 *p |= v;
 278 .Ed
 279 .It Fn atomic_subtract p v
 280 .Bd -literal -compact
 281 *p -= v;
 282 .Ed
 283 .It Fn atomic_store p v
 284 .Bd -literal -compact
 285 *p = v;
 286 .Ed
 287 .El
 288 .Pp
 289 The
 290 .Fn atomic_store
 291 functions are only provided with release memory barriers.
 292 .Bl -hang
 293 .It Fn atomic_swap p v
 294 .Bd -literal -compact
 295 tmp = *p;
 296 *p = v;
 297 return (tmp);
 298 .Ed
 299 .El
 300 .Pp
 301 The
 302 .Fn atomic_swap
 303 functions are not implemented for the types
 304 .Dq Li char ,
 305 .Dq Li short ,
 306 .Dq Li ptr ,
 307 .Dq Li 8 ,
 308 and
 309 .Dq Li 16
 310 and do not have any variants with memory barriers at this time.
 311 .Bl -hang
 312 .It Fn atomic_testandset p v
 313 .Bd -literal -compact
 314 bit = 1 << (v % (sizeof(*p) * NBBY));
 315 tmp = (*p & bit) != 0;
 316 *p |= bit;
 317 return (tmp);
 318 .Ed
 319 .El
 320 .Pp
 321 The
 322 .Fn atomic_testandset
 323 functions are only implemented for the types
 324 .Dq Li int ,
 325 .Dq Li long
 326 and
 327 .Dq Li 32
 328 and do not have any variants with memory barriers at this time.
 329 .Pp
 330 The type
 331 .Dq Li 64
 332 is currently not implemented for any of the atomic operations on the
 333 .Tn arm ,
 334 .Tn i386 ,
 335 and
 336 .Tn powerpc
 337 architectures.
 338 .Sh RETURN VALUES
 339 The
 340 .Fn atomic_cmpset
 341 function returns the result of the compare operation.
 342 The
 343 .Fn atomic_fetchadd ,
 344 .Fn atomic_load ,
 345 .Fn atomic_readandclear ,
 346 and
 347 .Fn atomic_swap
 348 functions return the value at the specified address.
 349 The
 350 .Fn atomic_testandset
 351 function returns the result of the test operation.
 352 .Sh EXAMPLES
 353 This example uses the
 354 .Fn atomic_cmpset_acq_ptr
 355 and
 356 .Fn atomic_set_ptr
 357 functions to obtain a sleep mutex and handle recursion.
 358 Since the
 359 .Va mtx_lock
 360 member of a
 361 .Vt "struct mtx"
 362 is a pointer, the
 363 .Dq Li ptr
 364 type is used.
 365 .Bd -literal
 366 /* Try to obtain mtx_lock once. */
 367 #define _obtain_lock(mp, tid)                                           \\
 368         atomic_cmpset_acq_ptr(&(mp)->mtx_lock, MTX_UNOWNED, (tid))
 369
 370 /* Get a sleep lock, deal with recursion inline. */
 371 #define _get_sleep_lock(mp, tid, opts, file, line) do {                 \\
 372         uintptr_t _tid = (uintptr_t)(tid);                              \\
 373                                                                         \\
 374         if (!_obtain_lock(mp, tid)) {                                   \\
 375                 if (((mp)->mtx_lock & MTX_FLAGMASK) != _tid)            \\
 376                         _mtx_lock_sleep((mp), _tid, (opts), (file), (line));\\
 377                 else {                                                  \\
 378                         atomic_set_ptr(&(mp)->mtx_lock, MTX_RECURSE);   \\
 379                         (mp)->mtx_recurse++;                            \\
 380                 }                                                       \\
 381         }                                                               \\
 382 } while (0)
 383 .Ed
 384 .Sh HISTORY
 385 The
 386 .Fn atomic_add ,
 387 .Fn atomic_clear ,
 388 .Fn atomic_set ,
 389 and
 390 .Fn atomic_subtract
 391 operations were first introduced in
 392 .Fx 3.0 .
 393 This first set only supported the types
 394 .Dq Li char ,
 395 .Dq Li short ,
 396 .Dq Li int ,
 397 and
 398 .Dq Li long .
 399 The
 400 .Fn atomic_cmpset ,
 401 .Fn atomic_load ,
 402 .Fn atomic_readandclear ,
 403 and
 404 .Fn atomic_store
 405 operations were added in
 406 .Fx 5.0 .
 407 The types
 408 .Dq Li 8 ,
 409 .Dq Li 16 ,
 410 .Dq Li 32 ,
 411 .Dq Li 64 ,
 412 and
 413 .Dq Li ptr
 414 and all of the acquire and release variants
 415 were added in
 416 .Fx 5.0
 417 as well.
 418 The
 419 .Fn atomic_fetchadd
 420 operations were added in
 421 .Fx 6.0 .
 422 The
 423 .Fn atomic_swap
 424 and
 425 .Fn atomic_testandset
 426 operations were added in
 427 .Fx 10.0 .