man/atomic_deprecated.3

   1 .Dd May 26, 2004
   2 .Dt ATOMIC_DEPRECATED 3
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm OSAtomicAdd32 ,
   6 .Nm OSAtomicAdd32Barrier ,
   7 .Nm OSAtomicIncrement32 ,
   8 .Nm OSAtomicIncrement32Barrier ,
   9 .Nm OSAtomicDecrement32 ,
  10 .Nm OSAtomicDecrement32Barrier ,
  11 .Nm OSAtomicOr32 ,
  12 .Nm OSAtomicOr32Barrier ,
  13 .Nm OSAtomicOr32Orig ,
  14 .Nm OSAtomicOr32OrigBarrier ,
  15 .Nm OSAtomicAnd32 ,
  16 .Nm OSAtomicAnd32Barrier ,
  17 .Nm OSAtomicAnd32Orig ,
  18 .Nm OSAtomicAnd32OrigBarrier ,
  19 .Nm OSAtomicXor32 ,
  20 .Nm OSAtomicXor32Barrier ,
  21 .Nm OSAtomicXor32Orig ,
  22 .Nm OSAtomicXor32OrigBarrier ,
  23 .Nm OSAtomicAdd64 ,
  24 .Nm OSAtomicAdd64Barrier ,
  25 .Nm OSAtomicIncrement64 ,
  26 .Nm OSAtomicIncrement64Barrier ,
  27 .Nm OSAtomicDecrement64 ,
  28 .Nm OSAtomicDecrement64Barrier ,
  29 .Nm OSAtomicCompareAndSwapInt ,
  30 .Nm OSAtomicCompareAndSwapIntBarrier ,
  31 .Nm OSAtomicCompareAndSwapLong ,
  32 .Nm OSAtomicCompareAndSwapLongBarrier ,
  33 .Nm OSAtomicCompareAndSwapPtr ,
  34 .Nm OSAtomicCompareAndSwapPtrBarrier ,
  35 .Nm OSAtomicCompareAndSwap32 ,
  36 .Nm OSAtomicCompareAndSwap32Barrier ,
  37 .Nm OSAtomicCompareAndSwap64 ,
  38 .Nm OSAtomicCompareAndSwap64Barrier ,
  39 .Nm OSAtomicTestAndSet ,
  40 .Nm OSAtomicTestAndSetBarrier ,
  41 .Nm OSAtomicTestAndClear ,
  42 .Nm OSAtomicTestAndClearBarrier ,
  43 .Nm OSMemoryBarrier
  44 .Nd deprecated atomic add, increment, decrement, or, and, xor, compare and swap, test and set, test and clear, and memory barrier
  45 .Sh SYNOPSIS
  46 .In libkern/OSAtomic.h
  47 .Ft int32_t
  48 .Fn OSAtomicAdd32 "int32_t theAmount" "volatile int32_t *theValue"
  49 .Ft int32_t
  50 .Fn OSAtomicAdd32Barrier "int32_t theAmount" "volatile int32_t *theValue"
  51 .Ft int32_t
  52 .Fn OSAtomicIncrement32 "volatile int32_t *theValue"
  53 .Ft int32_t
  54 .Fn OSAtomicIncrement32Barrier "volatile int32_t *theValue"
  55 .Ft int32_t
  56 .Fn OSAtomicDecrement32 "volatile int32_t *theValue"
  57 .Ft int32_t
  58 .Fn OSAtomicDecrement32Barrier "volatile int32_t *theValue"
  59 .Ft int32_t
  60 .Fn OSAtomicOr32 "uint32_t theMask" "volatile uint32_t *theValue"
  61 .Ft int32_t
  62 .Fn OSAtomicOr32Barrier "uint32_t theMask" "volatile uint32_t *theValue"
  63 .Ft int32_t
  64 .Fn OSAtomicAnd32 "uint32_t theMask" "volatile uint32_t *theValue"
  65 .Ft int32_t
  66 .Fn OSAtomicAnd32Barrier "uint32_t theMask" "volatile uint32_t *theValue"
  67 .Ft int32_t
  68 .Fn OSAtomicXor32 "uint32_t theMask" "volatile uint32_t *theValue"
  69 .Ft int32_t
  70 .Fn OSAtomicXor32Barrier "uint32_t theMask" "volatile uint32_t *theValue"
  71 .Ft int32_t
  72 .Fn OSAtomicOr32Orig "uint32_t theMask" "volatile uint32_t *theValue"
  73 .Ft int32_t
  74 .Fn OSAtomicOr32OrigBarrier "uint32_t theMask" "volatile uint32_t *theValue"
  75 .Ft int32_t
  76 .Fn OSAtomicAnd32Orig "uint32_t theMask" "volatile uint32_t *theValue"
  77 .Ft int32_t
  78 .Fn OSAtomicAnd32OrigBarrier "uint32_t theMask" "volatile uint32_t *theValue"
  79 .Ft int32_t
  80 .Fn OSAtomicXor32Orig "uint32_t theMask" "volatile uint32_t *theValue"
  81 .Ft int32_t
  82 .Fn OSAtomicXor32OrigBarrier "uint32_t theMask" "volatile uint32_t *theValue"
  83 .Ft int64_t
  84 .Fn OSAtomicAdd64 "int64_t theAmount" "volatile OSAtomic_int64_aligned64_t *theValue"
  85 .Ft int64_t
  86 .Fn OSAtomicAdd64Barrier "int64_t theAmount" "volatile OSAtomic_int64_aligned64_t *theValue"
  87 .Ft int64_t
  88 .Fn OSAtomicIncrement64 "volatile OSAtomic_int64_aligned64_t *theValue"
  89 .Ft int64_t
  90 .Fn OSAtomicIncrement64Barrier "volatile OSAtomic_int64_aligned64_t *theValue"
  91 .Ft int64_t
  92 .Fn OSAtomicDecrement64 "volatile OSAtomic_int64_aligned64_t *theValue"
  93 .Ft int64_t
  94 .Fn OSAtomicDecrement64Barrier "volatile OSAtomic_int64_aligned64_t *theValue"
  95 .Ft bool
  96 .Fn OSAtomicCompareAndSwapInt "int oldValue" "int newValue" "volatile int *theValue"
  97 .Ft bool
  98 .Fn OSAtomicCompareAndSwapIntBarrier "int oldValue" "int newValue" "volatile int *theValue"
  99 .Ft bool
 100 .Fn OSAtomicCompareAndSwapLong "long oldValue" "long newValue" "volatile long *theValue"
 101 .Ft bool
 102 .Fn OSAtomicCompareAndSwapLongBarrier "long oldValue" "long newValue" "volatile long *theValue"
 103 .Ft bool
 104 .Fn OSAtomicCompareAndSwapPtr "void* oldValue" "void* newValue" "void* volatile *theValue"
 105 .Ft bool
 106 .Fn OSAtomicCompareAndSwapPtrBarrier "void* oldValue" "void* newValue" "void* volatile *theValue"
 107 .Ft bool
 108 .Fn OSAtomicCompareAndSwap32 "int32_t oldValue" "int32_t newValue" "volatile int32_t *theValue"
 109 .Ft bool
 110 .Fn OSAtomicCompareAndSwap32Barrier "int32_t oldValue" "int32_t newValue" "volatile int32_t *theValue"
 111 .Ft bool
 112 .Fn OSAtomicCompareAndSwap64 "int64_t oldValue" "int64_t newValue" "volatile OSAtomic_int64_aligned64_t *theValue"
 113 .Ft bool
 114 .Fn OSAtomicCompareAndSwap64Barrier "int64_t oldValue" "int64_t newValue" "volatile OSAtomic_int64_aligned64_t *theValue"
 115 .Ft bool
 116 .Fn OSAtomicTestAndSet "uint32_t n" "volatile void *theAddress"
 117 .Ft bool
 118 .Fn OSAtomicTestAndSetBarrier "uint32_t n" "volatile void *theAddress"
 119 .Ft bool
 120 .Fn OSAtomicTestAndClear "uint32_t n" "volatile void *theAddress"
 121 .Ft bool
 122 .Fn OSAtomicTestAndClearBarrier "uint32_t n" "volatile void *theAddress"
 123 .Ft bool
 124 .Fn OSAtomicEnqueue "OSQueueHead *list" "void *new" "size_t offset"
 125 .Ft void*
 126 .Fn OSAtomicDequeue "OSQueueHead *list" "size_t offset"
 127 .Ft void
 128 .Fn OSMemoryBarrier "void"
 129 .Sh DESCRIPTION
 130 .Bf -symbolic
 131 These are deprecated interfaces for atomic and synchronization
 132 operations, provided for compatibility with legacy code. New code should use
 133 the C11
 134 .In stdatomic.h
 135 interfaces.
 136 .Ef
 137 .Pp
 138 These functions are thread and multiprocessor safe.  For each function, there
 139 is a version which incorporates a memory barrier and another version which does
 140 not.
 141 Barriers strictly order memory access on a weakly-ordered architecture such as
 142 ARM. All loads and stores executed in sequential program
 143 order before the barrier will complete before any load or store executed after
 144 the barrier.
 145 On some platforms, such as ARM, the barrier operation can be quite expensive.
 146 .Pp
 147 Most code will want to use the barrier functions to ensure that memory shared
 148 between threads is properly synchronized.  For example, if you want to
 149 initialize a shared data structure and then atomically increment a variable to
 150 indicate that the initialization is complete, then you must use
 151 .Fn OSAtomicIncrement32Barrier
 152 to ensure that the stores to your data structure complete before the atomic add.
 153 Likewise, the consumer of that data structure must use
 154 .Fn OSAtomicDecrement32Barrier ,
 155 in order to ensure that their loads of the structure are not executed before
 156 the atomic decrement.  On the other hand, if you are simply incrementing a
 157 global counter, then it is safe and potentially much faster to use
 158 .Fn OSAtomicIncrement32 .
 159 If you are unsure which version to use, prefer the barrier variants as they are
 160 safer.
 161 .Pp
 162 The logical (and, or, xor) and bit test operations are layered on top of the
 163 .Fn OSAtomicCompareAndSwap
 164 primitives.  There are four versions of each logical operation, depending on
 165 whether or not there is a barrier, and whether the return value is the result
 166 of the operation (eg,
 167 .Fn OSAtomicOr32
 168 ) or the original value before the operation (eg,
 169 .Fn OSAtomicOr32Orig
 170 ).
 171 .Pp
 172 The memory address
 173 .Fa theValue
 174 must be "naturally aligned", i.e. 32-bit aligned for 32-bit operations and
 175 64-bit aligned for 64-bit operations. Note that this is not the default alignment
 176 of the
 177 .Vt int64_t
 178 in the iOS ARMv7 ABI, the
 179 .Vt OSAtomic_int64_aligned64_t
 180 type can be used to declare variables with the required alignment.
 181 .Pp
 182 The
 183 .Fn OSAtomicCompareAndSwap
 184 operations compare
 185 .Fa oldValue
 186 to
 187 .Fa *theValue ,
 188 and set
 189 .Fa *theValue
 190 to
 191 .Fa newValue
 192 if the comparison is equal.  The comparison and assignment
 193 occur as one atomic operation.
 194 .Pp
 195 .Fn OSAtomicTestAndSet
 196 and
 197 .Fn OSAtomicTestAndClear
 198 operate on bit (0x80 >> (
 199 .Fa n
 200 & 7)) of byte ((char*)
 201 .Fa theAddress
 202 + (
 203 .Fa n
 204 >> 3)).  They set the named bit to either 1 or 0, respectively.
 205 .Fa theAddress
 206 need not be aligned.
 207 .Pp
 208 The
 209 .Fn OSMemoryBarrier
 210 function strictly orders memory accesses in a weakly ordered memory model such
 211 as with ARM, by creating a barrier.
 212 All loads and stores executed in sequential program order before the barrier
 213 will complete with respect to the memory coherence mechanism, before any load
 214 or store executed after the barrier. Used with an atomic operation, the barrier
 215 can be used to create custom synchronization protocols as an alternative to the
 216 spinlock or queue/dequeue operations. Note that this barrier does not order
 217 uncached loads and stores. On a uniprocessor, the barrier operation is
 218 typically optimized into a no-op.
 219 .Sh RETURN VALUES
 220 The arithmetic operations return the new value, after the operation has been
 221 performed. The boolean operations come in two styles, one of which returns the
 222 new value, and one of which (the "Orig" versions) returns the old.
 223 The compare-and-swap operations return true if the comparison was equal, ie if
 224 the swap occured. The bit test and set/clear operations return the original
 225 value of the bit.
 226 .Sh SEE ALSO
 227 .Xr atomic 3 ,
 228 .Xr spinlock_deprecated 3
 229 .Sh HISTORY
 230 Most of these functions first appeared in Mac OS 10.4 (Tiger).  The "Orig"
 231 forms of the boolean operations, the "int", "long" and "ptr" forms of
 232 compare-and-swap first appeared in Mac OS 10.5 (Leopard).