Changeset 21513 in vbox for trunk/include/iprt/semaphore.h

Timestamp:

Jul 12, 2009 7:17:13 PM (15 years ago)

Author:

vboxsync

Message:

iprt/semaphore.h,types.h: Defined a new semaphore type for use with the logger.

File:

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

trunk/include/iprt/semaphore.h

@@ -43 +43 @@
 
 
+/** @defgroup grp_rt_sems_event    RTSemEvent - Single Release Event Semaphores
+ * @{ */
+
 /**
  * Create a event semaphore.
@@ -95 +98 @@
 RTDECL(int)  RTSemEventWaitNoResume(RTSEMEVENT EventSem, unsigned cMillies);
 
-
+/** @} */
+
+
+/** @defgroup grp_rt_sems_event_multi   RTSemEventMulti - Multiple Release Event Semaphores
+ * @{ */
 
 /**
@@ -154 +161 @@
 RTDECL(int)  RTSemEventMultiWaitNoResume(RTSEMEVENTMULTI EventMultiSem, unsigned cMillies);
 
-
+/** @} */
+
+
+/** @defgroup grp_rt_sems_mutex     RTMutex - Mutex semaphores.
+ *
+ * @remarks These can be pretty heavy handed. Fast mutexes or critical sections
+ *          is usually what you need.
+ *
+ * @{ */
 
 /**
@@ -213 +228 @@
 RTDECL(int)  RTSemMutexRelease(RTSEMMUTEX MutexSem);
 
+/** @} */
+
+
+/** @defgroup grp_rt_sems_fast_mutex    RTSemFastMutex - Fast Mutex Semaphores
+ * @{ */
 
 /**
@@ -253 +273 @@
 RTDECL(int)  RTSemFastMutexRelease(RTSEMFASTMUTEX MutexSem);
 
+/** @} */
+
+
+/** @defgroup grp_rt_sems_spin_mutex RTSemSpinMutex - Spinning Mutex Semaphores
+ *
+ * Very adaptive kind of mutex semaphore tailored for the ring-0 logger.
+ *
+ * @{ */
+
+/**
+ * Creates a spinning mutex semaphore.
+ *
+ * @returns iprt status code.
+ * @retval  VERR_INVALID_PARAMETER on invalid flags.
+ * @retval  VERR_NO_MEMORY if out of memory for the semaphore structure and
+ *          handle.
+ *
+ * @param   phSpinMtx   Where to return the handle to the create semaphore.
+ * @param   fFlags      Flags, see RTSEMSPINMUTEX_FLAGS_XXX.
+ */
+RTDECL(int) RTSemSpinMutexCreate(PRTSEMSPINMUTEX phSpinMtx, uint32_t fFlags);
+
+/** @name RTSemSpinMutexCreate flags.
+ * @{ */
+/** Always take the semaphore in a IRQ safe way.
+ * (In plain words: always disable interrupts.) */
+#define RTSEMSPINMUTEX_FLAGS_IRQ_SAFE       RT_BIT_32(0)
+/** Mask of valid flags. */
+#define RTSEMSPINMUTEX_FLAGS_VALID_MASK     UINT32_C(0x00000001)
+/** @} */
+
+/**
+ * Destroys a spinning mutex semaphore.
+ *
+ * @returns iprt status code.
+ * @retval  VERR_INVALID_HANDLE (or crash) if the handle is invalid. (NIL will
+ *          not cause this status.)
+ *
+ * @param   hSpinMtx    The semaphore handle. NIL_RTSEMSPINMUTEX is ignored
+ *                      quietly (VINF_SUCCESS).
+ */
+RTDECL(int) RTSemSpinMutexDestroy(RTSEMSPINMUTEX hSpinMtx);
+
+/**
+ * Request the spinning mutex semaphore.
+ *
+ * This may block if the context we're called in allows this. If not it will
+ * spin. If called in an interrupt context, we will only spin if the current
+ * owner isn't interrupted. Also, on some systems it is not always possible to
+ * wake up blocking threads in all contexts, so, which will either be indicated
+ * by returning VERR_SEM_BAD_CONTEXT or by temporarily switching the semaphore
+ * into pure spinlock state.
+ *
+ * Preemption will be disabled upon return. IRQs may also be disabled.
+ *
+ * @returns iprt status code.
+ * @retval  VERR_SEM_BAD_CONTEXT if the context it's called in isn't suitable
+ *          for releasing it if someone is sleeping on it.
+ * @retval  VERR_SEM_DESTROYED if destroyed.
+ * @retval  VERR_SEM_NESTED if held by the caller. Asserted.
+ * @retval  VERR_INVALID_HANDLE if the handle is invalid. Asserted
+ *
+ * @param   hSpinMtx    The semaphore handle.
+ */
+RTDECL(int) RTSemSpinMutexRequest(RTSEMSPINMUTEX hSpinMtx);
+
+/**
+ * Like RTSemSpinMutexRequest but it won't block or spin if the semaphore is
+ * held by someone else.
+ *
+ * @returns iprt status code.
+ * @retval  VERR_SEM_BUSY if held by someone else.
+ * @retval  VERR_SEM_DESTROYED if destroyed.
+ * @retval  VERR_SEM_NESTED if held by the caller. Asserted.
+ * @retval  VERR_INVALID_HANDLE if the handle is invalid. Asserted
+ *
+ * @param   hSpinMtx    The semaphore handle.
+ */
+RTDECL(int) RTSemSpinMutexTryRequest(RTSEMSPINMUTEX hSpinMtx);
+
+/**
+ * Releases the semaphore previously acquired by RTSemSpinMutexRequest or
+ * RTSemSpinMutexTryRequest.
+ *
+ * @returns iprt status code.
+ * @retval  VERR_SEM_DESTROYED if destroyed.
+ * @retval  VERR_NOT_OWNER if not owner. Asserted.
+ * @retval  VERR_INVALID_HANDLE if the handle is invalid. Asserted.
+ *
+ * @param   hSpinMtx    The semaphore handle.
+ */
+RTDECL(int) RTSemSpinMutexRelease(RTSEMSPINMUTEX hSpinMtx);
+
+/** @} */
+
+
+/** @defgroup grp_rt_sem_rw             RTSemRW - Read / Write Semaphores
+ * @{ */
 
 /**
@@ -365 +483 @@
 RTDECL(uint32_t) RTSemRWGetWriterReadRecursion(RTSEMRW RWSem);
 
-
+/** @} */
+
+
+/** @defgroup grp_rt_sems_pingpong      RTSemPingPong - Ping-Pong Construct
+ * @{ */
 
 /**
@@ -524 +646 @@
 }
 
+/** @} */
 
 /** @} */