Changeset 25720 in vbox for trunk/include

Timestamp:

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

Author:

vboxsync

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

56460

Message:

iprt: Added RTSemEventMultiCreateEx and did some cleanups of the RTSemEventMultiDestroy behavior wrt NIL handles.

File:

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

trunk/include/iprt/semaphore.h

@@ -59 +59 @@
 
 /**
- * Create a event semaphore.
+ * Create an event semaphore.
  *
  * @returns iprt status code.
@@ -68 +68 @@
 
 /**
- * Creates a read/write semaphore.
+ * Create an event semaphore.
  *
  * @returns iprt status code.
@@ -91 +91 @@
 /** @} */
 
-
 /**
  * Destroy an event semaphore.
@@ -183 +182 @@
 
 /**
- * Create a event multi semaphore.
- *
- * @returns iprt status code.
- * @param   pEventMultiSem  Where to store the event multi semaphore handle.
- */
-RTDECL(int)  RTSemEventMultiCreate(PRTSEMEVENTMULTI pEventMultiSem);
+ * Creates a multiple release event semaphore.
+ *
+ * @returns iprt status code.
+ * @param   phEventMultiSem     Where to store the handle to the newly created
+ *                              multiple release event semaphore.
+ */
+RTDECL(int)  RTSemEventMultiCreate(PRTSEMEVENTMULTI phEventMultiSem);
+
+/**
+ * Creates a multiple release event semaphore.
+ *
+ * @returns iprt status code.
+ * @param   phEventMultiSem     Where to store the handle to the newly created
+ *                              multiple release event semaphore.
+ * @param   fFlags              Flags, any combination of the
+ *                              RTSEMEVENTMULTI_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)  RTSemEventMultiCreateEx(PRTSEMEVENTMULTI phEventMultiSem, uint32_t fFlags, RTLOCKVALCLASS hClass,
+                                     const char *pszNameFmt, ...);
+
+/** @name RTSemMutexCreateEx flags
+ * @{ */
+/** Disables lock validation. */
+#define RTSEMEVENTMULTI_FLAGS_NO_LOCK_VAL   UINT32_C(0x00000001)
+/** @} */
 
 /**
@@ -194 +219 @@
  *
  * @returns iprt status code.
- * @param   EventMultiSem   The event multi sempahore to destroy.
- */
-RTDECL(int)  RTSemEventMultiDestroy(RTSEMEVENTMULTI EventMultiSem);
+ * @param   hEventMultiSem      The multiple release event sempahore.  NIL is
+ *                              quietly ignored (VINF_SUCCESS).
+ */
+RTDECL(int)  RTSemEventMultiDestroy(RTSEMEVENTMULTI hEventMultiSem);
 
 /**
@@ -202 +228 @@
  *
  * @returns iprt status code.
- * @param   EventMultiSem   The event multi semaphore to signal.
- */
-RTDECL(int)  RTSemEventMultiSignal(RTSEMEVENTMULTI EventMultiSem);
+ * @param   hEventMultiSem      The multiple release event sempahore.
+ */
+RTDECL(int)  RTSemEventMultiSignal(RTSEMEVENTMULTI hEventMultiSem);
 
 /**
@@ -210 +236 @@
  *
  * @returns iprt status code.
- * @param   EventMultiSem   The event multi semaphore to reset.
- */
-RTDECL(int)  RTSemEventMultiReset(RTSEMEVENTMULTI EventMultiSem);
+ * @param   hEventMultiSem      The multiple release event sempahore.
+ */
+RTDECL(int)  RTSemEventMultiReset(RTSEMEVENTMULTI hEventMultiSem);
 
 /**
@@ -222 +248 @@
  * @returns iprt status code.
  *          Will not return VERR_INTERRUPTED.
- * @param   EventMultiSem   The event multi semaphore to wait on.
- * @param   cMillies        Number of milliseconds to wait.
- */
-RTDECL(int)  RTSemEventMultiWait(RTSEMEVENTMULTI EventMultiSem, unsigned cMillies);
+ * @param   hEventMultiSem      The multiple release event sempahore.
+ * @param   cMillies            Number of milliseconds to wait.
+ */
+RTDECL(int)  RTSemEventMultiWait(RTSEMEVENTMULTI hEventMultiSem, unsigned cMillies);
 
 
@@ -234 +260 @@
  *
  * @returns iprt status code.
- * @param   EventMultiSem   The event multi semaphore to wait on.
- * @param   cMillies        Number of milliseconds to wait.
- */
-RTDECL(int)  RTSemEventMultiWaitNoResume(RTSEMEVENTMULTI EventMultiSem, unsigned cMillies);
+ * @param   hEventMultiSem      The multiple release event sempahore.
+ * @param   cMillies            Number of milliseconds to wait.
+ */
+RTDECL(int)  RTSemEventMultiWaitNoResume(RTSEMEVENTMULTI hEventMultiSem, unsigned cMillies);
 
 /**