Changeset 25295 in vbox for trunk/include/iprt

Timestamp:

Dec 10, 2009 1:12:41 PM (15 years ago)

Author:

vboxsync

Message:

iprt/thread.h: more docs.

File:

• trunk/include/iprt/thread.h (modified) (4 diffs)

trunk/include/iprt/thread.h

@@ -666 +666 @@
 
 /**
- * Allocates a TLS entry (index). Before using an item of TLS, this must be called
- * once for the process; the RTTLS value returned is then typically stored in a global
- * or static variable. See RTTlsGet() for example code.
+ * Allocates a TLS entry (index).
+ *
+ * Example code:
+ * @code
+    RTTLS g_iTls = NIL_RTTLS;
+
+    ...
+
+    // once for the process, allocate the TLS index
+    if (g_iTls == NIL_RTTLS)
+         g_iTls = RTTlsAlloc();
+
+    // set the thread-local value.
+    RTTlsSet(g_iTls, pMyData);
+
+    ...
+
+    // get the thread-local value
+    PMYDATA pMyData = (PMYDATA)RTTlsGet(g_iTls);
+
+   @endcode
  *
  * @returns the index of the allocated TLS entry.
@@ -676 +694 @@
 
 /**
- * Allocates a TLS entry (index, with status code).
+ * Variant of RTTlsAlloc that returns a status code.
  *
  * @returns IPRT status code.
@@ -700 +718 @@
 /**
  * Get the (thread-local) value stored in a TLS entry.
- * If RTTlsSet() has not yet been called, returns NULL.
- *
- * Example code:
- * <code>
- * RTTLS g_globalTLSIndex = NIL_RTTLS;
- *
- * ...
- *
- * // once for the process, allocate the TLS index
- * if (g_globalTLSIndex == NIL_RTTLS)
- *      g_globalTLSIndex = RTTlsAlloc();
- *
- * // get the thread-local value
- * void* pv = RTTlsGet(g_globalTLSIndex);
- *
- * </code>
  *
  * @returns value in given TLS entry.
- * @returns NULL on failure.
+ * @retval  NULL if RTTlsSet() has not yet been called on this thread, or if the
+ *          TLS index is invalid.
+ *
  * @param   iTls        The index of the TLS entry.
  */
@@ -728 +732 @@
  * @returns IPRT status code.
  * @param   iTls        The index of the TLS entry.
- * @param   ppvValue    Where to store the value.
+ * @param   ppvValue    Where to store the value.  The value will be NULL if
+ *                      RTTlsSet has not yet been called on this thread.
  */
 RTR3DECL(int) RTTlsGetEx(RTTLS iTls, void **ppvValue);