+
+/*! @group Arithmetic functions
+ All functions in this group return the new value.
+ */
+
+/*! @abstract Atomically adds two 32-bit values.
+ @discussion
+ This function adds the value given by <code>__theAmount</code> to the
+ value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+ @result Returns the new value.
+ */
+int32_t OSAtomicAdd32( int32_t __theAmount, volatile int32_t *__theValue );
+
+
+/*! @abstract Atomically adds two 32-bit values.
+ @discussion
+ This function adds the value given by <code>__theAmount</code> to the
+ value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicAdd32}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+int32_t OSAtomicAdd32Barrier( int32_t __theAmount, volatile int32_t *__theValue );
+
+
+/*! @abstract Atomically increments a 32-bit value.
+ */
+__inline static
+int32_t OSAtomicIncrement32( volatile int32_t *__theValue )
+ { return OSAtomicAdd32( 1, __theValue); }
+
+
+/*! @abstract Atomically increments a 32-bit value with a barrier.
+ @discussion
+ This function is equivalent to {@link OSAtomicIncrement32}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+__inline static
+int32_t OSAtomicIncrement32Barrier( volatile int32_t *__theValue )
+ { return OSAtomicAdd32Barrier( 1, __theValue); }
+
+/*! @abstract Atomically decrements a 32-bit value. */
+__inline static
+int32_t OSAtomicDecrement32( volatile int32_t *__theValue )
+ { return OSAtomicAdd32( -1, __theValue); }
+
+/*! @abstract Atomically increments a 32-bit value with a barrier.
+ @discussion
+ This function is equivalent to {@link OSAtomicDecrement32}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+__inline static
+int32_t OSAtomicDecrement32Barrier( volatile int32_t *__theValue )
+ { return OSAtomicAdd32Barrier( -1, __theValue); }
+
+
+/*! @abstract Atomically adds two 64-bit values.
+ @discussion
+ This function adds the value given by <code>__theAmount</code> to the
+ value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+ */
+int64_t OSAtomicAdd64( int64_t __theAmount, volatile int64_t *__theValue );
+
+
+/*! @abstract Atomically adds two 64-bit values with a barrier.
+ @discussion
+ This function adds the value given by <code>__theAmount</code> to the
+ value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicAdd64}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+int64_t OSAtomicAdd64Barrier( int64_t __theAmount, volatile int64_t *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_3_2);
+
+
+/*! @abstract Atomically increments a 64-bit value. */
+__inline static
+int64_t OSAtomicIncrement64( volatile int64_t *__theValue )
+ { return OSAtomicAdd64( 1, __theValue); }
+
+/*! @abstract Atomically increments a 64-bit value with a barrier.
+ @discussion
+ This function is equivalent to {@link OSAtomicIncrement64}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+__inline static
+int64_t OSAtomicIncrement64Barrier( volatile int64_t *__theValue )
+ { return OSAtomicAdd64Barrier( 1, __theValue); }
+
+
+/*! @abstract Atomically decrements a 64-bit value.
+ @discussion
+ This function is equivalent to {@link OSAtomicIncrement64}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+__inline static
+int64_t OSAtomicDecrement64( volatile int64_t *__theValue )
+ { return OSAtomicAdd64( -1, __theValue); }
+
+
+/*! @abstract Atomically decrements a 64-bit value with a barrier.
+ @discussion
+ This function is equivalent to {@link OSAtomicDecrement64}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+__inline static
+int64_t OSAtomicDecrement64Barrier( volatile int64_t *__theValue )
+ { return OSAtomicAdd64Barrier( -1, __theValue); }
+
+
+/*! @group Boolean functions (AND, OR, XOR)
+ *
+ * @discussion Functions in this group come in four variants for each operation:
+ * with and without barriers, and functions that return the original value or
+ * the result value of the operation.
+ *
+ * The "Orig" versions return the original value, (before the operation); the non-Orig
+ * versions return the value after the operation. All are layered on top of
+ * {@link OSAtomicCompareAndSwap32} and similar.
+ */
+
+/*! @abstract Atomic bitwise OR of two 32-bit values.
+ @discussion
+ This function performs the bitwise OR of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+ @result Returns the new value.
+ */
+int32_t OSAtomicOr32( uint32_t __theMask, volatile uint32_t *__theValue );
+
+
+/*! @abstract Atomic bitwise OR of two 32-bit values with barrier.
+ @discussion
+ This function performs the bitwise OR of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicOr32}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+int32_t OSAtomicOr32Barrier( uint32_t __theMask, volatile uint32_t *__theValue );
+
+
+/*! @abstract Atomic bitwise OR of two 32-bit values returning original.
+ @discussion
+ This function performs the bitwise OR of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+ @result Returns the original value referenced by <code>__theValue</code>.
+ */
+int32_t OSAtomicOr32Orig( uint32_t __theMask, volatile uint32_t *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_3_2);
+
+
+/*! @abstract Atomic bitwise OR of two 32-bit values returning original with barrier.
+ @discussion
+ This function performs the bitwise OR of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicOr32Orig}
+ except that it also introduces a barrier.
+ @result Returns the original value referenced by <code>__theValue</code>.
+ */
+int32_t OSAtomicOr32OrigBarrier( uint32_t __theMask, volatile uint32_t *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_3_2);
+
+
+
+
+/*! @abstract Atomic bitwise AND of two 32-bit values.
+ @discussion
+ This function performs the bitwise AND of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+ @result Returns the new value.
+ */
+int32_t OSAtomicAnd32( uint32_t __theMask, volatile uint32_t *__theValue );
+
+
+/*! @abstract Atomic bitwise AND of two 32-bit values with barrier.
+ @discussion
+ This function performs the bitwise AND of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicAnd32}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+int32_t OSAtomicAnd32Barrier( uint32_t __theMask, volatile uint32_t *__theValue );
+
+
+/*! @abstract Atomic bitwise AND of two 32-bit values returning original.
+ @discussion
+ This function performs the bitwise AND of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+ @result Returns the original value referenced by <code>__theValue</code>.
+ */
+int32_t OSAtomicAnd32Orig( uint32_t __theMask, volatile uint32_t *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_3_2);
+
+
+/*! @abstract Atomic bitwise AND of two 32-bit values returning original with barrier.
+ @discussion
+ This function performs the bitwise AND of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicAnd32Orig}
+ except that it also introduces a barrier.
+ @result Returns the original value referenced by <code>__theValue</code>.
+ */
+int32_t OSAtomicAnd32OrigBarrier( uint32_t __theMask, volatile uint32_t *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_3_2);
+
+
+
+
+/*! @abstract Atomic bitwise XOR of two 32-bit values.
+ @discussion
+ This function performs the bitwise XOR of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+ @result Returns the new value.
+ */
+int32_t OSAtomicXor32( uint32_t __theMask, volatile uint32_t *__theValue );
+
+
+/*! @abstract Atomic bitwise XOR of two 32-bit values with barrier.
+ @discussion
+ This function performs the bitwise XOR of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicXor32}
+ except that it also introduces a barrier.
+ @result Returns the new value.
+ */
+int32_t OSAtomicXor32Barrier( uint32_t __theMask, volatile uint32_t *__theValue );
+
+
+/*! @abstract Atomic bitwise XOR of two 32-bit values returning original.
+ @discussion
+ This function performs the bitwise XOR of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+ @result Returns the original value referenced by <code>__theValue</code>.
+ */
+int32_t OSAtomicXor32Orig( uint32_t __theMask, volatile uint32_t *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_3_2);
+
+
+/*! @abstract Atomic bitwise XOR of two 32-bit values returning original with barrier.
+ @discussion
+ This function performs the bitwise XOR of the value given by <code>__theMask</code>
+ with the value in the memory location referenced by <code>__theValue</code>,
+ storing the result back to that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicXor32Orig}
+ except that it also introduces a barrier.
+ @result Returns the original value referenced by <code>__theValue</code>.
+ */
+int32_t OSAtomicXor32OrigBarrier( uint32_t __theMask, volatile uint32_t *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_3_2);
+
+
+/*! @group Compare and swap
+ * Functions in this group return true if the swap occured. There are several versions,
+ * depending on data type and on whether or not a barrier is used.
+ */
+
+
+/*! @abstract Compare and swap for 32-bit values.
+ @discussion
+ This function compares the value in <code>__oldValue</code> to the value
+ in the memory location referenced by <code>__theValue</code>. If the values
+ match, this function stores the value from <code>__newValue</code> into
+ that memory location atomically.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwap32( int32_t __oldValue, int32_t __newValue, volatile int32_t *__theValue );
+
+
+/*! @abstract Compare and swap for 32-bit values with barrier.
+ @discussion
+ This function compares the value in <code>__oldValue</code> to the value
+ in the memory location referenced by <code>__theValue</code>. If the values
+ match, this function stores the value from <code>__newValue</code> into
+ that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicCompareAndSwap32}
+ except that it also introduces a barrier.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwap32Barrier( int32_t __oldValue, int32_t __newValue, volatile int32_t *__theValue );
+
+
+/*! @abstract Compare and swap pointers.
+ @discussion
+ This function compares the pointer stored in <code>__oldValue</code> to the pointer
+ in the memory location referenced by <code>__theValue</code>. If the pointers
+ match, this function stores the pointer from <code>__newValue</code> into
+ that memory location atomically.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwapPtr( void *__oldValue, void *__newValue, void * volatile *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
+
+
+/*! @abstract Compare and swap pointers with barrier.
+ @discussion
+ This function compares the pointer stored in <code>__oldValue</code> to the pointer
+ in the memory location referenced by <code>__theValue</code>. If the pointers
+ match, this function stores the pointer from <code>__newValue</code> into
+ that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicCompareAndSwapPtr}
+ except that it also introduces a barrier.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwapPtrBarrier( void *__oldValue, void *__newValue, void * volatile *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
+
+
+/*! @abstract Compare and swap for <code>int</code> values.
+ @discussion
+ This function compares the value in <code>__oldValue</code> to the value
+ in the memory location referenced by <code>__theValue</code>. If the values
+ match, this function stores the value from <code>__newValue</code> into
+ that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicCompareAndSwap32}.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwapInt( int __oldValue, int __newValue, volatile int *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
+
+
+/*! @abstract Compare and swap for <code>int</code> values.
+ @discussion
+ This function compares the value in <code>__oldValue</code> to the value
+ in the memory location referenced by <code>__theValue</code>. If the values
+ match, this function stores the value from <code>__newValue</code> into
+ that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicCompareAndSwapInt}
+ except that it also introduces a barrier.
+
+ This function is equivalent to {@link OSAtomicCompareAndSwap32Barrier}.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwapIntBarrier( int __oldValue, int __newValue, volatile int *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
+
+
+/*! @abstract Compare and swap for <code>long</code> values.
+ @discussion
+ This function compares the value in <code>__oldValue</code> to the value
+ in the memory location referenced by <code>__theValue</code>. If the values
+ match, this function stores the value from <code>__newValue</code> into
+ that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicCompareAndSwap32} on 32-bit architectures,
+ or {@link OSAtomicCompareAndSwap64} on 64-bit architectures.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwapLong( long __oldValue, long __newValue, volatile long *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
+
+
+/*! @abstract Compare and swap for <code>long</code> values.
+ @discussion
+ This function compares the value in <code>__oldValue</code> to the value
+ in the memory location referenced by <code>__theValue</code>. If the values
+ match, this function stores the value from <code>__newValue</code> into
+ that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicCompareAndSwapLong}
+ except that it also introduces a barrier.
+
+ This function is equivalent to {@link OSAtomicCompareAndSwap32} on 32-bit architectures,
+ or {@link OSAtomicCompareAndSwap64} on 64-bit architectures.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwapLongBarrier( long __oldValue, long __newValue, volatile long *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
+
+
+/*! @abstract Compare and swap for <code>uint64_t</code> values.
+ @discussion
+ This function compares the value in <code>__oldValue</code> to the value
+ in the memory location referenced by <code>__theValue</code>. If the values
+ match, this function stores the value from <code>__newValue</code> into
+ that memory location atomically.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwap64( int64_t __oldValue, int64_t __newValue, volatile int64_t *__theValue );
+
+
+/*! @abstract Compare and swap for <code>uint64_t</code> values.
+ @discussion
+ This function compares the value in <code>__oldValue</code> to the value
+ in the memory location referenced by <code>__theValue</code>. If the values
+ match, this function stores the value from <code>__newValue</code> into
+ that memory location atomically.
+
+ This function is equivalent to {@link OSAtomicCompareAndSwap64}
+ except that it also introduces a barrier.
+ @result Returns TRUE on a match, FALSE otherwise.
+ */
+bool OSAtomicCompareAndSwap64Barrier( int64_t __oldValue, int64_t __newValue, volatile int64_t *__theValue ) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_3_2);
+
+
+/* Test and set. They return the original value of the bit, and operate on bit (0x80>>(n&7))
+ * in byte ((char*)theAddress + (n>>3)).
+ */
+/*! @abstract Atomic test and set
+ @discussion
+ This function tests a bit in the value referenced by <code>__theAddress</code>
+ and if it is not set, sets it. The bit is chosen by the value of <code>__n</code>.
+ The bits are numbered in order beginning with bit 1 as the lowest order bit.
+
+ For example, if <code>__theAddress</code> points to a 64-bit value,
+ to compare the value of the highest bit, you would specify <code>64</code> for
+ <code>__n</code>.
+ @result
+ Returns the original value of the bit being tested.
+ */
+bool OSAtomicTestAndSet( uint32_t __n, volatile void *__theAddress );
+
+
+/*! @abstract Atomic test and set with barrier
+ @discussion
+ This function tests a bit in the value referenced by <code>__theAddress</code>
+ and if it is not set, sets it. The bit is chosen by the value of <code>__n</code>.
+ The bits are numbered in order beginning with bit 1 as the lowest order bit.
+
+ For example, if <code>__theAddress</code> points to a 64-bit value,
+ to compare the value of the highest bit, you would specify <code>64</code> for
+ <code>__n</code>.
+
+ This function is equivalent to {@link OSAtomicTestAndSet}
+ except that it also introduces a barrier.
+ @result
+ Returns the original value of the bit being tested.
+ */
+
+bool OSAtomicTestAndSetBarrier( uint32_t __n, volatile void *__theAddress );
+
+
+
+/*! @abstract Atomic test and clear
+ @discussion
+ This function tests a bit in the value referenced by <code>__theAddress</code>
+ and if it is not cleared, clears it. The bit is chosen by the value of <code>__n</code>.
+ The bits are numbered in order beginning with bit 1 as the lowest order bit.
+
+ For example, if <code>__theAddress</code> points to a 64-bit value,
+ to compare the value of the highest bit, you would specify <code>64</code> for
+ <code>__n</code>.
+ @result
+ Returns the original value of the bit being tested.
+ */
+bool OSAtomicTestAndClear( uint32_t __n, volatile void *__theAddress );
+
+
+/*! @abstract Atomic test and clear
+ @discussion
+ This function tests a bit in the value referenced by <code>__theAddress</code>
+ and if it is not cleared, clears it. The bit is chosen by the value of <code>__n</code>.
+ The bits are numbered in order beginning with bit 1 as the lowest order bit.
+
+ For example, if <code>__theAddress</code> points to a 64-bit value,
+ to compare the value of the highest bit, you would specify <code>64</code> for
+ <code>__n</code>.
+
+ This function is equivalent to {@link OSAtomicTestAndSet}
+ except that it also introduces a barrier.
+ @result
+ Returns the original value of the bit being tested.
+ */
+bool OSAtomicTestAndClearBarrier( uint32_t __n, volatile void *__theAddress );
+
+
+/*! @group Spinlocks
+ * These spinlocks use memory barriers as required to synchronize access to shared
+ * memory protected by the lock.
+ */
+
+/*! @abstract The default value for an <code>OSSpinLock</code>.
+ @discussion
+ The convention is that unlocked is zero, locked is nonzero.
projects / apple / libc.git / blobdiff