OSAtomicAdd64, OSAtomicAdd64Barrier, OSAtomicIncrement64,
     OSAtomicIncrement64Barrier, OSAtomicDecrement64,
     OSAtomicDecrement64Barrier, OSAtomicCompareAndSwap32,
     OSAtomicCompareAndSwap32Barrier, OSAtomicCompareAndSwap64,
     OSAtomicCompareAndSwap64Barrier, OSAtomicTestAndSet,
     OSAtomicTestAndSetBarrier, OSAtomicTestAndClear,
     OSAtomicTestAndClearBarrier -- atomic add, increment, decrement, or, and,
     xor, compare and swap, test and set, and test and clear

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <libkern/OSAtomic.h>

     int32_t
     OSAtomicAdd32(int32_t theAmount, int32_t *theValue);

     int32_t
     OSAtomicAdd32Barrier(int32_t theAmount, int32_t *theValue);

     int32_t
     OSAtomicIncrement32(int32_t *theValue);

     int32_t
     OSAtomicIncrement32Barrier(int32_t *theValue);

     int32_t
     OSAtomicDecrement32(int32_t *theValue);

     int32_t
     OSAtomicDecrement32Barrier(int32_t *theValue);

     int32_t
     OSAtomicOr32(uint32_t theMask, uint32_t *theValue);

     int32_t
     OSAtomicOr32Barrier(uint32_t theMask, uint32_t *theValue);

     int32_t
     OSAtomicAnd32(uint32_t theMask, uint32_t *theValue);

     int32_t
     OSAtomicAnd32Barrier(uint32_t theMask, uint32_t *theValue);

     int32_t
     OSAtomicXor32(uint32_t theMask, uint32_t *theValue);

     int32_t
     OSAtomicXor32Barrier(uint32_t theMask, uint32_t *theValue);

     int64_t
     int64_t
     OSAtomicDecrement64Barrier(int64_t *theValue);

     bool
     OSAtomicCompareAndSwap32(int32_t oldValue, int32_t newValue,
         int32_t *theValue);

     bool
     OSAtomicCompareAndSwap32Barrier(int32_t oldValue, int32_t newValue,
         int32_t *theValue);

     bool
     OSAtomicCompareAndSwap64(int64_t oldValue, int64_t newValue,
         int64_t *theValue);

     bool
     OSAtomicCompareAndSwap64Barrier(int64_t oldValue, int64_t newValue,
         int64_t *theValue);

     bool
     OSAtomicTestAndSet(uint32_t n, void *theAddress);

     bool
     OSAtomicTestAndSetBarrier(uint32_t n, void *theAddress);

     bool
     OSAtomicTestAndClear(uint32_t n, void *theAddress);

     bool
     OSAtomicTestAndClearBarrier(uint32_t n, void *theAddress);

DESCRIPTION

     These functions are thread and multiprocessor safe.  For each function,
     there is a version that does and anoother that does not incorporate a
     memory barrier.  Barriers strictly order memory access on a weakly-
     ordered architecture such as PPC.  All loads and stores executed in
     sequential program order before the barrier will complete before any load
     or store executed after the barrier.  On a uniprocessor, the barrier
     operation is typically a nop.  On a multiprocessor, the barrier can be
     quite expensive.

     Most code will want to use the barrier functions to insure 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, then you MUST
     use OSAtomicIncrement32Barrier() to ensure that the stores to your data
     structure complete before the atomic add.  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 much faster to use OSAtomicIn-
     crement32().  If you are unsure which version to use, prefer the barrier
     OSAtomicTestAndSet() and OSAtomicTestAndClear() operate on bit (0x80 >> (
     n & 7)) of byte ((char*) theAddress + ( n >> 3)).  They set the named bit
     to either 1 or 0, respectively.  theAddress need not be aligned.

RETURN VALUES

     The arithmetic and logical operations return the new value, after the
     operation has been performed.  The compare-and-swap operations return
     true if the comparison was equal, ie if the swap occured.  The bit test
     and set/clear operations return the original value of the bit.

SEE ALSO

     atomicqueue(3), spinlock(3), barrier(3)

Darwin                           May 26, 2004                           Darwin