ATOMIC(3) BSD Library Functions Manual ATOMIC(3)

NAME
     OOSSAAttoommiiccAAdddd3322, OOSSAAttoommiiccAAdddd3322BBaarrrriieerr, OOSSAAttoommiiccIInnccrreemmeenntt3322,
     OOSSAAttoommiiccIInnccrreemmeenntt3322BBaarrrriieerr, OOSSAAttoommiiccDDeeccrreemmeenntt3322,
     OOSSAAttoommiiccDDeeccrreemmeenntt3322BBaarrrriieerr, OOSSAAttoommiiccOOrr3322, OOSSAAttoommiiccOOrr3322BBaarrrriieerr,
     OOSSAAttoommiiccAAnndd3322, OOSSAAttoommiiccAAnndd3322BBaarrrriieerr, OOSSAAttoommiiccXXoorr3322, OOSSAAttoommiiccXXoorr3322BBaarrrriieerr,
     OOSSAAttoommiiccAAdddd6644, OOSSAAttoommiiccAAdddd6644BBaarrrriieerr, OOSSAAttoommiiccIInnccrreemmeenntt6644,
     OOSSAAttoommiiccIInnccrreemmeenntt6644BBaarrrriieerr, OOSSAAttoommiiccDDeeccrreemmeenntt6644,
     OOSSAAttoommiiccDDeeccrreemmeenntt6644BBaarrrriieerr, OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp3322,
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp3322BBaarrrriieerr, OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp6644,
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp6644BBaarrrriieerr, OOSSAAttoommiiccTTeessttAAnnddSSeett,
     OOSSAAttoommiiccTTeessttAAnnddSSeettBBaarrrriieerr, OOSSAAttoommiiccTTeessttAAnnddCClleeaarr,
     OOSSAAttoommiiccTTeessttAAnnddCClleeaarrBBaarrrriieerr - atomic add, increment, decrement, or, and,
     xor, compare and swap, test and set, and test and clear

LLIIBBRRAARRYY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##iinncclluuddee <>

     int32t
     OOSSAAttoommiiccAAdddd3322(int32t theAmount, int32t *theValue);

     int32t
     OOSSAAttoommiiccAAdddd3322BBaarrrriieerr(int32t theAmount, int32t *theValue);

     int32t
     OOSSAAttoommiiccIInnccrreemmeenntt3322(int32t *theValue);

     int32t
     OOSSAAttoommiiccIInnccrreemmeenntt3322BBaarrrriieerr(int32t *theValue);

     int32t
     OOSSAAttoommiiccDDeeccrreemmeenntt3322(int32t *theValue);

     int32t
     OOSSAAttoommiiccDDeeccrreemmeenntt3322BBaarrrriieerr(int32t *theValue);

     int32t
     OOSSAAttoommiiccOOrr3322(uint32t theMask, uint32t *theValue);

     int32t
     OOSSAAttoommiiccOOrr3322BBaarrrriieerr(uint32t theMask, uint32t *theValue);

     int32t
     OOSSAAttoommiiccAAnndd3322(uint32t theMask, uint32t *theValue);

     int32t
     OOSSAAttoommiiccAAnndd3322BBaarrrriieerr(uint32t theMask, uint32t *theValue);

     int32t
     OOSSAAttoommiiccXXoorr3322(uint32t theMask, uint32t *theValue);

     int32t
     OOSSAAttoommiiccXXoorr3322BBaarrrriieerr(uint32t theMask, uint32t *theValue);

     int64t
     OOSSAAttoommiiccAAdddd6644(int64t theAmount, int64t *theValue);

     int64t
     OOSSAAttoommiiccAAdddd6644BBaarrrriieerr(int64t theAmount, int64t *theValue);

     int64t
     OOSSAAttoommiiccIInnccrreemmeenntt6644(int64t *theValue);

     int64t
     OOSSAAttoommiiccIInnccrreemmeenntt6644BBaarrrriieerr(int64t *theValue);

     int64t
     OOSSAAttoommiiccDDeeccrreemmeenntt6644(int64t *theValue);

     int64t
     OOSSAAttoommiiccDDeeccrreemmeenntt6644BBaarrrriieerr(int64t *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp3322(int32t oldValue, int32t newValue,
         int32t *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp3322BBaarrrriieerr(int32t oldValue, int32t newValue,
         int32t *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp6644(int64t oldValue, int64t newValue,
         int64t *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp6644BBaarrrriieerr(int64t oldValue, int64t newValue,
         int64t *theValue);

     bool
     OOSSAAttoommiiccTTeessttAAnnddSSeett(uint32t n, void *theAddress);

     bool
     OOSSAAttoommiiccTTeessttAAnnddSSeettBBaarrrriieerr(uint32t n, void *theAddress);

     bool
     OOSSAAttoommiiccTTeessttAAnnddCClleeaarr(uint32t n, void *theAddress);

     bool
     OOSSAAttoommiiccTTeessttAAnnddCClleeaarrBBaarrrriieerr(uint32t 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
     variants as they are safer.

     The logical (and, or, xor) and bit test operations are layered on top of
     the OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp() primitives.

     The memory address theValue must be naturally aligned, ie 32-bit aligned
     for 32-bit operations and 64-bit aligned for 64-bit operations.

     The 64-bit operations are only implemented for 64-bit processes.

     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp3322() and OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp6644() compare
     oldValue to *theValue, and set *theValue to newValue if the comparison is
     equal.  The comparison and assignment occur as one atomic operation.

     OOSSAAttoommiiccTTeessttAAnnddSSeett() and OOSSAAttoommiiccTTeessttAAnnddCClleeaarr() 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