[haiku-commits] r35148 - haiku/trunk/docs/user/support
- From: niels.reedijk@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Tue, 19 Jan 2010 00:14:46 +0100 (CET)
Author: nielx
Date: 2010-01-19 00:14:46 +0100 (Tue, 19 Jan 2010)
New Revision: 35148
Changeset: http://dev.haiku-os.org/changeset/35148/haiku
Modified:
haiku/trunk/docs/user/support/SupportDefs.dox
Log:
Update the SupportDefs documentation for several changes and document the
atomic_* functions.
Modified: haiku/trunk/docs/user/support/SupportDefs.dox
===================================================================
--- haiku/trunk/docs/user/support/SupportDefs.dox 2010-01-18 22:49:33 UTC
(rev 35147)
+++ haiku/trunk/docs/user/support/SupportDefs.dox 2010-01-18 23:14:46 UTC
(rev 35148)
@@ -5,7 +5,7 @@
* Documentation by:
* Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
* Corresponds to:
- * /trunk/headers/os/support/SupportDefs.h rev 19972
+ * /trunk/headers/os/support/SupportDefs.h rev 35018
*/
/*!
@@ -15,141 +15,128 @@
*/
/*!
- \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
*/
-//! @}
-
/*!
- \name Short 2-byte long Type Formats
+ \typedef typedef __haiku_int32 int32
*/
-//! @{
-
/*!
- \typedef typedef short int16
+ \typedef typedef __haiku_uint32 uint32
*/
/*!
- \typedef typedef unsigned short uint16
+ \typedef typedef __haiku_int64 int64
*/
/*!
- \typedef typedef volatile short vint16
+ \typedef typedef __haiku_uint64 uint64
*/
-/*!
- \typedef typedef volatile unsigned short vuint16
-*/
-
//! @}
+
/*!
- \name Short 4-byte long Type Formats
+ \name Fixed-size Volatile Types
*/
//! @{
-
+
/*!
- \typedef typedef long int32
+ \typedef typedef volatile int8 vint8
*/
/*!
- \typedef typedef unsigned long uint32
+ \typedef typedef volatile uint8 vuint8
*/
/*!
- \typedef typedef volatile long vint32
+ \typedef typedef volatile int16 vint16
*/
/*!
- \typedef typedef volatile unsigned long vuint32
+ \typedef typedef volatile uint16 vuint16
*/
-//! @}
-
/*!
- \name Short 8-byte long Type Formats
+ \typedef typedef volatile int32 vint32
*/
-//! @{
-
/*!
- \typedef typedef long long int64
+ \typedef typedef volatile uint32 vuint32
*/
/*!
- \typedef typedef unsigned long long uint64
+ \typedef typedef volatile int64 vint64
*/
/*!
- \typedef typedef volatile long long vint64
+ \typedef typedef volatile uint64 vuint64
*/
-/*!
- \typedef typedef volatile unsigned long long vuint64
-*/
-
//! @}
+
/*!
- \name Short volatile Type Formats
+ \name Short-hand Volatile Type Names
*/
//! @{
/*!
- \typedef typedef volatile long vlong
+ \typedef typedef volatile long vlong
*/
/*!
- \typedef typedef volatile int vint
+ \typedef typedef volatile int vint
*/
/*!
- \typedef typedef volatile short vshort
+ \typedef typedef volatile short vshort
*/
/*!
- \typedef typedef volatile char vchar
+ \typedef typedef volatile char vchar
*/
/*!
- \typedef typedef volatile unsigned long vulong
+ \typedef typedef volatile unsigned long vulong
*/
/*!
- \typedef typedef volatile unsigned int vuint
+ \typedef typedef volatile unsigned int vuint
*/
/*!
- \typedef typedef volatile unsigned short vushort
+ \typedef typedef volatile unsigned short vushort
*/
/*!
- \typedef typedef volatile unsigned char vuchar
+ \typedef typedef volatile unsigned char vuchar
*/
//! @}
+
/*!
\name Character Type Formats
*/
@@ -183,6 +170,11 @@
*/
/*!
+ \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
values.
@@ -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
+*/
+
//! @{
/*!
Other related posts:
- » [haiku-commits] r35148 - haiku/trunk/docs/user/support - niels . reedijk
