Mac Developer Library

Developer

OSAtomic.h Reference

Options
Deployment Target:

On This Page

OSAtomic.h Reference

This header declares the OSAtomic group of functions for atomic reading and updating of values.

Included Headers

  • <libkern/OSBase.h>

Functions

  • 32-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    SInt32 OSAddAtomic ( SInt32 amount, volatile SInt32 *address );

    Parameters

    amount

    The amount to add.

    address

    The 4-byte aligned address of the value to update atomically.

    Return Value

    The value before the addition

    Discussion

    The OSAddAtomic function adds the specified amount to the value at the specified address and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 16-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    SInt16 OSAddAtomic16 ( SInt32 amount, volatile SInt16 *address );

    Parameters

    address

    The 2-byte aligned address of the value to update atomically.

    Return Value

    The value before the addition

    Discussion

    The OSAddAtomic16 function adds the specified amount to the value at the specified address and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 64-bit atomic add operation.

    Declaration

    Objective-C

    SInt64 OSAddAtomic64 ( SInt64 theAmount, volatile SInt64 *address );

    Discussion

    See OSAddAtomic.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.5 and later.

  • 8-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    SInt8 OSAddAtomic8 ( SInt32 amount, volatile SInt8 *address );

    Parameters

    amount

    The amount to add.

    address

    The address of the value to update atomically.

    Return Value

    The value before the addition.

    Discussion

    The OSAddAtomic8 function adds the specified amount to the value at the specified address and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 32-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    UInt32 OSBitAndAtomic ( UInt32 mask, volatile UInt32 *address );

    Parameters

    mask

    The mask to logically and with the value.

    address

    The 4-byte aligned address of the value to update atomically.

    Return Value

    The value before the bitwise operation

    Discussion

    The OSBitAndAtomic function logically ands the bits of the specified mask into the value at the specified address and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers..

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 16-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    UInt16 OSBitAndAtomic16 ( UInt32 mask, volatile UInt16 *address );

    Parameters

    mask

    The mask to logically and with the value.

    address

    The 2-byte aligned address of the value to update atomically.

    Return Value

    The value before the bitwise operation.

    Discussion

    The OSBitAndAtomic16 function logically ands the bits of the specified mask into the value at the specified address and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 8-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    UInt8 OSBitAndAtomic8 ( UInt32 mask, volatile UInt8 *address );

    Parameters

    mask

    The mask to logically and with the value.

    address

    The address of the value to update atomically.

    Return Value

    The value before the bitwise operation.

    Discussion

    The OSBitAndAtomic8 function logically ands the bits of the specified mask into the value at the specified address and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 32-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    UInt32 OSBitOrAtomic ( UInt32 mask, volatile UInt32 *address );

    Parameters

    mask

    The mask to logically or with the value.

    address

    The 4-byte aligned address of the value to update atomically.

    Return Value

    The value before the bitwise operation.

    Discussion

    The OSBitOrAtomic function logically ors the bits of the specified mask into the value at the specified address and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 16-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    UInt16 OSBitOrAtomic16 ( UInt32 mask, volatile UInt16 *address );

    Parameters

    mask

    The mask to logically or with the value.

    address

    The 2-byte aligned address of the value to update atomically.

    Return Value

    The value before the bitwise operation.

    Discussion

    The OSBitOrAtomic16 function logically ors the bits of the specified mask into the value at the specified address and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 8-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Declaration

    Objective-C

    UInt8 OSBitOrAtomic8 ( UInt32 mask, volatile UInt8 *address );

    Parameters

    mask

    The mask to logically or with the value.

    address

    The address of the value to update atomically.

    Return Value

    The value before the bitwise operation.

    Discussion

    The OSBitOrAtomic8 function logically ors the bits of the specified mask into the value at the specified address and returns the original value.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 32-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Declaration

    Objective-C

    UInt32 OSBitXorAtomic ( UInt32 mask, volatile UInt32 *address );

    Parameters

    mask

    The mask to logically or with the value.

    address

    The 4-byte aligned address of the value to update atomically.

    Return Value

    The value before the bitwise operation.

    Discussion

    The OSBitXorAtomic function logically xors the bits of the specified mask into the value at the specified address and returns the original value.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 16-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    UInt16 OSBitXorAtomic16 ( UInt32 mask, volatile UInt16 *address );

    Parameters

    mask

    The mask to logically or with the value.

    address

    The 2-byte aligned address of the value to update atomically.

    Return Value

    The value before the bitwise operation.

    Discussion

    The OSBitXorAtomic16 function logically xors the bits of the specified mask into the value at the specified address and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 8-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Declaration

    Objective-C

    UInt8 OSBitXorAtomic8 ( UInt32 mask, volatile UInt8 *address );

    Parameters

    mask

    The mask to logically or with the value.

    address

    The address of the value to update atomically.

    Return Value

    The value before the bitwise operation.

    Discussion

    The OSBitXorAtomic8 function logically xors the bits of the specified mask into the value at the specified address and returns the original value.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    Boolean OSCompareAndSwap ( UInt32 oldValue, UInt32 newValue, volatile UInt32 *address );

    Parameters

    oldValue

    The value to compare at address.

    newValue

    The value to write to address if oldValue compares true.

    address

    The 4-byte aligned address of the data to update atomically.

    Return Value

    true if newValue was written to the address.

    Discussion

    The OSCompareAndSwap function compares the value at the specified address with oldVal. The value of newValue is written to the address only if oldValue and the value at the address are equal. OSCompareAndSwap returns true if newValue is written to the address; otherwise, it returns false.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 64-bit compare and swap operation.

    Declaration

    Objective-C

    Boolean OSCompareAndSwap64 ( UInt64 oldValue, UInt64 newValue, volatile UInt64 *address );

    Discussion

    See OSCompareAndSwap.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.5 and later.

  • Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    Boolean OSCompareAndSwapPtr ( void *oldValue, void *newValue, void * volatile *address );

    Parameters

    oldValue

    The pointer value to compare at address.

    newValue

    The pointer value to write to address if oldValue compares true.

    address

    The pointer-size aligned address of the data to update atomically.

    Return Value

    true if newValue was written to the address.

    Discussion

    The OSCompareAndSwapPtr function compares the pointer-sized value at the specified address with oldVal. The value of newValue is written to the address only if oldValue and the value at the address are equal. OSCompareAndSwapPtr returns true if newValue is written to the address; otherwise, it returns false.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.6 and later.

  • 32-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    SInt32 OSDecrementAtomic ( volatile SInt32 *address );

    Parameters

    address

    The 4-byte aligned address of the value to update atomically.

    Return Value

    The value before the decrement.

    Discussion

    The OSDecrementAtomic function decrements the value at the specified address by one and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 16-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    SInt16 OSDecrementAtomic16 ( volatile SInt16 *address );

    Parameters

    address

    The 2-byte aligned address of the value to update atomically.

    Return Value

    The value before the decrement.

    Discussion

    The OSDecrementAtomic16 function decrements the value at the specified address by one and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 64-bit decrement.

    Declaration

    Objective-C

    SInt64 OSDecrementAtomic64 ( volatile SInt64 *address );

    Discussion

    See OSDecrementAtomic.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.5 and later.

  • 8-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    SInt8 OSDecrementAtomic8 ( volatile SInt8 *address );

    Parameters

    address

    The address of the value to update atomically.

    Return Value

    The value before the decrement.

    Discussion

    The OSDecrementAtomic8 function decrements the value at the specified address by one and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 32-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    SInt32 OSIncrementAtomic ( volatile SInt32 *address );

    Parameters

    address

    The 4-byte aligned address of the value to update atomically.

    Return Value

    The value before the increment.

    Discussion

    The OSIncrementAtomic function increments the value at the specified address by one and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 16-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    SInt16 OSIncrementAtomic16 ( volatile SInt16 *address );

    Parameters

    address

    The 2-byte aligned address of the value to update atomically.

    Return Value

    The value before the increment.

    Discussion

    The OSIncrementAtomic16 function increments the value at the specified address by one and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • 64-bit increment.

    Declaration

    Objective-C

    SInt64 OSIncrementAtomic64 ( volatile SInt64 *address );

    Discussion

    See OSIncrementAtomic.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.5 and later.

  • 8-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    SInt8 OSIncrementAtomic8 ( volatile SInt8 *address );

    Parameters

    address

    The address of the value to update atomically.

    Return Value

    The value before the increment.

    Discussion

    The OSIncrementAtomic8 function increments the value at the specified address by one and returns the original value.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Previous incarnations of this function incorporated a memory barrier on systems with weakly-ordered memory architectures, but current versions contain no barriers.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices.

    Declaration

    Objective-C

    void OSSynchronizeIO ( void );

    Discussion

    The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices. It executes the eieio instruction on PowerPC processors.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • Bit test and clear operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    Declaration

    Objective-C

    Boolean OSTestAndClear ( UInt32 bit, volatile UInt8 *startAddress );

    Parameters

    bit

    The bit number in the range 0 through 7.

    startAddress

    The address of the byte to update atomically.

    Return Value

    true if the bit was already clear, false otherwise.

    Discussion

    The OSTestAndClear function clears a single bit in a byte at a specified address. It returns true if the bit was already clear, false otherwise.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

  • Bit test and set operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

    This function guarantees atomicity only with main system memory. It is specifically unsuitable for use on noncacheable memory such as that in devices; this function cannot guarantee atomicity, for example, on memory mapped from a PCI device. Additionally, this function incorporates a memory barrier on systems with weakly-ordered memory architectures.

    Declaration

    Objective-C

    Boolean OSTestAndSet ( UInt32 bit, volatile UInt8 *startAddress );

    Parameters

    bit

    The bit number in the range 0 through 7.

    startAddress

    The address of the byte to update atomically.

    Return Value

    true if the bit was already set, false otherwise.

    Discussion

    The OSTestAndSet function sets a single bit in a byte at a specified address. It returns true if the bit was already set, false otherwise.

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.0 and later.

Data Types

See the Overview section above for header-level documentation.

  • Data type for a spinlock.

    Declaration

    Objective-C

    typedef SInt32 OSSpinLock;

    Discussion

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

    Import Statement

    Objective-C

    #include <OSAtomic.h>;

    Availability

    Available in OS X v10.7 and later.

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    #define OS_SPINLOCK_INIT 0

    Constants

    • OS_SPINLOCK_INIT

      OS_SPINLOCK_INIT

      The default value for an OSSpinLock.

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

      Available in OS X v10.7 and later.