OSAtomic.h

Overview

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)

Lockless atomic enqueue and dequeue

Group members:

Memory barriers

Group members:

Spinlocks

Group members:

Boolean functions (AND, OR, XOR)

Group members:

Arithmetic functions

Group members:

Compare and swap

Group members:

Functions

OSAtomicAdd32

Atomically adds two 32-bit values.

OSAtomicAdd32Barrier

Atomically adds two 32-bit values.

OSAtomicAdd64

Atomically adds two 64-bit values.

OSAtomicAdd64Barrier

Atomically adds two 64-bit values with a barrier.

OSAtomicAnd32

Atomic bitwise AND of two 32-bit values.

OSAtomicAnd32Barrier

Atomic bitwise AND of two 32-bit values with barrier.

OSAtomicAnd32Orig

Atomic bitwise AND of two 32-bit values returning original.

OSAtomicAnd32OrigBarrier

Atomic bitwise AND of two 32-bit values returning original with barrier.

OSAtomicCompareAndSwap32

Compare and swap for 32-bit values.

OSAtomicCompareAndSwap32Barrier

Compare and swap for 32-bit values with barrier.

OSAtomicCompareAndSwap64

Compare and swap for uint64_t values.

OSAtomicCompareAndSwap64Barrier

Compare and swap for uint64_t values.

OSAtomicCompareAndSwapInt

Compare and swap for int values.

OSAtomicCompareAndSwapIntBarrier

Compare and swap for int values.

OSAtomicCompareAndSwapLong

Compare and swap for long values.

OSAtomicCompareAndSwapLongBarrier

Compare and swap for long values.

OSAtomicCompareAndSwapPtr

Compare and swap pointers.

OSAtomicCompareAndSwapPtrBarrier

Compare and swap pointers with barrier.

OSAtomicDecrement32

Atomically decrements a 32-bit value.

OSAtomicDecrement32Barrier

Atomically increments a 32-bit value with a barrier.

OSAtomicDecrement64

Atomically decrements a 64-bit value.

OSAtomicDecrement64Barrier

Atomically decrements a 64-bit value with a barrier.

OSAtomicDequeue

Dequeue an item from a list.

OSAtomicEnqueue

Enqueue an item onto a list.

OSAtomicIncrement32

Atomically increments a 32-bit value.

OSAtomicIncrement32Barrier

Atomically increments a 32-bit value with a barrier.

OSAtomicIncrement64

Atomically increments a 64-bit value.

OSAtomicIncrement64Barrier

Atomically increments a 64-bit value with a barrier.

OSAtomicOr32

Atomic bitwise OR of two 32-bit values.

OSAtomicOr32Barrier

Atomic bitwise OR of two 32-bit values with barrier.

OSAtomicOr32Orig

Atomic bitwise OR of two 32-bit values returning original.

OSAtomicOr32OrigBarrier

Atomic bitwise OR of two 32-bit values returning original with barrier.

OSAtomicTestAndClear

Atomic test and clear

OSAtomicTestAndClearBarrier

Atomic test and clear

OSAtomicTestAndSet

Atomic test and set

OSAtomicTestAndSetBarrier

Atomic test and set with barrier

OSAtomicXor32

Atomic bitwise XOR of two 32-bit values.

OSAtomicXor32Barrier

Atomic bitwise XOR of two 32-bit values with barrier.

OSAtomicXor32Orig

Atomic bitwise XOR of two 32-bit values returning original.

OSAtomicXor32OrigBarrier

Atomic bitwise XOR of two 32-bit values returning original with barrier.

OSMemoryBarrier

Memory barrier.

OSSpinLockLock

Locks a spinlock

OSSpinLockTry

Locks a spinlock if it would not block

OSSpinLockUnlock

Unlocks a spinlock

Atomically adds two 32-bit values.

int32_t OSAtomicAdd32(
    int32_t __theAmount,
    volatile int32_t *__theValue );  

Return Value

Returns the new value.

Discussion

This function adds the value in __theAmount to the value referenced by __theValue and stores the result at the address specified by __theValue.

Atomically adds two 32-bit values.

int32_t OSAtomicAdd32Barrier(
    int32_t __theAmount,
    volatile int32_t *__theValue );  

Return Value

Returns the new value.

Discussion

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.

Atomically adds two 64-bit values.

int64_t OSAtomicAdd64(
    int64_t __theAmount,
    volatile int64_t *__theValue );  

Discussion

This function adds the value in __theAmount to the value referenced by __theValue and stores the result at the address specified by __theValue.

Atomically adds two 64-bit values with a barrier.

int64_t OSAtomicAdd64Barrier(
    int64_t __theAmount,
    volatile int64_t *__theValue );  

Return Value

Returns the new value.

Discussion

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.

Atomic bitwise AND of two 32-bit values.

int32_t OSAtomicAnd32(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the new value.

Discussion

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.

Atomic bitwise AND of two 32-bit values with barrier.

int32_t OSAtomicAnd32Barrier(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the new value.

Discussion

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.

Atomic bitwise AND of two 32-bit values returning original.

int32_t OSAtomicAnd32Orig(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Atomic bitwise AND of two 32-bit values returning original with barrier.

int32_t OSAtomicAnd32OrigBarrier(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap for 32-bit values.

bool OSAtomicCompareAndSwap32(
    int32_t __oldValue,
    int32_t __newValue,
    volatile int32_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap for 32-bit values with barrier.

bool OSAtomicCompareAndSwap32Barrier(
    int32_t __oldValue,
    int32_t __newValue,
    volatile int32_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap for uint64_t values.

bool OSAtomicCompareAndSwap64(
    int64_t __oldValue,
    int64_t __newValue,
    volatile int64_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap for uint64_t values.

bool OSAtomicCompareAndSwap64Barrier(
    int64_t __oldValue,
    int64_t __newValue,
    volatile int64_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap for int values.

bool OSAtomicCompareAndSwapInt(
    int __oldValue,
    int __newValue,
    volatile int *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap for int values.

bool OSAtomicCompareAndSwapIntBarrier(
    int __oldValue,
    int __newValue,
    volatile int *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap for long values.

bool OSAtomicCompareAndSwapLong(
    long __oldValue,
    long __newValue,
    volatile long *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap for long values.

bool OSAtomicCompareAndSwapLongBarrier(
    long __oldValue,
    long __newValue,
    volatile long *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap pointers.

bool OSAtomicCompareAndSwapPtr(
    void *__oldValue,
    void *__newValue,
    void *volatile *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Compare and swap pointers with barrier.

bool OSAtomicCompareAndSwapPtrBarrier(
    void *__oldValue,
    void *__newValue,
    void *volatile *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Atomically decrements a 32-bit value.

__inline static int32_t OSAtomicDecrement32(
    volatile int32_t *__theValue ) 

Atomically increments a 32-bit value with a barrier.

__inline static int32_t OSAtomicDecrement32Barrier(
    volatile int32_t *__theValue ) 

Return Value

Returns the new value.

Discussion

This function is equivalent to OSAtomicDecrement32 except that it also introduces a barrier.

Atomically decrements a 64-bit value.

__inline static int64_t OSAtomicDecrement64(
    volatile int64_t *__theValue ) 

Return Value

Returns the new value.

Discussion

This function is equivalent to OSAtomicIncrement64 except that it also introduces a barrier.

Atomically decrements a 64-bit value with a barrier.

__inline static int64_t OSAtomicDecrement64Barrier(
    volatile int64_t *__theValue ) 

Return Value

Returns the new value.

Discussion

This function is equivalent to OSAtomicDecrement64 except that it also introduces a barrier.

Dequeue an item from a list.

void* OSAtomicDequeue(
    OSQueueHead *__list,
    size_t __offset);  

Parameters

Return Value

Returns the most recently enqueued element, or NULL if the list is empty.

Discussion

Memory barriers are incorporated as needed to permit thread-safe access to the queue element.

Enqueue an item onto a list.

void OSAtomicEnqueue(
    OSQueueHead *__list,
    void *__new,
    size_t __offset);  

Parameters

Discussion

Memory barriers are incorporated as needed to permit thread-safe access to the queue element.

Atomically increments a 32-bit value.

__inline static int32_t OSAtomicIncrement32(
    volatile int32_t *__theValue ) 

Atomically increments a 32-bit value with a barrier.

__inline static int32_t OSAtomicIncrement32Barrier(
    volatile int32_t *__theValue ) 

Return Value

Returns the new value.

Discussion

This function is equivalent to OSAtomicIncrement32 except that it also introduces a barrier.

Atomically increments a 64-bit value.

__inline static int64_t OSAtomicIncrement64(
    volatile int64_t *__theValue ) 

Atomically increments a 64-bit value with a barrier.

__inline static int64_t OSAtomicIncrement64Barrier(
    volatile int64_t *__theValue ) 

Return Value

Returns the new value.

Discussion

This function is equivalent to OSAtomicIncrement64 except that it also introduces a barrier.

Atomic bitwise OR of two 32-bit values.

int32_t OSAtomicOr32(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the new value.

Discussion

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.

Atomic bitwise OR of two 32-bit values with barrier.

int32_t OSAtomicOr32Barrier(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the new value.

Discussion

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.

Atomic bitwise OR of two 32-bit values returning original.

int32_t OSAtomicOr32Orig(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Atomic bitwise OR of two 32-bit values returning original with barrier.

int32_t OSAtomicOr32OrigBarrier(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Atomic test and clear

bool OSAtomicTestAndClear(
    uint32_t __n,
    volatile void *__theAddress );  

Return Value

Returns the original value of the bit being tested.

Discussion

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.

Atomic test and clear

bool OSAtomicTestAndClearBarrier(
    uint32_t __n,
    volatile void *__theAddress );  

Return Value

Returns the original value of the bit being tested.

Discussion

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.

Atomic test and set

bool OSAtomicTestAndSet(
    uint32_t __n,
    volatile void *__theAddress );  

Return Value

Returns the original value of the bit being tested.

Discussion

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.

Atomic test and set with barrier

bool OSAtomicTestAndSetBarrier(
    uint32_t __n,
    volatile void *__theAddress );  

Return Value

Returns the original value of the bit being tested.

Discussion

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.

Atomic bitwise XOR of two 32-bit values.

int32_t OSAtomicXor32(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the new value.

Discussion

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.

Atomic bitwise XOR of two 32-bit values with barrier.

int32_t OSAtomicXor32Barrier(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the new value.

Discussion

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.

Atomic bitwise XOR of two 32-bit values returning original.

int32_t OSAtomicXor32Orig(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Atomic bitwise XOR of two 32-bit values returning original with barrier.

int32_t OSAtomicXor32OrigBarrier(
    uint32_t __theMask,
    volatile uint32_t *__theValue );  

Return Value

Returns the original value referenced by __theValue.

Discussion

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.

Memory barrier.

void OSMemoryBarrier(
    void );  

Discussion

This function serves as both a read and write barrier.

Locks a spinlock

void OSSpinLockLock(
    volatile OSSpinLock *__lock );  

Discussion

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.

Locks a spinlock if it would not block

bool OSSpinLockTry(
    volatile OSSpinLock *__lock );  

Return Value

Returns false if the lock was already held by another thread, true if it took the lock successfully.

Unlocks a spinlock

void OSSpinLockUnlock(
    volatile OSSpinLock *__lock );  

Typedefs

OSQueueHead

The data structure for a queue head.

OSSpinLock

Data type for a spinlock.

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  

Discussion

You should always initialize a queue head structure with the initialization vector OS_ATOMIC_QUEUE_INIT before use.

Data type for a spinlock.

typedef int32_t OSSpinLock;  

Discussion

You should always initialize a spinlock to OS_SPINLOCK_INIT before using it.

Macro Definitions

OS_ATOMIC_QUEUE_INIT

The initialization vector for a queue head.

OS_SPINLOCK_INIT

The default value for an OSSpinLock.

The initialization vector for a queue head.

#define OS_ATOMIC_QUEUE_INIT  

The default value for an OSSpinLock.

#define OS_SPINLOCK_INIT 0 

Discussion

The convention is that unlocked is zero, locked is nonzero.

Last Updated: 2009-10-15