semaphore.h revision b011d23442f2b9e7208db889ff4b5ffe2c8effc8
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * IPRT - Semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
c97989161fbe75bc14cea477a5443bbf474dd3advboxsync * available from http://www.virtualbox.org. This file is free software;
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * you can redistribute it and/or modify it under the terms of the GNU
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * General Public License (GPL) as published by the Free Software
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * The contents of this file may alternatively be used under the terms
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * of the Common Development and Distribution License Version 1.0
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * VirtualBox OSE distribution, in which case the provisions of the
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * CDDL are applicable instead of those of the GPL.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * You may elect to license modified versions of this file under the
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * terms and conditions of either the GPL or the CDDL or both.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * additional information or have any questions.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync/** @defgroup grp_rt_sems RTSem - Semaphores
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * This module implements all kinds of event and mutex semaphores; in addition
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * to these, IPRT implements "critical sections", which are fast recursive
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * mutexes (see @ref grp_rt_critsect ). C++ users may find @ref grp_rt_lock
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * interesting.
200b30e29b4e37472d84580f1b69b842cafb4f5evboxsync * @ingroup grp_rt
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync/** @defgroup grp_rt_sems_event RTSemEvent - Single Release Event Semaphores
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Event semaphores can be used for inter-thread communication when one thread
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * wants to notify another thread that something happened. A thread can block
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * ("wait") on an event semaphore until it is signalled by another thread; see
d3b1e232c566c55799a7bfc83f66b045c4d82657vboxsync * RTSemEventCreate, RTSemEventSignal and RTSemEventWait.
d645696bf70e804f18f661a9b1b8b79c32a1b331vboxsync * Create a event semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param pEventSem Where to store the event semaphore handle.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(int) RTSemEventCreate(PRTSEMEVENT pEventSem);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Destroy an event semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param EventSem Handle of the
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Signal an event semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * The event semaphore will be signaled and automatically reset after exactly
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * one thread have successfully returned from RTSemEventWait() after
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * waiting/polling on that semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param EventSem The event semaphore to signal.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Wait for the event semaphore to be signaled, resume on interruption.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * This function will resume if the wait is interrupted by an async system event
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * (like a unix signal) or similar.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Will not return VERR_INTERRUPTED.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param EventSem The event semaphore to wait on.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param cMillies Number of milliseconds to wait.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(int) RTSemEventWait(RTSEMEVENT EventSem, unsigned cMillies);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Wait for the event semaphore to be signaled, return on interruption.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * This function will not resume the wait if interrupted.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param EventSem The event semaphore to wait on.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param cMillies Number of milliseconds to wait.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(int) RTSemEventWaitNoResume(RTSEMEVENT EventSem, unsigned cMillies);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Sets the signaller thread to one specific thread.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * This is only used for validating usage and deadlock detection. When used
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * after calls to RTSemEventAddSignaller, the specified thread will be the only
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * signalling thread.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hEventSem The event semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hThread The thread that will signal it. Pass
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * NIL_RTTHREAD to indicate that there is no
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * special signalling thread.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(void) RTSemEventSetSignaller(RTSEMEVENT hEventSem, RTTHREAD hThread);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * To add more signalling threads.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * First call RTSemEventSetSignaller then add further threads with this.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hEventSem The event semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hThread The thread that will signal it. NIL_RTTHREAD is
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * not accepted.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(void) RTSemEventAddSignaller(RTSEMEVENT hEventSem, RTTHREAD hThread);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * To remove a signalling thread.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Reverts work done by RTSemEventAddSignaller and RTSemEventSetSignaller.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hEventSem The event semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hThread A previously added thread.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(void) RTSemEventRemoveSignaller(RTSEMEVENT hEventSem, RTTHREAD hThread);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync/** @defgroup grp_rt_sems_event_multi RTSemEventMulti - Multiple Release Event Semaphores
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * A variant of @ref grp_rt_sems_event where all threads will be unblocked when
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * signalling the semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Create a event multi semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param pEventMultiSem Where to store the event multi semaphore handle.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(int) RTSemEventMultiCreate(PRTSEMEVENTMULTI pEventMultiSem);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Destroy an event multi semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param EventMultiSem The event multi sempahore to destroy.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(int) RTSemEventMultiDestroy(RTSEMEVENTMULTI EventMultiSem);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Signal an event multi semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param EventMultiSem The event multi semaphore to signal.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(int) RTSemEventMultiSignal(RTSEMEVENTMULTI EventMultiSem);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Resets an event multi semaphore to non-signaled state.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param EventMultiSem The event multi semaphore to reset.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(int) RTSemEventMultiReset(RTSEMEVENTMULTI EventMultiSem);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Wait for the event multi semaphore to be signaled, resume on interruption.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * This function will resume if the wait is interrupted by an async
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * system event (like a unix signal) or similar.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Will not return VERR_INTERRUPTED.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param EventMultiSem The event multi semaphore to wait on.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param cMillies Number of milliseconds to wait.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(int) RTSemEventMultiWait(RTSEMEVENTMULTI EventMultiSem, unsigned cMillies);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Wait for the event multi semaphore to be signaled, return on interruption.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * This function will not resume the wait if interrupted.
fb7ddc547f7396b0016729175bee920396b5cd3fvboxsync * @returns iprt status code.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param EventMultiSem The event multi semaphore to wait on.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param cMillies Number of milliseconds to wait.
fb7ddc547f7396b0016729175bee920396b5cd3fvboxsyncRTDECL(int) RTSemEventMultiWaitNoResume(RTSEMEVENTMULTI EventMultiSem, unsigned cMillies);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Sets the signaller thread to one specific thread.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * This is only used for validating usage and deadlock detection. When used
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * after calls to RTSemEventAddSignaller, the specified thread will be the only
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * signalling thread.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hEventMultiSem The multiple release event semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hThread The thread that will signal it. Pass
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * NIL_RTTHREAD to indicate that there is no
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * special signalling thread.
dfff275f489de72e78be4fb4fbc3a2780f0ee2aavboxsyncRTDECL(void) RTSemEventMultiSetSignaller(RTSEMEVENTMULTI hEventMultiSem, RTTHREAD hThread);
dfff275f489de72e78be4fb4fbc3a2780f0ee2aavboxsync * To add more signalling threads.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * First call RTSemEventSetSignaller then add further threads with this.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hEventMultiSem The multiple release event semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hThread The thread that will signal it. NIL_RTTHREAD is
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * not accepted.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(void) RTSemEventMultiAddSignaller(RTSEMEVENTMULTI hEventMultiSem, RTTHREAD hThread);
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * To remove a signalling thread.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * Reverts work done by RTSemEventAddSignaller and RTSemEventSetSignaller.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hEventMultiSem The multiple release event semaphore.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsync * @param hThread A previously added thread.
9f4747a43944848d911353b1bcc99f41aaa5bf81vboxsyncRTDECL(void) RTSemEventMultiRemoveSignaller(RTSEMEVENTMULTI hEventMultiSem, RTTHREAD hThread);
RTDECL(int) RTSemMutexRequestDebug(RTSEMMUTEX MutexSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
RTDECL(int) RTSemMutexRequestNoResumeDebug(RTSEMMUTEX MutexSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
#ifdef RT_STRICT
# ifdef ___iprt_asm_h
# define RTSemMutexRequest(pCritSect, cMillies) RTSemMutexRequestDebug((pCritSect), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
# define RTSemMutexRequestNoResume(pCritSect, cMillies) RTSemMutexRequestNoResumeDebug((pCritSect), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
# define RTSemMutexRequest(pCritSect, cMillies) RTSemMutexRequestDebug((pCritSect), (cMillies), 0, RT_SRC_POS)
# define RTSemMutexRequestNoResume(pCritSect, cMillies) RTSemMutexRequestNoResumeDebug((pCritSect), (cMillies), 0, RT_SRC_POS)
RTDECL(int) RTSemRWRequestReadDebug(RTSEMRW RWSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
RTDECL(int) RTSemRWRequestReadNoResumeDebug(RTSEMRW RWSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
RTDECL(int) RTSemRWRequestWriteDebug(RTSEMRW RWSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
RTDECL(int) RTSemRWRequestWriteNoResumeDebug(RTSEMRW RWSem, unsigned cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
#ifdef RT_STRICT
# ifdef ___iprt_asm_h
# define RTSemRWRequestRead(pCritSect, cMillies) RTSemRWRequestReadDebug((pCritSect), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
# define RTSemRWRequestReadNoResume(pCritSect, cMillies) RTSemRWRequestReadNoResumeDebug((pCritSect), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
# define RTSemRWRequestWrite(pCritSect, cMillies) RTSemRWRequestWriteDebug((pCritSect), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
# define RTSemRWRequestWriteNoResume(pCritSect, cMillies) RTSemRWRequestWriteNoResumeDebug((pCritSect), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
# define RTSemRWRequestRead(pCritSect, cMillies) RTSemRWRequestReadDebug((pCritSect), (cMillies), 0, RT_SRC_POS)
# define RTSemRWRequestReadNoResume(pCritSect, cMillies) RTSemRWRequestReadNoResumeDebug((pCritSect), (cMillies), 0, RT_SRC_POS)
# define RTSemRWRequestWrite(pCritSect, cMillies) RTSemRWRequestWriteDebug((pCritSect), (cMillies), 0, RT_SRC_POS)
# define RTSemRWRequestWriteNoResume(pCritSect, cMillies) RTSemRWRequestWriteNoResumeDebug((pCritSect), (cMillies), 0, RT_SRC_POS)
typedef enum RTPINGPONGSPEAKER
typedef struct RTPINGPONG
} RTPINGPONG;