semaphore.h revision 51f9db691d747d579ebd9047e86aab26105b6bc3
/** @file
* Incredibly Portable Runtime - Semaphore.
*/
/*
* Copyright (C) 2006-2007 Sun Microsystems, Inc.
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
#ifndef ___iprt_semaphore_h
#define ___iprt_semaphore_h
/** @defgroup grp_rt_sems RTSem - Semaphores
* @ingroup grp_rt
* @{
*/
/**
* Create a event semaphore.
*
* @returns iprt status code.
* @param pEventSem Where to store the event semaphore handle.
*/
/**
* Destroy an event semaphore.
*
* @returns iprt status code.
* @param EventSem Handle of the
*/
/**
* Signal an event semaphore.
*
* The event semaphore will be signaled and automatically reset
* after exactly one thread have successfully returned from
*
* @returns iprt status code.
* @param EventSem The event semaphore to signal.
*/
/**
* Wait for the event semaphore to be signaled, resume on interruption.
*
* This function will resume if the wait is interrupted by an async
* system event (like a unix signal) or similar.
*
* @returns iprt status code.
* Will not return VERR_INTERRUPTED.
* @param EventSem The event semaphore to wait on.
* @param cMillies Number of milliseconds to wait.
*/
/**
* Wait for the event semaphore to be signaled, return on interruption.
*
* This function will not resume the wait if interrupted.
*
* @returns iprt status code.
* @param EventSem The event semaphore to wait on.
* @param cMillies Number of milliseconds to wait.
*/
/**
* Create a event multi semaphore.
*
* @returns iprt status code.
* @param pEventMultiSem Where to store the event multi semaphore handle.
*/
/**
* Destroy an event multi semaphore.
*
* @returns iprt status code.
* @param EventMultiSem The event multi sempahore to destroy.
*/
/**
* Signal an event multi semaphore.
*
* @returns iprt status code.
* @param EventMultiSem The event multi semaphore to signal.
*/
/**
* Resets an event multi semaphore to non-signaled state.
*
* @returns iprt status code.
* @param EventMultiSem The event multi semaphore to reset.
*/
/**
* Wait for the event multi semaphore to be signaled, resume on interruption.
*
* This function will resume if the wait is interrupted by an async
* system event (like a unix signal) or similar.
*
* @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.
*/
/**
* Wait for the event multi semaphore to be signaled, return on interruption.
*
* This function will not resume the wait if interrupted.
*
* @returns iprt status code.
* @param EventMultiSem The event multi semaphore to wait on.
* @param cMillies Number of milliseconds to wait.
*/
/**
* Create a mutex semaphore.
*
* @returns iprt status code.
* @param pMutexSem Where to store the mutex semaphore handle.
*/
/**
* Destroy a mutex semaphore.
*
* @returns iprt status code.
* @param MutexSem The mutex semaphore to destroy.
*/
/**
* Request ownership of a mutex semaphore, resume on interruption.
*
* This function will resume if the wait is interrupted by an async
* system event (like a unix signal) or similar.
*
* The same thread may request a mutex semaphore multiple times,
* a nested counter is kept to make sure it's released on the right
* RTSemMutexRelease() call.
*
* @returns iprt status code.
* Will not return VERR_INTERRUPTED.
* @param MutexSem The mutex semaphore to request ownership over.
* @param cMillies The number of milliseconds to wait.
*/
/**
* Request ownership of a mutex semaphore, return on interruption.
*
* This function will not resume the wait if interrupted.
*
* The same thread may request a mutex semaphore multiple times,
* a nested counter is kept to make sure it's released on the right
* RTSemMutexRelease() call.
*
* @returns iprt status code.
* @param MutexSem The mutex semaphore to request ownership over.
* @param cMillies The number of milliseconds to wait.
*/
/**
* Release the ownership of a mutex semaphore.
*
* @returns iprt status code.
* @param MutexSem The mutex to release the ownership of.
* It goes without saying the the calling thread must own it.
*/
/**
* Create a fast mutex semaphore.
*
* @returns iprt status code.
* @param pMutexSem Where to store the mutex semaphore handle.
*/
/**
* Destroy a fast mutex semaphore.
*
* @returns iprt status code.
* @param MutexSem The mutex semaphore to destroy.
*/
/**
* Request ownership of a fast mutex semaphore.
*
* The same thread may request a mutex semaphore multiple times,
* a nested counter is kept to make sure it's released on the right
* RTSemMutexRelease() call.
*
* @returns iprt status code.
* @param MutexSem The mutex semaphore to request ownership over.
*/
/**
* Release the ownership of a fast mutex semaphore.
*
* @returns iprt status code.
* @param MutexSem The mutex to release the ownership of.
* It goes without saying the the calling thread must own it.
*/
/**
*
* @returns iprt status code.
* @param pRWSem Where to store the handle to the created RW semaphore.
*/
/**
*
* @returns iprt status code.
*/
/**
*
* @returns iprt status code.
* @retval VINF_SUCCESS on success.
* @retval VERR_INTERRUPT if the wait was interrupted.
* @retval VERR_INVALID_HANDLE if RWSem is invalid.
*
* @param cMillies The number of milliseconds to wait.
*/
/**
*
* @returns iprt status code.
* @retval VINF_SUCCESS on success.
* @retval VERR_INTERRUPT if the wait was interrupted.
* @retval VERR_INVALID_HANDLE if RWSem is invalid.
*
* @param cMillies The number of milliseconds to wait.
*/
/**
*
* @returns iprt status code.
* Goes without saying that caller must have read access to the sem.
*/
/**
*
* @returns iprt status code.
* @retval VINF_SUCCESS on success.
* @retval VERR_DEADLOCK if the caller owned the read lock.
* @retval VERR_INVALID_HANDLE if RWSem is invalid.
*
* @param cMillies The number of milliseconds to wait.
*/
/**
*
* @returns iprt status code.
* @retval VINF_SUCCESS on success.
* @retval VERR_INTERRUPT if the wait was interrupted.
* @retval VERR_DEADLOCK if the caller owned the read lock.
* @retval VERR_INVALID_HANDLE if RWSem is invalid.
*
* @param cMillies The number of milliseconds to wait.
*/
/**
*
* @returns iprt status code.
* Goes without saying that caller must have write access to the sem.
*/
/**
* Ping-pong speaker
*/
typedef enum RTPINGPONGSPEAKER
{
/** Not initialized. */
/** Ping is speaking, Pong is waiting. */
/** Pong is signaled, Ping is waiting. */
/** Pong is speaking, Ping is waiting. */
/** Ping is signaled, Pong is waiting. */
/** Hack to ensure that it's at least 32-bits wide. */
RTPINGPONGSPEAKER_HACK = 0x7fffffff
/**
* Ping-Pong construct.
*
* Two threads, one saying Ping and the other saying Pong. The construct
* makes sure they don't speak out of turn and that they can wait and poll
* on the conversation.
*/
typedef struct RTPINGPONG
{
/** The semaphore the Ping thread waits on. */
/** The semaphore the Pong thread waits on. */
/** The current speaker. */
volatile RTPINGPONGSPEAKER enmSpeaker;
#if HC_ARCH_BITS == 64
/** Padding the structure to become a multiple of sizeof(RTHCPTR). */
#endif
} RTPINGPONG;
/** Pointer to Ping-Pong construct. */
typedef RTPINGPONG *PRTPINGPONG;
/**
* Init a Ping-Pong construct.
*
* @returns iprt status code.
* @param pPP Pointer to the ping-pong structure which needs initialization.
*/
/**
* Destroys a Ping-Pong construct.
*
* @returns iprt status code.
* @param pPP Pointer to the ping-pong structure which is to be destroyed.
* (I.e. put into uninitialized state.)
*/
/**
* Signals the pong thread in a ping-pong construct. (I.e. sends ping.)
* This is called by the ping thread.
*
* @returns iprt status code.
* @param pPP Pointer to the ping-pong structure to ping.
*/
/**
* Signals the ping thread in a ping-pong construct. (I.e. sends pong.)
* This is called by the pong thread.
*
* @returns iprt status code.
* @param pPP Pointer to the ping-pong structure to pong.
*/
/**
* Wait function for the ping thread.
*
* @returns iprt status code.
* Will not return VERR_INTERRUPTED.
* @param pPP Pointer to the ping-pong structure to wait on.
* @param cMillies Number of milliseconds to wait.
*/
/**
* Wait function for the pong thread.
*
* @returns iprt status code.
* Will not return VERR_INTERRUPTED.
* @param pPP Pointer to the ping-pong structure to wait on.
* @param cMillies Number of milliseconds to wait.
*/
/** @} */
#endif