man/stdatomic.3

   1 .\" Copyright (c) 2011 Ed Schouten <ed@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 AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd December 27, 2011
  28 .Dt stdatomic 3
  29 .Os
  30 .Sh NAME
  31 .Nm ATOMIC_VAR_INIT ,
  32 .Nm atomic_init ,
  33 .Nm atomic_load ,
  34 .Nm atomic_store ,
  35 .Nm atomic_exchange ,
  36 .Nm atomic_compare_exchange_strong ,
  37 .Nm atomic_compare_exchange_weak ,
  38 .Nm atomic_fetch_add ,
  39 .Nm atomic_fetch_and ,
  40 .Nm atomic_fetch_or ,
  41 .Nm atomic_fetch_sub ,
  42 .Nm atomic_fetch_xor ,
  43 .Nm atomic_is_lock_free
  44 .Nd type-generic atomic operations
  45 .Sh SYNOPSIS
  46 .In stdatomic.h
  47 .Pp
  48 .Vt _Atomic(T) Va v No = \*[Fn-font]ATOMIC_VAR_INIT\*[No-font] Ns Pq Fa c ;
  49 .Vt _Atomic T Va v No =  \*[Fn-font]ATOMIC_VAR_INIT\*[No-font] Ns Pq Fa c ;
  50 .Ft void
  51 .Fn atomic_init "_Atomic(T) *object" "T value"
  52 .Ft T
  53 .Fn atomic_load "_Atomic(T) *object"
  54 .Ft T
  55 .Fn atomic_load_explicit "_Atomic(T) *object" "memory_order order"
  56 .Ft void
  57 .Fn atomic_store "_Atomic(T) *object" "T desired"
  58 .Ft void
  59 .Fn atomic_store_explicit "_Atomic(T) *object" "T desired" "memory_order order"
  60 .Ft T
  61 .Fn atomic_exchange "_Atomic(T) *object" "T desired"
  62 .Ft T
  63 .Fn atomic_exchange_explicit "_Atomic(T) *object" "T desired" "memory_order order"
  64 .Ft _Bool
  65 .Fn atomic_compare_exchange_strong "_Atomic(T) *object" "T *expected" "T desired"
  66 .Ft _Bool
  67 .Fn atomic_compare_exchange_strong_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure"
  68 .Ft _Bool
  69 .Fn atomic_compare_exchange_weak "_Atomic(T) *object" "T *expected" "T desired"
  70 .Ft _Bool
  71 .Fn atomic_compare_exchange_weak_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure"
  72 .Ft T
  73 .Fn atomic_fetch_add "_Atomic(T) *object" "T operand"
  74 .Ft T
  75 .Fn atomic_fetch_add_explicit "_Atomic(T) *object" "T operand" "memory_order order"
  76 .Ft T
  77 .Fn atomic_fetch_and "_Atomic(T) *object" "T operand"
  78 .Ft T
  79 .Fn atomic_fetch_and_explicit "_Atomic(T) *object" "T operand" "memory_order order"
  80 .Ft T
  81 .Fn atomic_fetch_or "_Atomic(T) *object" "T operand"
  82 .Ft T
  83 .Fn atomic_fetch_or_explicit "_Atomic(T) *object" "T operand" "memory_order order"
  84 .Ft T
  85 .Fn atomic_fetch_sub "_Atomic(T) *object" "T operand"
  86 .Ft T
  87 .Fn atomic_fetch_sub_explicit "_Atomic(T) *object" "T operand" "memory_order order"
  88 .Ft T
  89 .Fn atomic_fetch_xor "_Atomic(T) *object" "T operand"
  90 .Ft T
  91 .Fn atomic_fetch_xor_explicit "_Atomic(T) *object" "T operand" "memory_order order"
  92 .Ft _Bool
  93 .Fn atomic_is_lock_free "const _Atomic(T) *object"
  94 .Sh DESCRIPTION
  95 The header
  96 .In stdatomic.h
  97 provides type-generic operations on atomic operations.
  98 .Pp
  99 Atomic variables are declared using the
 100 .Vt _Atomic()
 101 type specifier or the
 102 .Vt _Atomic
 103 type qualifier.
 104 Such variables are not type-compatible with their non-atomic
 105 counterparts and may have different alignment.
 106 .Pp
 107 Operations on atomic variables that do not use the
 108 .Fn atomic_
 109 interfaces, including compound assignment operations, will behave as if the
 110 .Pf non- Fn _explicit
 111 versions of those interfaces had been used.
 112 .Pp
 113 The
 114 .Fn atomic_init
 115 operation initializes the atomic variable
 116 .Fa object
 117 with
 118 .Fa value .
 119 Atomic variables can be initialized while being declared using
 120 .Fn ATOMIC_VAR_INIT .
 121 .Pp
 122 The
 123 .Fn atomic_load
 124 operation returns the value of atomic variable
 125 .Fa object .
 126 The
 127 .Fn atomic_store
 128 operation sets the atomic variable
 129 .Fa object
 130 to the
 131 .Fa desired
 132 value.
 133 .Pp
 134 The
 135 .Fn atomic_exchange
 136 operation combines the behaviour of
 137 .Fn atomic_load
 138 and
 139 .Fn atomic_store .
 140 It sets the atomic variable
 141 .Fa object
 142 to the desired
 143 .Fa value
 144 and returns the original contents of the atomic variable.
 145 .Pp
 146 The
 147 .Fn atomic_compare_exchange_strong
 148 operation stores the
 149 .Fa desired
 150 value into atomic variable
 151 .Fa object ,
 152 but only if the atomic variable is equal to the
 153 .Fa expected
 154 value.
 155 Upon success, the operation returns
 156 .Dv true .
 157 Upon failure, the
 158 .Fa expected
 159 value is overwritten with the contents of the atomic variable and
 160 .Dv false
 161 is returned.
 162 .Pp
 163 The
 164 .Fn atomic_compare_exchange_weak
 165 operation is identical to
 166 .Fn atomic_compare_exchange_strong ,
 167 but is allowed to fail even if atomic variable
 168 .Fa object
 169 is equal to the
 170 .Fa expected
 171 value. When an
 172 .Fn atomic_compare_exchange
 173 operation is in a loop, the weak version will yield better performance on
 174 some platforms. When
 175 .Fn atomic_compare_exchange_weak
 176 would require a loop and
 177 .Fn atomic_compare_exchange_strong
 178 would not, the strong version is preferable.
 179 .Pp
 180 The
 181 .Fn atomic_fetch_add
 182 operation adds the value
 183 .Fa operand
 184 to atomic variable
 185 .Fa object
 186 and returns the original contents of the atomic variable.
 187 .Pp
 188 The
 189 .Fn atomic_fetch_and
 190 operation applies the
 191 .Em and
 192 operator to atomic variable
 193 .Fa object
 194 and value
 195 .Fa operand
 196 and stores the result into
 197 .Fa object ,
 198 while returning the original contents of the atomic variable.
 199 .Pp
 200 The
 201 .Fn atomic_fetch_or
 202 operation applies the
 203 .Em or
 204 operator to atomic variable
 205 .Fa object
 206 and value
 207 .Fa operand
 208 and stores the result into
 209 .Fa object ,
 210 while returning the original contents of the atomic variable.
 211 .Pp
 212 The
 213 .Fn atomic_fetch_sub
 214 operation subtracts the value
 215 .Fa operand
 216 from atomic variable
 217 .Fa object
 218 and returns the original contents of the atomic variable.
 219 .Pp
 220 The
 221 .Fn atomic_fetch_xor
 222 operation applies the
 223 .Em xor
 224 operator to atomic variable
 225 .Fa object
 226 and value
 227 .Fa operand
 228 and stores the result into
 229 .Fa object ,
 230 while returning the original contents of the atomic variable.
 231 .Pp
 232 The
 233 .Fn atomic_is_lock_free
 234 operation returns whether atomic variable
 235 .Fa object
 236 uses locks to implement atomic operations.
 237 .Sh MEMORY ORDER
 238 C11 defines a memory model that may allow for the reordering of operations in the
 239 absence of fences or explicit memory ordering operations.
 240 The
 241 .Pf non- Fn _explicit
 242 interfaces use the strictest available memory order: sequential
 243 consistency. The
 244 .Fn _explicit
 245 interfaces allow for configuration of the memory order operation which is
 246 present.  The types of available memory order operations are explained in
 247 more detail in
 248 .St -isoC-2011 .
 249 .Pp
 250 The
 251 .Fa order
 252 parameter of the
 253 .Fn _explicit
 254 interfaces can have one of the following values:
 255 .Bl -tag -width memory_order_relaxed
 256 .It Dv memory_order_relaxed
 257 Operation does not order memory.
 258 .It Dv memory_order_consume
 259 Performs a consume operation.
 260 .It Dv memory_order_acquire
 261 Performs an acquire operation.
 262 .It Dv memory_order_release
 263 Performs a release operation.
 264 .It Dv memory_order_acq_rel
 265 Performs both an acquire and a release operation.
 266 .It Dv memory_order_seq_cst
 267 Provides sequential consistency.
 268 .El
 269 .Sh SEE ALSO
 270 .Xr atomic 3 ,
 271 .Xr pthread 3
 272 .Sh STANDARDS
 273 These interfaces conform to
 274 .St -isoC-2011 .