Changeset 25717 in vbox for trunk/include

Timestamp:

Jan 11, 2010 1:24:09 PM (15 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

56457

Message:

iprt: Added RTSemEventCreateEx and did some cleanups of the RTSemEventDestroy behavior wrt NIL handles.

File:

• trunk/include/iprt/semaphore.h (modified) (5 diffs)

trunk/include/iprt/semaphore.h

@@ -62 +62 @@
  *
  * @returns iprt status code.
- * @param   pEventSem    Where to store the event semaphore handle.
- */
-RTDECL(int)  RTSemEventCreate(PRTSEMEVENT pEventSem);
+ * @param   phEventSem          Where to store the handle to the newly created
+ *                              event semaphore.
+ */
+RTDECL(int)  RTSemEventCreate(PRTSEMEVENT phEventSem);
+
+/**
+ * Creates a read/write semaphore.
+ *
+ * @returns iprt status code.
+ * @param   phEventSem          Where to store the handle to the newly created
+ *                              event semaphore.
+ * @param   fFlags              Flags, any combination of the
+ *                              RTSEMEVENT_FLAGS_XXX \#defines.
+ * @param   hClass              The class (no reference consumed).  Since we
+ *                              don't do order checks on event semaphores, the
+ *                              use of the class is limited to controlling the
+ *                              timeout threshold for deadlock detection.
+ * @param   pszNameFmt          Name format string for the lock validator,
+ *                              optional (NULL).  Max length is 32 bytes.
+ * @param   ...                 Format string arguments.
+ */
+RTDECL(int)  RTSemEventCreateEx(PRTSEMEVENT phEventSem, uint32_t fFlags, RTLOCKVALCLASS hClass, const char *pszNameFmt, ...);
+
+/** @name RTSemMutexCreateEx flags
+ * @{ */
+/** Disables lock validation. */
+#define RTSEMEVENT_FLAGS_NO_LOCK_VAL    UINT32_C(0x00000001)
+/** @} */
+
 
 /**
@@ -70 +96 @@
  *
  * @returns iprt status code.
- * @param   EventSem    Handle of the
- */
-RTDECL(int)  RTSemEventDestroy(RTSEMEVENT EventSem);
+ * @param   hEventSem           Handle of the event sempahore.  NIL_RTSEMEVENT
+ *                              is quitely ignored (VINF_SUCCESS).
+ */
+RTDECL(int)  RTSemEventDestroy(RTSEMEVENT hEventSem);
 
 /**
@@ -82 +109 @@
  *
  * @returns iprt status code.
- * @param   EventSem    The event semaphore to signal.
- */
-RTDECL(int)  RTSemEventSignal(RTSEMEVENT EventSem);
+ * @param   hEventSem           The event semaphore to signal.
+ */
+RTDECL(int)  RTSemEventSignal(RTSEMEVENT hEventSem);
 
 /**
@@ -94 +121 @@
  * @returns iprt status code.
  *          Will not return VERR_INTERRUPTED.
- * @param   EventSem    The event semaphore to wait on.
- * @param   cMillies    Number of milliseconds to wait.
- */
-RTDECL(int)  RTSemEventWait(RTSEMEVENT EventSem, unsigned cMillies);
+ * @param   hEventSem           The event semaphore to wait on.
+ * @param   cMillies            Number of milliseconds to wait.
+ */
+RTDECL(int)  RTSemEventWait(RTSEMEVENT hEventSem, unsigned cMillies);
 
 /**
@@ -105 +132 @@
  *
  * @returns iprt status code.
- * @param   EventSem    The event semaphore to wait on.
- * @param   cMillies    Number of milliseconds to wait.
- */
-RTDECL(int)  RTSemEventWaitNoResume(RTSEMEVENT EventSem, unsigned cMillies);
+ * @param   hEventSem           The event semaphore to wait on.
+ * @param   cMillies            Number of milliseconds to wait.
+ */
+RTDECL(int)  RTSemEventWaitNoResume(RTSEMEVENT hEventSem, unsigned cMillies);
 
 /**