Changeset 24468 in vbox

Timestamp:

Nov 6, 2009 5:03:44 PM (15 years ago)

Author:

vboxsync

Message:

iprt/req.h: Document RTReqCall* caveats better.

Location:

trunk

Files:

• include/iprt/req.h (modified) (4 diffs)
• src/VBox/Runtime/common/misc/req.cpp (modified) (4 diffs)

trunk/include/iprt/req.h

@@ -209 +209 @@
  * @param   pfnFunction     Pointer to the function to call.
  * @param   cArgs           Number of arguments following in the ellipsis.
- *                          The arguments must be of integer or pointer type and
- *                          not bigger in size than uintptr_t. Do not try pass
- *                          64-bit integers directly in portable code.
  * @param   ...             Function arguments.
+ *
+ * @remarks See remarks on RTReqCallV.
  */
 RTDECL(int) RTReqCall(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
@@ -237 +236 @@
  * @param   pfnFunction     Pointer to the function to call.
  * @param   cArgs           Number of arguments following in the ellipsis.
- *                          The arguments must be of integer or pointer type and
- *                          not bigger in size than uintptr_t. Do not try pass
- *                          64-bit integers directly in portable code.
  * @param   ...             Function arguments.
+ *
+ * @remarks See remarks on RTReqCallV.
  */
 RTDECL(int) RTReqCallVoid(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
@@ -267 +265 @@
  * @param   pfnFunction     Pointer to the function to call.
  * @param   cArgs           Number of arguments following in the ellipsis.
- *                          The arguments must be of integer or pointer type and
- *                          not bigger in size than uintptr_t. Do not try pass
- *                          64-bit integers directly in portable code.
  * @param   ...             Function arguments.
+ *
+ * @remarks See remarks on RTReqCallV.
  */
 RTDECL(int) RTReqCallEx(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
@@ -297 +294 @@
  * @param   pfnFunction     Pointer to the function to call.
  * @param   cArgs           Number of arguments following in the ellipsis.
- *                          The arguments must be of integer or pointer type and
- *                          not bigger in size than uintptr_t. Do not try pass
- *                          64-bit integers directly in portable code.
  * @param   Args            Variable argument vector.
+ *
+ * @remarks Caveats:
+ *              - Do not pass anything which is larger than an uintptr_t.
+ *              - 64-bit integers are larger than uintptr_t on 32-bit hosts.
+ *                Pass integers > 32-bit by reference (pointers).
+ *              - Don't use NULL since it should be the integer 0 in C++ and may
+ *                therefore end up with garbage in the bits 63:32 on 64-bit
+ *                hosts because 'int' is 32-bit.
+ *                Use (void *)NULL or (uintptr_t)0 instead of NULL.
  */
 RTDECL(int) RTReqCallV(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);

trunk/src/VBox/Runtime/common/misc/req.cpp

@@ -207 +207 @@
  * @param   pfnFunction     Pointer to the function to call.
  * @param   cArgs           Number of arguments following in the ellipsis.
- *                          Not possible to pass 64-bit arguments!
  * @param   ...             Function arguments.
+ *
+ * @remarks See remarks on RTReqCallV.
  */
 RTDECL(int) RTReqCall(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...)
@@ -241 +242 @@
  * @param   pfnFunction     Pointer to the function to call.
  * @param   cArgs           Number of arguments following in the ellipsis.
- *                          Not possible to pass 64-bit arguments!
  * @param   ...             Function arguments.
+ *
+ * @remarks See remarks on RTReqCallV.
  */
 RTDECL(int) RTReqCallVoid(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...)
@@ -277 +279 @@
  * @param   pfnFunction     Pointer to the function to call.
  * @param   cArgs           Number of arguments following in the ellipsis.
- *                          Not possible to pass 64-bit arguments!
  * @param   ...             Function arguments.
+ *
+ * @remarks See remarks on RTReqCallV.
  */
 RTDECL(int) RTReqCallEx(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...)
@@ -313 +316 @@
  * @param   pfnFunction     Pointer to the function to call.
  * @param   cArgs           Number of arguments following in the ellipsis.
- *                          Not possible to pass 64-bit arguments!
  * @param   Args            Variable argument vector.
+ *
+ * @remarks Caveats:
+ *              - Do not pass anything which is larger than an uintptr_t.
+ *              - 64-bit integers are larger than uintptr_t on 32-bit hosts.
+ *                Pass integers > 32-bit by reference (pointers).
+ *              - Don't use NULL since it should be the integer 0 in C++ and may
+ *                therefore end up with garbage in the bits 63:32 on 64-bit
+ *                hosts because 'int' is 32-bit.
+ *                Use (void *)NULL or (uintptr_t)0 instead of NULL.
  */
 RTDECL(int) RTReqCallV(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args)