/* ********************************************************** * Copyright 2004 - 2009 VMware, Inc. All rights reserved. * **********************************************************/ /* * @VMKAPIMOD_LICENSE@ */ /* *********************************************************************** * Semaphores */ /** * \addtogroup Core * @{ * \defgroup Semaphores Semaphores * @{ *********************************************************************** */ #ifndef _VMKAPI_SEM_H_ #define _VMKAPI_SEM_H_ /** \cond never */ #ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H #error This vmkapi file should never be included directly but only via vmkapi.h #endif /** \endcond never */ /** * \brief Opaque handle for semaphores */ typedef struct vmk_SemaphoreInt *vmk_Semaphore; /** * \brief Opaque handle for readers-writers semaphores */ typedef struct vmk_SemaphoreRWInt *vmk_SemaphoreRW; /* *********************************************************************** * vmk_SemaCreate -- */ /** * * \brief Allocate and initialize a counting semaphore * * \note This function will not block. * * \note Requires that the module heap be initialized. * * \param[out] sema New counting semaphore. * \param[in] moduleID Module on whose behalf the semaphore * is created. * \param[in] name Human-readable name of the semaphore. * \param[in] value Initial count. * * \retval VMK_OK The semaphore was successfully created * \retval VMK_NO_MEMORY The semaphore could not be allocated * \retval VMK_NO_MODULE_HEAP The module has no heap to allocate from * *********************************************************************** */ VMK_ReturnStatus vmk_SemaCreate( vmk_Semaphore *sema, vmk_ModuleID moduleID, const char *name, vmk_int32 value); /* *********************************************************************** * vmk_BinarySemaCreate -- */ /** * * \brief Allocate and initialize a binary semaphore * * \note This function will not block. * * \note Requires that the module heap be initialized. * * \param[out] sema New counting semaphore. * \param[in] moduleID Module on whose behalf the semaphore * is created. * \param[in] name Human-readable name of the semaphore. * * \retval VMK_OK The semaphore was successfully created * \retval VMK_NO_MEMORY The semaphore could not be allocated * \retval VMK_NO_MODULE_HEAP The module has no heap to allocate from * *********************************************************************** */ VMK_ReturnStatus vmk_BinarySemaCreate( vmk_Semaphore *sema, vmk_ModuleID moduleID, const char *name); /* *********************************************************************** * vmk_SemaAssertHasState -- * * This is used by vmk_SemaAssertLocked() and vmk_SemaAssertUnlocked(). * VMKAPI clients should not call this function directly. * * \note This function will not block. * *********************************************************************** */ /** \cond nodoc */ void vmk_SemaAssertHasState( vmk_Semaphore *sema, vmk_Bool locked); /** \endcond */ /* *********************************************************************** * vmk_SemaAssertIsLocked -- */ /** * * \brief Assert that a semaphore is currently locked. * * \note This function will not block. * \note This call only performs the check on a debug build. * * \param[in] sema Semaphore to check. * *********************************************************************** */ static VMK_ALWAYS_INLINE void vmk_SemaAssertIsLocked( vmk_Semaphore *sema) { #ifdef VMX86_DEBUG vmk_SemaAssertHasState(sema, VMK_TRUE); #endif } /* *********************************************************************** * vmk_SemaAssertIsUnlocked -- */ /** * * \brief Assert that a semaphore is currently unlocked. * * \note This function will not block. * \note This call only performs the check on a debug build. * * \param[in] sema Semaphore to check. * *********************************************************************** */ static VMK_ALWAYS_INLINE void vmk_SemaAssertIsUnlocked( vmk_Semaphore *sema) { #ifdef VMX86_DEBUG vmk_SemaAssertHasState(sema, VMK_FALSE); #endif } /* *********************************************************************** * vmk_SemaLock -- */ /** * * \brief Acquire a semaphore * * \note This function may block. * * \pre Shall be called from a blockable context. * \pre The caller shall not already hold a semaphore of lower or equal * rank if the semaphore is a binary semaphore. * * \param[in] sema The semaphore to acquire. * *********************************************************************** */ void vmk_SemaLock( vmk_Semaphore *sema); /* *********************************************************************** * vmk_SemaTryLock -- */ /** * * \brief Try to acquire a semaphore. * * \note This function will not block. * * This tries to acquire the given semaphore once. * If the semaphore is already locked, it returns immediately. * * \pre Shall be called from a blockable context. * * \param[in] sema Semaphore to attempt to acquire. * * \retval VMK_OK The semaphore was successfully acquired. * \retval VMK_BUSY The semaphore is currently locked. * *********************************************************************** */ VMK_ReturnStatus vmk_SemaTryLock( vmk_Semaphore *sema); /* *********************************************************************** * vmk_SemaUnlock -- */ /** * * \brief Release a semaphore * * \note This function will not block. * * \param[in] sema Semaphore to unlock. * *********************************************************************** */ void vmk_SemaUnlock( vmk_Semaphore *sema); /* *********************************************************************** * vmk_SemaDestroy -- */ /** * * \brief Destroy a semaphore * * \note This function will not block. * * Revert all side effects of vmk_SemaCreate or * vmk_BinarySemaCreate. * * \param[in] sema Semaphore to destroy. * *********************************************************************** */ void vmk_SemaDestroy(vmk_Semaphore *sema); /* *********************************************************************** * vmk_RWSemaCreate -- */ /** * * \brief Allocate and initialize a readers-writers semaphore * * \note This function will not block. * * \param[out] sema New readers-writers semaphore. * \param[in] moduleID Module on whose behalf the semaphore * is created. * \param[in] name Human-readable name of the semaphore. * *********************************************************************** */ VMK_ReturnStatus vmk_RWSemaCreate( vmk_SemaphoreRW *sema, vmk_ModuleID moduleID, const char *name); /* *********************************************************************** * vmk_RWSemaDestroy -- */ /** * * \brief Destroy a readers-writers semaphore * * \note This function will not block. * * Revert all side effects of vmk_RWSemaCreate. * * \param[in] sema Readers-writers semaphore to destroy. * *********************************************************************** */ void vmk_RWSemaDestroy(vmk_SemaphoreRW *sema); /* *********************************************************************** * vmk_RWSemaReadLock -- */ /** * * \brief Acquire a readers-writers semaphore for shared read access. * * \note This function may block. * * \pre Shall be called from a blockable context. * * \param[in] sema Readers-writers semaphore to acquire. * *********************************************************************** */ void vmk_RWSemaReadLock(vmk_SemaphoreRW *sema); /* *********************************************************************** * vmk_RWSemaTryReadLock -- */ /** * * \brief Attempt to acquire a rw semaphore for shared read access. * * \note This function will not block. * * \param[in] sema Readers-writers semaphore to acquire. * * \retval VMK_OK The semaphore was acquired. * \retval VMK_WOULD_BLOCK The semaphore does not allow immediate reader * access. * *********************************************************************** */ VMK_ReturnStatus vmk_RWSemaTryReadLock(vmk_SemaphoreRW *sema); /* *********************************************************************** * vmk_RWSemaWriteLock -- */ /** * * \brief Acquire a readers-writers semaphore for exclusive write * access. * * \note This function may block. * * \pre Shall be called from a blockable context. * * \param[in] sema Readers-writers semaphore to acquire. * *********************************************************************** */ void vmk_RWSemaWriteLock(vmk_SemaphoreRW *sema); /* *********************************************************************** * vmk_RWSemaReadUnlock -- */ /** * * \brief Release a readers-writers semaphore from shared read access. * * \note This function will not block. * * \param[in] sema Readers-writers semaphore to release. * *********************************************************************** */ void vmk_RWSemaReadUnlock(vmk_SemaphoreRW *sema); /* *********************************************************************** * vmk_RWSemaWriteUnlock -- */ /** * * \brief Release a readers-writers semaphore from exclusive write * access. * * \note This function will not block. * * \param[in] sema Readers-writers semaphore to release. * *********************************************************************** */ void vmk_RWSemaWriteUnlock(vmk_SemaphoreRW *sema); /* *********************************************************************** * vmk_RWSemaUpgradeFromRead -- */ /** * * \brief Upgrade a readers-writers semaphore to exclusive write access. * * This requests an upgrade to exclusive writers access for the * readers-writers semaphore while already holding shared reader access. * If the upgrade is not immediately available, only the first caller * can block waiting for the upgrade. Others fail, but they retain * shared reader access. * * \note This function may block. * * \pre Shall already have read access to the semaphore. * * \param[in] sema Readers-writers semaphore to upgrade. * * \retval VMK_OK The semaphore was upgraded. * \retval VMK_BUSY The semaphore could not be upgraded. * *********************************************************************** */ VMK_ReturnStatus vmk_RWSemaUpgradeFromRead(vmk_SemaphoreRW *sema); /* *********************************************************************** * vmk_RWSemaTryUpgradeFromRead -- */ /** * * \brief Attempt to upgrade a readers-writers semaphore to * exclusive write access. * * \note This function will not block. * * This attempts to obtain exclusive writers access to the * readers-writers semaphore while already holding shared reader access. * If the upgrade is not immediately available, shared reader access * is retained. * * \pre Shall already have read access to the semaphore. * * \param[in] sema Readers-writers semaphore to upgrade. * * \retval VMK_OK The semaphore was upgraded. * \retval VMK_BUSY The semaphore could not be upgraded. * *********************************************************************** */ VMK_ReturnStatus vmk_RWSemaTryUpgradeFromRead(vmk_SemaphoreRW *sema); /* *********************************************************************** * vmk_RWSemaDowngradeToRead -- */ /** * * \brief Downgrade a readers-writers semaphore from exclusive * write access to shared read access. * * \note This function will not block. * * \pre Shall already have write access to the semaphore. * * \param[in] sema Readers-writers semaphore to downgrade. * *********************************************************************** */ void vmk_RWSemaDowngradeToRead(vmk_SemaphoreRW *sema); /* *********************************************************************** * vmk_RWSemaAssertHasReadersInt -- * * This is used internally by vmk_RWSemaAssertHasReaders. VMKAPI * clients should not call this function directly. * * \note This function will not block. * *********************************************************************** */ /** \cond nodoc */ void vmk_RWSemaAssertHasReadersInt(vmk_SemaphoreRW *sema); /** \endcond */ /* *********************************************************************** * vmk_RWSemaAssertHasReaders -- */ /** * * \brief Assert that a readers-writers semaphore has at least one * shared reader. The check is only performed in debug builds. * * \note This function will not block. * * \param[in] sema Semaphore to check. * *********************************************************************** */ static VMK_ALWAYS_INLINE void vmk_RWSemaAssertHasReaders(vmk_SemaphoreRW *sema) { #ifdef VMX86_DEBUG vmk_RWSemaAssertHasReadersInt(sema); #endif } /* *********************************************************************** * vmk_SemaAssertHasWriterInt -- * * This is used internally by vmk_RWSemaAssertHasWriter. VMKAPI * clients should not call this function directly. * * \note This function will not block. * *********************************************************************** */ /** \cond nodoc */ void vmk_RWSemaAssertHasWriterInt(vmk_SemaphoreRW *sema); /** \endcond */ /* *********************************************************************** * vmk_RWSemaAssertHasWriter -- */ /** * * \brief Assert that a readers-writers semaphore has a writer. * The check is only performed in debug builds. * * \note This call will not block. * * \param[in] sema Semaphore to check. * *********************************************************************** */ static VMK_ALWAYS_INLINE void vmk_RWSemaAssertHasWriter(vmk_SemaphoreRW *sema) { #ifdef VMX86_DEBUG vmk_RWSemaAssertHasWriterInt(sema); #endif } /* *********************************************************************** * vmk_SemaAssertHasReadersWriterInt -- * * This is used internally by vmk_RWSemaAssertHasReadersWriter. * VMKAPI clients should not call this function directly. * * \note This function will not block. * *********************************************************************** */ /** \cond nodoc */ void vmk_RWSemaAssertHasReadersWriterInt(vmk_SemaphoreRW *sema); /** \endcond */ /* *********************************************************************** * vmk_RWSemaAssertHasReadersWriter -- */ /** * * \brief Assert that a readers-writers semaphore has either readers * or a writer. The check is only performed on debug builds. * * \note This call will not block. * * \param[in] sema Semaphore to check. * *********************************************************************** */ static VMK_ALWAYS_INLINE void vmk_RWSemaAssertHasReadersWriter(vmk_SemaphoreRW *sema) { #ifdef VMX86_DEBUG vmk_RWSemaAssertHasReadersWriterInt(sema); #endif } #endif /* _VMKAPI_SEM_H_ */ /** @} */ /** @} */