Update the SupportDefs documentation for several changes and document the atomic_* functions.
git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@35148 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
parent
27bb89cae1
commit
ae15171716
@ -5,7 +5,7 @@
|
||||
* Documentation by:
|
||||
* Niels Sascha Reedijk <niels.reedijk@gmail.com>
|
||||
* Corresponds to:
|
||||
* /trunk/headers/os/support/SupportDefs.h rev 19972
|
||||
* /trunk/headers/os/support/SupportDefs.h rev 35018
|
||||
*/
|
||||
|
||||
/*!
|
||||
@ -15,140 +15,127 @@
|
||||
*/
|
||||
|
||||
/*!
|
||||
\name Short byte long Type Formats
|
||||
\name Fixed-Size Integer Types
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\typedef typedef signed char int8
|
||||
\typedef typedef __haiku_int8 int8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef unsigned char uint8
|
||||
\typedef typedef __haiku_uint8 uint8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile signed char vint8
|
||||
\typedef typedef __haiku_int16 int16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned char vuint8
|
||||
\typedef typedef __haiku_uint16 uint16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef __haiku_int32 int32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef __haiku_uint32 uint32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef __haiku_int64 int64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef __haiku_uint64 uint64
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Short 2-byte long Type Formats
|
||||
\name Fixed-size Volatile Types
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile int8 vint8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile uint8 vuint8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile int16 vint16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile uint16 vuint16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile int32 vint32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile uint32 vuint32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile int64 vint64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile uint64 vuint64
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Short-hand Volatile Type Names
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\typedef typedef short int16
|
||||
\typedef typedef volatile long vlong
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef unsigned short uint16
|
||||
\typedef typedef volatile int vint
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile short vint16
|
||||
\typedef typedef volatile short vshort
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned short vuint16
|
||||
\typedef typedef volatile char vchar
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned long vulong
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned int vuint
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned short vushort
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned char vuchar
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Short 4-byte long Type Formats
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\typedef typedef long int32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef unsigned long uint32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile long vint32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned long vuint32
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Short 8-byte long Type Formats
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\typedef typedef long long int64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef unsigned long long uint64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile long long vint64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned long long vuint64
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Short volatile Type Formats
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile long vlong
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile int vint
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile short vshort
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile char vchar
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned long vulong
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned int vuint
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned short vushort
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef volatile unsigned char vuchar
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Character Type Formats
|
||||
@ -182,6 +169,11 @@
|
||||
\brief Represents time. The unit depends on the context of the function.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef int64 nanotime_t
|
||||
\brief Represents time in nanoseconds.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef uint32 type_code
|
||||
\brief Represents a certain type of data. See TypeConstants.h for possible
|
||||
@ -195,7 +187,291 @@
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
|
||||
/*!
|
||||
\name Format strings for printf()/scanf()
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\def B_PRId8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIi8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRId16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIi16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRId32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIi32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRId64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIi64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIu8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIo8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIx8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIX8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIu16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIo16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIx16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIX16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIu32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIo32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIx32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIX32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIu64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIo64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIx64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIX64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNd8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNi8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNd16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNi16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNd32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNi32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNd64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNi64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNu8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNo8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNx8
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNu16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNo16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNx16
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNu32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNo32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNx32
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNu64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNo64
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_SCNx64
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Format strings for several standard types
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\def B_PRIuSIZE
|
||||
\brief size_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIoSIZE
|
||||
\brief size_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIxSIZE
|
||||
\brief size_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIXSIZE
|
||||
\brief size_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIdSSIZE
|
||||
\brief ssize_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIiSSIZE
|
||||
\brief ssize_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIuADDR
|
||||
\brief addr_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIoADDR
|
||||
\brief addr_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIxADDR
|
||||
\brief addr_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIXADDR
|
||||
\brief addr_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIdOFF
|
||||
\brief off_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIiOFF
|
||||
\brief off_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIdDEV
|
||||
\brief dev_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIiDEV
|
||||
\brief dev_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIdINO
|
||||
\brief ino_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIiINO
|
||||
\brief ino_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIdTIME
|
||||
\brief time_t
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def B_PRIiTIME
|
||||
\brief time_t
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
//////////////// Odds and ends
|
||||
|
||||
/*!
|
||||
@ -232,15 +508,31 @@
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_set(vint32 *value, int32 newValue)
|
||||
\brief Undocumented.
|
||||
\sa atomic_set64() for a version that works on \c long \c long
|
||||
\brief Atomically set the variable \a value to \a newvalue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c = \c newValue
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
|
||||
\sa atomic_set64() for a version that works on \c long \c long
|
||||
\sa atomic_test_and_set(), atomic_add(), atomic_and(),
|
||||
atomic_or(), atomic_get()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_test_and_set(vint32 *value, int32 newValue, int32 testAgainst)
|
||||
\brief Undocumented.
|
||||
\brief Atomically set the variable \a value to \a newValue if the current
|
||||
value is \a testAgainst.
|
||||
|
||||
This is a thread-safe way of conditionally performing the \c *value \c +=
|
||||
\c newValue operation. You should use these function when two or more threads
|
||||
might access the variable simultaneously. You don't have to use a semaphore
|
||||
or a mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_test_and_set64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_add(), atomic_and(),
|
||||
atomic_or(), atomic_get()
|
||||
@ -248,7 +540,14 @@
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_add(vint32 *value, int32 addValue)
|
||||
\brief Undocumented.
|
||||
\brief Atomically add the value of \a addValue to \a value.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c += \c addValue
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_add64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_and(),
|
||||
atomic_or(), atomic_get()
|
||||
@ -256,7 +555,15 @@
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_and(vint32 *value, int32 andValue)
|
||||
\brief Undocumented.
|
||||
\brief Atomically perform a bitwise AND operation of \a andValue to the
|
||||
variable \a andValue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c &= \c andValue
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_and64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_add(),
|
||||
atomic_or(), atomic_get()
|
||||
@ -265,7 +572,15 @@
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_or(vint32 *value, int32 orValue)
|
||||
\brief Undocumented.
|
||||
\brief Atomically perform a bitwise OR operation of \a orValue to the
|
||||
variable \a andValue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c |= \c orValue
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_or64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
|
||||
atomic_get()
|
||||
@ -273,7 +588,14 @@
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_get(vint32 *value)
|
||||
\brief Undocumented.
|
||||
\brief Atomically return the value of \c value.
|
||||
|
||||
This is a thread-safe way of reading the contents of the \c value
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_get64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
|
||||
atomic_or()
|
||||
@ -281,7 +603,15 @@
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_set64(vint64 *value, int64 newValue)
|
||||
\brief Undocumented.
|
||||
\brief Atomically set the variable \a value to \a newvalue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c = \c newValue
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
|
||||
\sa atomic_set() for a version that works on an \c int32
|
||||
\sa atomic_test_and_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
@ -289,7 +619,15 @@
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_test_and_set64(vint64 *value, int64 newValue, int64 testAgainst)
|
||||
\brief Undocumented.
|
||||
\brief Atomically set the variable \a value to \a newValue if the current
|
||||
value is \a testAgainst.
|
||||
|
||||
This is a thread-safe way of conditionally performing the \c *value \c +=
|
||||
\c newValue operation. You should use these function when two or more threads
|
||||
might access the variable simultaneously. You don't have to use a semaphore
|
||||
or a mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_test_and_set() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
@ -297,7 +635,14 @@
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_add64(vint64 *value, int64 addValue)
|
||||
\brief Undocumented.
|
||||
\brief Atomically add the value of \a addValue to \a value.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c += \c addValue
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_add() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_and64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
@ -305,7 +650,15 @@
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_and64(vint64 *value, int64 andValue)
|
||||
\brief Undocumented.
|
||||
\brief Atomically perform a bitwise AND operation of \a andValue to the
|
||||
variable \a andValue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c &= \c andValue
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_and() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
@ -313,7 +666,15 @@
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_or64(vint64 *value, int64 orValue)
|
||||
\brief Undocumented.
|
||||
\brief Atomically perform a bitwise OR operation of \a orValue to the
|
||||
variable \a andValue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c |= \c orValue
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_or() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_get64()
|
||||
@ -321,7 +682,14 @@
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_get64(vint64 *value)
|
||||
\brief Undocumented.
|
||||
\brief Atomically return the value of \c value.
|
||||
|
||||
This is a thread-safe way of reading the contents of the \c value
|
||||
operation. You should use these function when two or more threads might
|
||||
access the variable simultaneously. You don't have to use a semaphore or a
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_get() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_or64()
|
||||
@ -331,10 +699,14 @@
|
||||
|
||||
/*!
|
||||
\fn void* get_stack_frame(void)
|
||||
\brief This is internal, I guess. Else this needs to be documented.
|
||||
\brief Internal function.
|
||||
\internal
|
||||
*/
|
||||
|
||||
/*!
|
||||
\name Deprecated defines
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
|
||||
Loading…
Reference in New Issue
Block a user