|
OSAtomic.h |
Includes: |
<stddef.h> <sys/cdefs.h> <stdint.h> <stdbool.h> |
These are the preferred versions of the atomic and synchronization operations. Their implementation is customized at boot time for the platform, including late-breaking errata fixes as necessary. They are thread safe.
WARNING: all addresses passed to these functions must be "naturally aligned",
i.e. * int32_t
pointers must be 32-bit aligned (low 2 bits of
address are zeroes), and int64_t
pointers must be 64-bit aligned
(low 3 bits of address are zeroes.)
Note that some versions of the atomic functions incorporate memory barriers and some do not. Barriers strictly order memory access on weakly-ordered architectures such as PPC. All loads and stores that appear (in sequential program order) before the barrier are guaranteed to complete before any load or store that appears after the barrier.
On a uniprocessor system, the barrier operation is typically a no-op. On a multiprocessor system, the barrier can be quite expensive on some platforms, such as PPC.
Most code should use the barrier functions to ensure that memory shared between
threads is properly synchronized. For example, if you want to initialize
a shared data structure and then atomically increment a variable to indicate
that the initialization is complete, you must use OSAtomicIncrement32Barrier
to ensure that the stores to your data structure complete before the atomic
increment.
Likewise, the consumer of that data structure must use OSAtomicDecrement32Barrier
,
in order to ensure that their loads of the structure are not executed before
the atomic decrement. On the other hand, if you are simply incrementing a global
counter, then it is safe and potentially faster to use OSAtomicIncrement32
.
If you are unsure which version to use, prefer the barrier variants as they are safer.
The spinlock and queue operations always incorporate a barrier.
For the kernel-space version of this header, see
OSAtomic.h (Kernel Framework)
These routines manipulate singly-linked LIFO lists.
The initialization vector for a queue head.
Dequeue an item from a list.
Enqueue an item onto a list.
The data structure for a queue head.
Memory barrier.
These spinlocks use memory barriers as required to synchronize access to shared memory protected by the lock.
The default value for an OSSpinLock
.
Data type for a spinlock.
Locks a spinlock
Locks a spinlock if it would not block
Unlocks a spinlock
Atomic bitwise AND of two 32-bit values.
Atomic bitwise AND of two 32-bit values with barrier.
Atomic bitwise AND of two 32-bit values returning original.
Atomic bitwise AND of two 32-bit values returning original with barrier.
Atomic bitwise OR of two 32-bit values.
Atomic bitwise OR of two 32-bit values with barrier.
Atomic bitwise OR of two 32-bit values returning original.
Atomic bitwise OR of two 32-bit values returning original with barrier.
Atomic bitwise XOR of two 32-bit values.
Atomic bitwise XOR of two 32-bit values with barrier.
Atomic bitwise XOR of two 32-bit values returning original.
Atomic bitwise XOR of two 32-bit values returning original with barrier.
All functions in this group return the new value.
Atomically adds two 32-bit values.
Atomically adds two 32-bit values.
Atomically adds two 64-bit values.
Atomically adds two 64-bit values with a barrier.
Atomically decrements a 32-bit value.
Atomically increments a 32-bit value with a barrier.
Atomically decrements a 64-bit value.
Atomically decrements a 64-bit value with a barrier.
Atomically increments a 32-bit value.
Atomically increments a 32-bit value with a barrier.
Atomically increments a 64-bit value.
Atomically increments a 64-bit value with a barrier.
Functions in this group return true if the swap occured. There are several versions, depending on data type and on whether or not a barrier is used.
Compare and swap for 32-bit values.
Compare and swap for 32-bit values with barrier.
Compare and swap for uint64_t
values.
Compare and swap for uint64_t
values.
Compare and swap for int
values.
Compare and swap for int
values.
Compare and swap for long
values.
Compare and swap for long
values.
Compare and swap pointers.
Compare and swap pointers with barrier.
Atomic test and clear
Atomic test and clear
Atomic test and set
Atomic test and set with barrier
Atomically adds two 32-bit values.
Atomically adds two 32-bit values.
Atomically adds two 64-bit values.
Atomically adds two 64-bit values with a barrier.
Atomic bitwise AND of two 32-bit values.
Atomic bitwise AND of two 32-bit values with barrier.
Atomic bitwise AND of two 32-bit values returning original.
Atomic bitwise AND of two 32-bit values returning original with barrier.
Compare and swap for 32-bit values.
Compare and swap for 32-bit values with barrier.
Compare and swap for uint64_t
values.
Compare and swap for uint64_t
values.
Compare and swap for int
values.
Compare and swap for int
values.
Compare and swap for long
values.
Compare and swap for long
values.
Compare and swap pointers.
Compare and swap pointers with barrier.
Atomically decrements a 32-bit value.
Atomically increments a 32-bit value with a barrier.
Atomically decrements a 64-bit value.
Atomically decrements a 64-bit value with a barrier.
Dequeue an item from a list.
Enqueue an item onto a list.
Atomically increments a 32-bit value.
Atomically increments a 32-bit value with a barrier.
Atomically increments a 64-bit value.
Atomically increments a 64-bit value with a barrier.
Atomic bitwise OR of two 32-bit values.
Atomic bitwise OR of two 32-bit values with barrier.
Atomic bitwise OR of two 32-bit values returning original.
Atomic bitwise OR of two 32-bit values returning original with barrier.
Atomic test and clear
Atomic test and clear
Atomic test and set
Atomic test and set with barrier
Atomic bitwise XOR of two 32-bit values.
Atomic bitwise XOR of two 32-bit values with barrier.
Atomic bitwise XOR of two 32-bit values returning original.
Atomic bitwise XOR of two 32-bit values returning original with barrier.
Memory barrier.
Locks a spinlock
Locks a spinlock if it would not block
Unlocks a spinlock
OSAtomicAdd32 |
Atomically adds two 32-bit values.
int32_t OSAtomicAdd32( int32_t __theAmount, volatile int32_t *__theValue );
Returns the new value.
This function adds the value in __theAmount
to the
value referenced by __theValue
and stores the result at
the address specified by __theValue
.
OSAtomicAdd32Barrier |
Atomically adds two 32-bit values.
int32_t OSAtomicAdd32Barrier( int32_t __theAmount, volatile int32_t *__theValue );
Returns the new value.
This function adds the value in __theAmount
to the
value referenced by __theValue
and stores the result at
the address specified by __theValue
.
This function is equivalent to OSAtomicAdd32
except that it also introduces a barrier.
OSAtomicAdd64 |
Atomically adds two 64-bit values.
int64_t OSAtomicAdd64( int64_t __theAmount, volatile int64_t *__theValue );
This function adds the value in __theAmount
to the
value referenced by __theValue
and stores the result at
the address specified by __theValue
.
OSAtomicAdd64Barrier |
Atomically adds two 64-bit values with a barrier.
int64_t OSAtomicAdd64Barrier( int64_t __theAmount, volatile int64_t *__theValue );
Returns the new value.
This function adds the value in __theAmount
to the
value referenced by __theValue
and stores the result at
the address specified by __theValue
.
This function is equivalent to OSAtomicAdd64
except that it also introduces a barrier.
OSAtomicAnd32 |
Atomic bitwise AND of two 32-bit values.
int32_t OSAtomicAnd32( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the new value.
This function performs the bitwise AND of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
OSAtomicAnd32Barrier |
Atomic bitwise AND of two 32-bit values with barrier.
int32_t OSAtomicAnd32Barrier( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the new value.
This function performs the bitwise AND of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
This function is equivalent to OSAtomicAnd32
except that it also introduces a barrier.
OSAtomicAnd32Orig |
Atomic bitwise AND of two 32-bit values returning original.
int32_t OSAtomicAnd32Orig( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the original value referenced by __theValue
.
This function performs the bitwise AND of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
OSAtomicAnd32OrigBarrier |
Atomic bitwise AND of two 32-bit values returning original with barrier.
int32_t OSAtomicAnd32OrigBarrier( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the original value referenced by __theValue
.
This function performs the bitwise AND of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
This function is equivalent to OSAtomicAnd32Orig
except that it also introduces a barrier.
OSAtomicCompareAndSwap32 |
Compare and swap for 32-bit values.
bool OSAtomicCompareAndSwap32( int32_t __oldValue, int32_t __newValue, volatile int32_t *__theValue );
Returns the original value referenced by __theValue
.
This function compares the value in __oldValue
to the value
referenced by __theValue
. If the values match, this function
stores the value from __newValue
at the address specified
by __theValue
.
OSAtomicCompareAndSwap32Barrier |
Compare and swap for 32-bit values with barrier.
bool OSAtomicCompareAndSwap32Barrier( int32_t __oldValue, int32_t __newValue, volatile int32_t *__theValue );
Returns the original value referenced by __theValue
.
This function compares the value in __oldValue
to the value
referenced by __theValue
. If the values match, this function
stores the value from __newValue
at the address specified
by __theValue
.
This function is equivalent to OSAtomicCompareAndSwap32
except that it also introduces a barrier.
OSAtomicCompareAndSwap64 |
Compare and swap for uint64_t
values.
bool OSAtomicCompareAndSwap64( int64_t __oldValue, int64_t __newValue, volatile int64_t *__theValue );
Returns the original value referenced by __theValue
.
This function compares the value in __oldValue
to the value
referenced by __theValue
. If the values match, this function
stores the value from __newValue
at the address specified
by __theValue
.
OSAtomicCompareAndSwap64Barrier |
Compare and swap for uint64_t
values.
bool OSAtomicCompareAndSwap64Barrier( int64_t __oldValue, int64_t __newValue, volatile int64_t *__theValue );
Returns the original value referenced by __theValue
.
This function compares the value in __oldValue
to the value
referenced by __theValue
. If the values match, this function
stores the value from __newValue
at the address specified
by __theValue
.
This function is equivalent to OSAtomicCompareAndSwap64
except that it also introduces a barrier.
OSAtomicCompareAndSwapInt |
Compare and swap for int
values.
bool OSAtomicCompareAndSwapInt( int __oldValue, int __newValue, volatile int *__theValue );
Returns the original value referenced by __theValue
.
This function compares the value in __oldValue
to the value
referenced by __theValue
. If the values match, this function
stores the value from __newValue
at the address specified
by __theValue
.
This function is equivalent to OSAtomicCompareAndSwap32
.
OSAtomicCompareAndSwapIntBarrier |
Compare and swap for int
values.
bool OSAtomicCompareAndSwapIntBarrier( int __oldValue, int __newValue, volatile int *__theValue );
Returns the original value referenced by __theValue
.
This function compares the value in __oldValue
to the value
referenced by __theValue
. If the values match, this function
stores the value from __newValue
at the address specified
by __theValue
.
This function is equivalent to OSAtomicCompareAndSwapInt
except that it also introduces a barrier.
This function is equivalent to OSAtomicCompareAndSwap32Barrier
.
OSAtomicCompareAndSwapLong |
Compare and swap for long
values.
bool OSAtomicCompareAndSwapLong( long __oldValue, long __newValue, volatile long *__theValue );
Returns the original value referenced by __theValue
.
This function compares the value in __oldValue
to the value
referenced by __theValue
. If the values match, this function
stores the value from __newValue
at the address specified
by __theValue
.
This function is equivalent to OSAtomicCompareAndSwap32
on 32-bit architectures,
or OSAtomicCompareAndSwap64
on 64-bit architectures.
OSAtomicCompareAndSwapLongBarrier |
Compare and swap for long
values.
bool OSAtomicCompareAndSwapLongBarrier( long __oldValue, long __newValue, volatile long *__theValue );
Returns the original value referenced by __theValue
.
This function compares the value in __oldValue
to the value
referenced by __theValue
. If the values match, this function
stores the value from __newValue
at the address specified
by __theValue
.
This function is equivalent to OSAtomicCompareAndSwapLong
except that it also introduces a barrier.
This function is equivalent to OSAtomicCompareAndSwap32
on 32-bit architectures,
or OSAtomicCompareAndSwap64
on 64-bit architectures.
OSAtomicCompareAndSwapPtr |
Compare and swap pointers.
bool OSAtomicCompareAndSwapPtr( void *__oldValue, void *__newValue, void *volatile *__theValue );
Returns the original value referenced by __theValue
.
This function compares the pointer stored in __oldValue
to the pointer
stored in __theValue
. If the pointers match, this function
stores the pointer from __newValue
at the address specified
by __theValue
.
OSAtomicCompareAndSwapPtrBarrier |
Compare and swap pointers with barrier.
bool OSAtomicCompareAndSwapPtrBarrier( void *__oldValue, void *__newValue, void *volatile *__theValue );
Returns the original value referenced by __theValue
.
This function compares the pointer stored in __oldValue
to the pointer
stored in __theValue
. If the pointers match, this function
stores the pointer from __newValue
at the address specified
by __theValue
.
This function is equivalent to OSAtomicCompareAndSwapPtr
except that it also introduces a barrier.
OSAtomicDecrement32 |
Atomically decrements a 32-bit value.
__inline static int32_t OSAtomicDecrement32( volatile int32_t *__theValue )
OSAtomicDecrement32Barrier |
Atomically increments a 32-bit value with a barrier.
__inline static int32_t OSAtomicDecrement32Barrier( volatile int32_t *__theValue )
Returns the new value.
This function is equivalent to OSAtomicDecrement32
except that it also introduces a barrier.
OSAtomicDecrement64 |
Atomically decrements a 64-bit value.
__inline static int64_t OSAtomicDecrement64( volatile int64_t *__theValue )
Returns the new value.
This function is equivalent to OSAtomicIncrement64
except that it also introduces a barrier.
OSAtomicDecrement64Barrier |
Atomically decrements a 64-bit value with a barrier.
__inline static int64_t OSAtomicDecrement64Barrier( volatile int64_t *__theValue )
Returns the new value.
This function is equivalent to OSAtomicDecrement64
except that it also introduces a barrier.
OSAtomicDequeue |
Dequeue an item from a list.
void* OSAtomicDequeue( OSQueueHead *__list, size_t __offset);
__list
The list on which you want to enqueue the item.
__offset
The "offset" parameter is the offset (in bytes) of the link field
from the beginning of the data structure being queued (__new
).
The link field should be a pointer type.
Returns the most recently enqueued element, or NULL
if the
list is empty.
Memory barriers are incorporated as needed to permit thread-safe access to the queue element.
OSAtomicEnqueue |
Enqueue an item onto a list.
void OSAtomicEnqueue( OSQueueHead *__list, void *__new, size_t __offset);
__list
The list on which you want to enqueue the item.
__new
The item to add.
__offset
The "offset" parameter is the offset (in bytes) of the link field
from the beginning of the data structure being queued (__new
).
The link field should be a pointer type.
Memory barriers are incorporated as needed to permit thread-safe access to the queue element.
OSAtomicIncrement32 |
Atomically increments a 32-bit value.
__inline static int32_t OSAtomicIncrement32( volatile int32_t *__theValue )
OSAtomicIncrement32Barrier |
Atomically increments a 32-bit value with a barrier.
__inline static int32_t OSAtomicIncrement32Barrier( volatile int32_t *__theValue )
Returns the new value.
This function is equivalent to OSAtomicIncrement32
except that it also introduces a barrier.
OSAtomicIncrement64 |
Atomically increments a 64-bit value.
__inline static int64_t OSAtomicIncrement64( volatile int64_t *__theValue )
OSAtomicIncrement64Barrier |
Atomically increments a 64-bit value with a barrier.
__inline static int64_t OSAtomicIncrement64Barrier( volatile int64_t *__theValue )
Returns the new value.
This function is equivalent to OSAtomicIncrement64
except that it also introduces a barrier.
OSAtomicOr32 |
Atomic bitwise OR of two 32-bit values.
int32_t OSAtomicOr32( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the new value.
This function performs the bitwise OR of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
OSAtomicOr32Barrier |
Atomic bitwise OR of two 32-bit values with barrier.
int32_t OSAtomicOr32Barrier( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the new value.
This function performs the bitwise OR of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
This function is equivalent to OSAtomicOr32
except that it also introduces a barrier.
OSAtomicOr32Orig |
Atomic bitwise OR of two 32-bit values returning original.
int32_t OSAtomicOr32Orig( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the original value referenced by __theValue
.
This function performs the bitwise OR of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
OSAtomicOr32OrigBarrier |
Atomic bitwise OR of two 32-bit values returning original with barrier.
int32_t OSAtomicOr32OrigBarrier( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the original value referenced by __theValue
.
This function performs the bitwise OR of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
This function is equivalent to OSAtomicOr32Orig
except that it also introduces a barrier.
OSAtomicTestAndClear |
Atomic test and clear
bool OSAtomicTestAndClear( uint32_t __n, volatile void *__theAddress );
Returns the original value of the bit being tested.
This function tests a bit in the value referenced by __theAddress
and if it is not cleared, clears it. The bit is chosen by the value of __n
.
The bits are numbered in order beginning with bit 1 as the lowest order bit.
For example, if __theAddress
points to a 64-bit value,
to compare the value of the highest bit, you would specify 64
for
__n
.
OSAtomicTestAndClearBarrier |
Atomic test and clear
bool OSAtomicTestAndClearBarrier( uint32_t __n, volatile void *__theAddress );
Returns the original value of the bit being tested.
This function tests a bit in the value referenced by __theAddress
and if it is not cleared, clears it. The bit is chosen by the value of __n
.
The bits are numbered in order beginning with bit 1 as the lowest order bit.
For example, if __theAddress
points to a 64-bit value,
to compare the value of the highest bit, you would specify 64
for
__n
.
This function is equivalent to OSAtomicTestAndSet
except that it also introduces a barrier.
OSAtomicTestAndSet |
Atomic test and set
bool OSAtomicTestAndSet( uint32_t __n, volatile void *__theAddress );
Returns the original value of the bit being tested.
This function tests a bit in the value referenced by __theAddress
and if it is not set, sets it. The bit is chosen by the value of __n
.
The bits are numbered in order beginning with bit 1 as the lowest order bit.
For example, if __theAddress
points to a 64-bit value,
to compare the value of the highest bit, you would specify 64
for
__n
.
OSAtomicTestAndSetBarrier |
Atomic test and set with barrier
bool OSAtomicTestAndSetBarrier( uint32_t __n, volatile void *__theAddress );
Returns the original value of the bit being tested.
This function tests a bit in the value referenced by __theAddress
and if it is not set, sets it. The bit is chosen by the value of __n
.
The bits are numbered in order beginning with bit 1 as the lowest order bit.
For example, if __theAddress
points to a 64-bit value,
to compare the value of the highest bit, you would specify 64
for
__n
.
This function is equivalent to OSAtomicTestAndSet
except that it also introduces a barrier.
OSAtomicXor32 |
Atomic bitwise XOR of two 32-bit values.
int32_t OSAtomicXor32( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the new value.
This function performs the bitwise exclusive OR of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
OSAtomicXor32Barrier |
Atomic bitwise XOR of two 32-bit values with barrier.
int32_t OSAtomicXor32Barrier( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the new value.
This function performs the bitwise exclusive OR of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
This function is equivalent to OSAtomicXor32
except that it also introduces a barrier.
OSAtomicXor32Orig |
Atomic bitwise XOR of two 32-bit values returning original.
int32_t OSAtomicXor32Orig( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the original value referenced by __theValue
.
This function performs the bitwise exclusive OR of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
OSAtomicXor32OrigBarrier |
Atomic bitwise XOR of two 32-bit values returning original with barrier.
int32_t OSAtomicXor32OrigBarrier( uint32_t __theMask, volatile uint32_t *__theValue );
Returns the original value referenced by __theValue
.
This function performs the bitwise exclusive OR of the value in __theAmount
with the value referenced by __theValue
and stores the result at
the address specified by __theValue
.
This function is equivalent to OSAtomicXor32Orig
except that it also introduces a barrier.
OSMemoryBarrier |
Memory barrier.
void OSMemoryBarrier( void );
This function serves as both a read and write barrier.
OSSpinLockLock |
Locks a spinlock
void OSSpinLockLock( volatile OSSpinLock *__lock );
Although the lock operation spins, it employs various strategies to back off if the lock is held, making it immune to most priority-inversion livelocks.
OSSpinLockTry |
Locks a spinlock if it would not block
bool OSSpinLockTry( volatile OSSpinLock *__lock );
Returns false
if the lock was already held by another thread,
true
if it took the lock successfully.
OSSpinLockUnlock |
Unlocks a spinlock
void OSSpinLockUnlock( volatile OSSpinLock *__lock );
The data structure for a queue head.
Data type for a spinlock.
OSQueueHead |
The data structure for a queue head.
#if defined(__x86_64__) typedef volatile struct { void *opaque1; long opaque2; } OSQueueHead __attribute__ ((aligned (16))); #else typedef volatile struct { void *opaque1; long opaque2; } OSQueueHead; #endif
You should always initialize a queue head structure with the
initialization vector OS_ATOMIC_QUEUE_INIT
before use.
OSSpinLock |
Data type for a spinlock.
typedef int32_t OSSpinLock;
You should always initialize a spinlock to OS_SPINLOCK_INIT
before
using it.
The initialization vector for a queue head.
The default value for an OSSpinLock
.
OS_ATOMIC_QUEUE_INIT |
The initialization vector for a queue head.
#define OS_ATOMIC_QUEUE_INIT
OS_SPINLOCK_INIT |
The default value for an OSSpinLock
.
#define OS_SPINLOCK_INIT 0
The convention is that unlocked is zero, locked is nonzero.
Last Updated: 2009-10-15