a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * IPRT - Condition Variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Copyright (C) 2006-2010 Oracle Corporation
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * available from http://www.virtualbox.org. This file is free software;
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * you can redistribute it and/or modify it under the terms of the GNU
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * General Public License (GPL) as published by the Free Software
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * The contents of this file may alternatively be used under the terms
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * of the Common Development and Distribution License Version 1.0
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * VirtualBox OSE distribution, in which case the provisions of the
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * CDDL are applicable instead of those of the GPL.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * You may elect to license modified versions of this file under the
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * terms and conditions of either the GPL or the CDDL or both.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync#if defined(RT_LOCK_STRICT_ORDER) && defined(IN_RING3)
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync/** @defgroup grp_rt_condvar RTCondVar - Condition Variable
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Condition variables combines mutex semaphore or critical sections with event
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * semaphores. See @ref grp_rt_sems_mutex, @ref grp_rt_critsect,
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @ref grp_rt_sems_event and @ref grp_rt_sems_event_multi.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @ingroup grp_rt
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Create a condition variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param phCondVar Where to store the handle to the newly created
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * condition variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Create a condition variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param phCondVar Where to store the handle to the newly created
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * condition variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param fFlags Flags, any combination of the
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * RTCONDVAR_FLAGS_XXX \#defines.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hClass The class (no reference consumed). Since we
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * don't do order checks on condition variables,
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * the use of the class is limited to controlling
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * the timeout threshold for deadlock detection.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param pszNameFmt Name format string for the lock validator,
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * optional (NULL). Max length is 32 bytes.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param ... Format string arguments.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(int) RTConvVarCreateEx(PRTCONDVAR phCondVar, uint32_t fFlags, RTLOCKVALCLASS hClass, const char *pszNameFmt, ...);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync/** @name RTConvVarCreateEx flags
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync/** Disables lock validation. */
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync#define RTCONDVAR_FLAGS_NO_LOCK_VAL UINT32_C(0x00000001)
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Destroy a condition variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hCondVar Handle of the condition variable. NIL_RTCONDVAR
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * is quietly ignored (VINF_SUCCESS).
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Signal the condition variable, waking up exactly one thread.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * It is recommended that the caller holds the associated lock, but this is not
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * strictly speaking necessary.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * If no threads are waiting on the condition variable, the call will have no
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * effect on the variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to signal.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Signal the condition variable, waking up all blocked threads.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * It is recommended that the caller holds the associated lock, but this is not
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * strictly speaking necessary.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * If no threads are waiting on the condition variable, the call will have no
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * effect on the variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to broadcast.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Wait for the condition variable to be signaled, resume on interruption.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This function will resume if the wait is interrupted by an async system event
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * (like a unix signal) or similar.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Will not return VERR_INTERRUPTED.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to wait on.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hMtx The mutex to leave during the wait and which
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * will be re-enter before returning.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param cMillies Number of milliseconds to wait. Use
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * RT_INDEFINITE_WAIT to wait forever.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(int) RTConvVarMutexWait(RTCONDVAR hCondVar, RTSEMMUTEX hMtx, RTMSINTERVAL cMillies);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Wait for the condition variable to be signaled, return on interruption.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This function will not resume the wait if interrupted.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to wait on.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hMtx The mutex to leave during the wait and which
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * will be re-enter before returning.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param cMillies Number of milliseconds to wait. Use
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * RT_INDEFINITE_WAIT to wait forever.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(int) RTConvVarMutexWaitNoResume(RTCONDVAR hCondVar, RTSEMMUTEX hMtx, RTMSINTERVAL cMillies);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Wait for the condition variable to be signaled, resume on interruption.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This function will resume if the wait is interrupted by an async system event
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * (like a unix signal) or similar.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Will not return VERR_INTERRUPTED.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to wait on.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hRWSem The read/write semaphore to write-leave during
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * the wait and which will be re-enter in write
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * mode before returning.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param cMillies Number of milliseconds to wait. Use
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * RT_INDEFINITE_WAIT to wait forever.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(int) RTConvVarRWWriteWait(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Wait for the condition variable to be signaled, return on interruption.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This function will not resume the wait if interrupted.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to wait on.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hRWSem The read/write semaphore to write-leave during
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * the wait and which will be re-enter in write
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * mode before returning.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param cMillies Number of milliseconds to wait. Use
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * RT_INDEFINITE_WAIT to wait forever.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(int) RTConvVarRWWriteWaitNoResume(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Wait for the condition variable to be signaled, resume on interruption.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This function will resume if the wait is interrupted by an async system event
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * (like a unix signal) or similar.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Will not return VERR_INTERRUPTED.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to wait on.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hRWSem The read/write semaphore to read-leave during
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * the wait and which will be re-enter in read mode
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * before returning.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param cMillies Number of milliseconds to wait. Use
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * RT_INDEFINITE_WAIT to wait forever.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(int) RTConvVarRWReadWait(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Wait for the condition variable to be signaled, return on interruption.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This function will not resume the wait if interrupted.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to wait on.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hRWSem The read/write semaphore to read-leave during
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * the wait and which will be re-enter in read mode
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * before returning.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param cMillies Number of milliseconds to wait. Use
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * RT_INDEFINITE_WAIT to wait forever.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(int) RTConvVarRWReadWaitNoResume(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Wait for the condition variable to be signaled, resume on interruption.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This function will resume if the wait is interrupted by an async system event
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * (like a unix signal) or similar.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Will not return VERR_INTERRUPTED.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to wait on.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param pCritSect The critical section to leave during the wait
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * and which will be re-enter before returning.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param cMillies Number of milliseconds to wait. Use
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * RT_INDEFINITE_WAIT to wait forever.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(int) RTConvVarCritSectWait(RTCONDVAR hCondVar, PRTCRITSECT pCritSect, RTMSINTERVAL cMillies);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Wait for the condition variable to be signaled, return on interruption.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This function will not resume the wait if interrupted.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @returns iprt status code.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable to wait on.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param pCritSect The critical section to leave during the wait
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * and which will be re-enter before returning.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param cMillies Number of milliseconds to wait. Use
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * RT_INDEFINITE_WAIT to wait forever.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(int) RTConvVarCritSectWaitNoResume(RTCONDVAR hCondVar, PRTCRITSECT pCritSect, RTMSINTERVAL cMillies);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Sets the signaller thread to one specific thread.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * This is only used for validating usage and deadlock detection. When used
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * after calls to RTConvVarAddSignaller, the specified thread will be the only
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * signalling thread.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hThread The thread that will signal it. Pass
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * NIL_RTTHREAD to indicate that there is no
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * special signalling thread.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(void) RTConvVarSetSignaller(RTCONDVAR hCondVar, RTTHREAD hThread);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * To add more signalling threads.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * First call RTCondVarSetSignaller then add further threads with this.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hThread The thread that will signal it. NIL_RTTHREAD is
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * not accepted.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsyncRTDECL(void) RTConvVarAddSignaller(RTCONDVAR hCondVar, RTTHREAD hThread);
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * To remove a signalling thread.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * Reverts work done by RTCondVarAddSignaller and RTCondVarSetSignaller.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hConvVar The condition variable.
a7169ca7cf17625398ff21548eedc3851a742ec0vboxsync * @param hThread A previously added thread.