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

NAME
     OOSSAAttoommiiccAAdddd3322, OOSSAAttoommiiccAAdddd3322BBaarrrriieerr, OOSSAAttoommiiccIInnccrreemmeenntt3322,
     OOSSAAttoommiiccIInnccrreemmeenntt3322BBaarrrriieerr, OOSSAAttoommiiccDDeeccrreemmeenntt3322,
     OOSSAAttoommiiccDDeeccrreemmeenntt3322BBaarrrriieerr, OOSSAAttoommiiccOOrr3322, OOSSAAttoommiiccOOrr3322BBaarrrriieerr,
     OOSSAAttoommiiccOOrr3322OOrriigg, OOSSAAttoommiiccOOrr3322OOrriiggBBaarrrriieerr, OOSSAAttoommiiccAAnndd3322,
     OOSSAAttoommiiccAAnndd3322BBaarrrriieerr, OOSSAAttoommiiccAAnndd3322OOrriigg, OOSSAAttoommiiccAAnndd3322OOrriiggBBaarrrriieerr,
     OOSSAAttoommiiccXXoorr3322, OOSSAAttoommiiccXXoorr3322BBaarrrriieerr, OOSSAAttoommiiccXXoorr3322OOrriigg,
     OOSSAAttoommiiccXXoorr3322OOrriiggBBaarrrriieerr, OOSSAAttoommiiccAAdddd6644, OOSSAAttoommiiccAAdddd6644BBaarrrriieerr,
     OOSSAAttoommiiccIInnccrreemmeenntt6644, OOSSAAttoommiiccIInnccrreemmeenntt6644BBaarrrriieerr, OOSSAAttoommiiccDDeeccrreemmeenntt6644,
     OOSSAAttoommiiccDDeeccrreemmeenntt6644BBaarrrriieerr, OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappIInntt,
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappIInnttBBaarrrriieerr, OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappLLoonngg,
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappLLoonnggBBaarrrriieerr, OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappPPttrr,
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappPPttrrBBaarrrriieerr, OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp3322,
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp3322BBaarrrriieerr, OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp6644,
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp6644BBaarrrriieerr, OOSSAAttoommiiccTTeessttAAnnddSSeett,
     OOSSAAttoommiiccTTeessttAAnnddSSeettBBaarrrriieerr, OOSSAAttoommiiccTTeessttAAnnddCClleeaarr,
     OOSSAAttoommiiccTTeessttAAnnddCClleeaarrBBaarrrriieerr, OOSSSSppiinnLLoocckkTTrryy, OOSSSSppiinnLLoocckkLLoocckk,
     OOSSSSppiinnLLoocckkUUnnlloocckk, OOSSAAttoommiiccEEnnqquueeuuee, OOSSAAttoommiiccDDeeqquueeuuee - atomic add, incre-
     ment, decrement, or, and, xor, compare and swap, test and set, test and
     clear, spinlocks, and lockless queues

LLIIBBRRAARRYY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##iinncclluuddee <>

     int32t
     OOSSAAttoommiiccAAdddd3322(int32t theAmount, volatile int32t *theValue);

     int32t
     OOSSAAttoommiiccAAdddd3322BBaarrrriieerr(int32t theAmount, volatile int32t *theValue);

     int32t
     OOSSAAttoommiiccIInnccrreemmeenntt3322(volatile int32t *theValue);

     int32t
     OOSSAAttoommiiccIInnccrreemmeenntt3322BBaarrrriieerr(volatile int32t *theValue);

     int32t
     OOSSAAttoommiiccDDeeccrreemmeenntt3322(volatile int32t *theValue);

     int32t
     OOSSAAttoommiiccDDeeccrreemmeenntt3322BBaarrrriieerr(volatile int32t *theValue);

     int32t
     OOSSAAttoommiiccOOrr3322(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccOOrr3322BBaarrrriieerr(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccAAnndd3322(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccAAnndd3322BBaarrrriieerr(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccXXoorr3322(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccXXoorr3322BBaarrrriieerr(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccOOrr3322OOrriigg(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccOOrr3322OOrriiggBBaarrrriieerr(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccAAnndd3322OOrriigg(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccAAnndd3322OOrriiggBBaarrrriieerr(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccXXoorr3322OOrriigg(uint32t theMask, volatile uint32t *theValue);

     int32t
     OOSSAAttoommiiccXXoorr3322OOrriiggBBaarrrriieerr(uint32t theMask, volatile uint32t *theValue);

     int64t
     OOSSAAttoommiiccAAdddd6644(int64t theAmount, volatile int64t *theValue);

     int64t
     OOSSAAttoommiiccAAdddd6644BBaarrrriieerr(int64t theAmount, volatile int64t *theValue);

     int64t
     OOSSAAttoommiiccIInnccrreemmeenntt6644(volatile int64t *theValue);

     int64t
     OOSSAAttoommiiccIInnccrreemmeenntt6644BBaarrrriieerr(volatile int64t *theValue);

     int64t
     OOSSAAttoommiiccDDeeccrreemmeenntt6644(volatile int64t *theValue);

     int64t
     OOSSAAttoommiiccDDeeccrreemmeenntt6644BBaarrrriieerr(volatile int64t *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappIInntt(int oldValue, int newValue,
         volatile int *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappIInnttBBaarrrriieerr(int oldValue, int newValue,
         volatile int *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappLLoonngg(long oldValue, long newValue,
         volatile long *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappLLoonnggBBaarrrriieerr(long oldValue, long newValue,
         volatile long *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappPPttrr(void* oldValue, void* newValue,
         void* volatile *theValue);

     bool
     OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaappPPttrrBBaarrrriieerr(void* oldValue, void* newValue,
         void* volatile *theValue);

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

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

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

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

     bool
     OOSSAAttoommiiccTTeessttAAnnddSSeett(uint32t n, volatile void *theAddress);

     bool
     OOSSAAttoommiiccTTeessttAAnnddSSeettBBaarrrriieerr(uint32t n, volatile void *theAddress);

     bool
     OOSSAAttoommiiccTTeessttAAnnddCClleeaarr(uint32t n, volatile void *theAddress);

     bool
     OOSSAAttoommiiccTTeessttAAnnddCClleeaarrBBaarrrriieerr(uint32t n, volatile void *theAddress);

     bool
     OOSSSSppiinnLLoocckkTTrryy(OSSpinLock *lock);

     void
     OOSSSSppiinnLLoocckkLLoocckk(OSSpinLock *lock);

     void
     OOSSSSppiinnLLoocckkUUnnlloocckk(OSSpinLock *lock);

     void
     OOSSAAttoommiiccEEnnqquueeuuee(OSQueueHead *list, void *new, sizet offset);

     void*
     OOSSAAttoommiiccDDeeqquueeuuee(OSQueueHead *list, sizet offset);

DESCRIPTION
     These functions are thread and multiprocessor safe.  For each function,
     there is a version that does and another that does not incorporate a mem-
     ory 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 expen-
     sive.

     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.  There are four versions of each
     logical operation, depending on whether or not there is a barrier, and
     whether the return value is the result of the operation (eg,
     OOSSAAttoommiiccOOrr3322() ) or the original value before the operation (eg,
     OOSSAAttoommiiccOOrr3322OOrriigg() ).

     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 not implemented for 32-bit processes on PPC
     platforms.

     The OOSSAAttoommiiccCCoommppaarreeAAnnddSSwwaapp() operations 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.

     The routines OOSSAAttoommiiccEEnnqquueeuuee() and OOSSAAttoommiiccDDeeqquueeuuee() operate on singly
     linked LIFO queues.  Ie, a dequeue operation will return the most
     recently enqueued element, or NULL if the list is empty.  The operations
     are lockless, and barriers are used as necessary to permit thread-safe
     access to the queue element.  offset is the offset in bytes to the link
     field in the queue element.  For example:

                   typedef struct elem {
                           long    data1;
                           struct elem *link;
                           int     data2;
                   } elemt;

                   elemt fred, mary, *p;

                   OSQueueHead q = OSATOMICQUEUEINIT;

                   OSAtomicEnqueue( &q, &fred, offsetof(elemt,link) );
                   OSAtomicEnqueue( &q, &mary, offsetof(elemt,link) );

                   p = OSAtomicDequeue( &q, offsetof(elemt,link) );

     In this example, the call of OOSSAAttoommiiccDDeeqquueeuuee() will return a ptr to mary.

RETURN VALUES
     The arithmetic operations return the new value, after the operation has
     been performed.  The boolean operations come in two styles, one of which
     returns the new value, and one of which (the "Orig" versions) returns the
     old.  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.  The dequeue operation returns the
     most recently enqueued element, or NULL if the list in empty.

SEE ALSO
     spinlock(3), barrier(3)

HISTORY     Most of these functions first appeared in Mac OS 10.4 (Tiger).  The
     "Orig" forms of the boolean operations, the "int", "long" and "ptr" forms
     of compare-and-swap, and lockless enqueue/dequeue first appeared in Mac
     OS 10.5 (Leopard).

Darwin                           May 26, 2004                           Darwin