OSAtomic.h Reference

Declared in
OSAtomic.h

Overview

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

Included Headers

  • <libkern/OSBase.h>

Functions

See the Overview section above for header-level documentation.

OSAddAtomic

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSAddAtomic16

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSAddAtomic64

64-bit atomic add operation.

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

See OSAddAtomic.

Availability
  • Available in OS X v10.5 and later.
Declared In
OSAtomic.h

OSAddAtomic8

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSBitAndAtomic

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

extern 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..

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSBitAndAtomic16

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSBitAndAtomic8

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSBitOrAtomic

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSBitOrAtomic16

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSBitOrAtomic8

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.

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSBitXorAtomic

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.

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSBitXorAtomic16

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSBitXorAtomic8

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.

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSCompareAndSwap

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSCompareAndSwap64

64-bit compare and swap operation.

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

See OSCompareAndSwap.

Availability
  • Available in OS X v10.5 and later.
Declared In
OSAtomic.h

OSCompareAndSwapPtr

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

extern 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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSAtomic.h

OSDecrementAtomic

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSDecrementAtomic16

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSDecrementAtomic64

64-bit decrement.

inline static SInt64 OSDecrementAtomic64(
   volatile SInt64 *address)
Discussion

See OSDecrementAtomic.

Availability
  • Available in OS X v10.5 and later.
Declared In
OSAtomic.h

OSDecrementAtomic8

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSIncrementAtomic

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSIncrementAtomic16

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSIncrementAtomic64

64-bit increment.

inline static SInt64 OSIncrementAtomic64(
   volatile SInt64 *address)
Discussion

See OSIncrementAtomic.

Availability
  • Available in OS X v10.5 and later.
Declared In
OSAtomic.h

OSIncrementAtomic8

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSSynchronizeIO

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

static __inline__ 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSTestAndClear

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

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

OSTestAndSet

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.

extern 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSAtomic.h

Data Types

See the Overview section above for header-level documentation.

OSSpinLock

Data type for a spinlock.

typedef SInt32 OSSpinLock;
Discussion

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

Availability
  • Available in OS X v10.7 and later.
Declared In
OSAtomic.h

Constants

See the Overview section above for header-level documentation.

Miscellaneous Defines

   
#define OS_SPINLOCK_INIT 0
Constants
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.

Declared in OSAtomic.h.