VirtualBox

source: vbox/trunk/include/iprt/condvar.h@ 95897

Last change on this file since 95897 was 93115, checked in by vboxsync, 3 years ago

scm --update-copyright-year
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.0 KB
Line 
1/** @file
2 * IPRT - Condition Variable.
3 */
4
5/*
6 * Copyright (C) 2006-2022 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef IPRT_INCLUDED_condvar_h
27#define IPRT_INCLUDED_condvar_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/cdefs.h>
33#include <iprt/types.h>
34#if defined(RT_LOCK_STRICT_ORDER) && defined(IN_RING3)
35# include <iprt/lockvalidator.h>
36#endif
37
38
39RT_C_DECLS_BEGIN
40
41/** @defgroup grp_rt_condvar RTCondVar - Condition Variable
42 *
43 * Condition variables combines mutex semaphore or critical sections with event
44 * semaphores. See @ref grp_rt_sems_mutex, @ref grp_rt_critsect,
45 * @ref grp_rt_sems_event and @ref grp_rt_sems_event_multi.
46 *
47 * @ingroup grp_rt
48 * @{
49 */
50
51
52/**
53 * Create a condition variable.
54 *
55 * @returns iprt status code.
56 * @param phCondVar Where to store the handle to the newly created
57 * condition variable.
58 */
59RTDECL(int) RTCondVarCreate(PRTCONDVAR phCondVar);
60
61/**
62 * Create a condition variable.
63 *
64 * @returns iprt status code.
65 * @param phCondVar Where to store the handle to the newly created
66 * condition variable.
67 * @param fFlags Flags, any combination of the
68 * RTCONDVAR_FLAGS_XXX \#defines.
69 * @param hClass The class (no reference consumed). Since we
70 * don't do order checks on condition variables,
71 * the use of the class is limited to controlling
72 * the timeout threshold for deadlock detection.
73 * @param pszNameFmt Name format string for the lock validator,
74 * optional (NULL). Max length is 32 bytes.
75 * @param ... Format string arguments.
76 */
77RTDECL(int) RTCondVarCreateEx(PRTCONDVAR phCondVar, uint32_t fFlags, RTLOCKVALCLASS hClass,
78 const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(4, 5);
79
80/** @name RTCondVarCreateEx flags
81 * @{ */
82/** Disables lock validation. */
83#define RTCONDVAR_FLAGS_NO_LOCK_VAL UINT32_C(0x00000001)
84/** @} */
85
86/**
87 * Destroy a condition variable.
88 *
89 * @returns iprt status code.
90 * @param hCondVar Handle of the condition variable. NIL_RTCONDVAR
91 * is quietly ignored (VINF_SUCCESS).
92 */
93RTDECL(int) RTCondVarDestroy(RTCONDVAR hCondVar);
94
95/**
96 * Signal the condition variable, waking up exactly one thread.
97 *
98 * It is recommended that the caller holds the associated lock, but this is not
99 * strictly speaking necessary.
100 *
101 * If no threads are waiting on the condition variable, the call will have no
102 * effect on the variable.
103 *
104 * @returns iprt status code.
105 * @param hCondVar The condition variable to signal.
106 */
107RTDECL(int) RTCondVarSignal(RTCONDVAR hCondVar);
108
109/**
110 * Signal the condition variable, waking up all blocked threads.
111 *
112 * It is recommended that the caller holds the associated lock, but this is not
113 * strictly speaking necessary.
114 *
115 * If no threads are waiting on the condition variable, the call will have no
116 * effect on the variable.
117 *
118 * @returns iprt status code.
119 * @param hCondVar The condition variable to broadcast.
120 */
121RTDECL(int) RTCondVarBroadcast(RTCONDVAR hCondVar);
122
123/**
124 * Wait for the condition variable to be signaled, resume on interruption.
125 *
126 * This function will resume if the wait is interrupted by an async system event
127 * (like a unix signal) or similar.
128 *
129 * @returns iprt status code.
130 * Will not return VERR_INTERRUPTED.
131 * @param hCondVar The condition variable to wait on.
132 * @param hMtx The mutex to leave during the wait and which
133 * will be re-enter before returning.
134 * @param cMillies Number of milliseconds to wait. Use
135 * RT_INDEFINITE_WAIT to wait forever.
136 */
137RTDECL(int) RTCondVarMutexWait(RTCONDVAR hCondVar, RTSEMMUTEX hMtx, RTMSINTERVAL cMillies);
138
139/**
140 * Wait for the condition variable to be signaled, return on interruption.
141 *
142 * This function will not resume the wait if interrupted.
143 *
144 * @returns iprt status code.
145 * @param hCondVar The condition variable to wait on.
146 * @param hMtx The mutex to leave during the wait and which
147 * will be re-enter before returning.
148 * @param cMillies Number of milliseconds to wait. Use
149 * RT_INDEFINITE_WAIT to wait forever.
150 */
151RTDECL(int) RTCondVarMutexWaitNoResume(RTCONDVAR hCondVar, RTSEMMUTEX hMtx, RTMSINTERVAL cMillies);
152
153/**
154 * Wait for the condition variable to be signaled, resume on interruption.
155 *
156 * This function will resume if the wait is interrupted by an async system event
157 * (like a unix signal) or similar.
158 *
159 * @returns iprt status code.
160 * Will not return VERR_INTERRUPTED.
161 * @param hCondVar The condition variable to wait on.
162 * @param hRWSem The read/write semaphore to write-leave during
163 * the wait and which will be re-enter in write
164 * mode before returning.
165 * @param cMillies Number of milliseconds to wait. Use
166 * RT_INDEFINITE_WAIT to wait forever.
167 */
168RTDECL(int) RTCondVarRWWriteWait(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
169
170/**
171 * Wait for the condition variable to be signaled, return on interruption.
172 *
173 * This function will not resume the wait if interrupted.
174 *
175 * @returns iprt status code.
176 * @param hCondVar The condition variable to wait on.
177 * @param hRWSem The read/write semaphore to write-leave during
178 * the wait and which will be re-enter in write
179 * mode before returning.
180 * @param cMillies Number of milliseconds to wait. Use
181 * RT_INDEFINITE_WAIT to wait forever.
182 */
183RTDECL(int) RTCondVarRWWriteWaitNoResume(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
184
185/**
186 * Wait for the condition variable to be signaled, resume on interruption.
187 *
188 * This function will resume if the wait is interrupted by an async system event
189 * (like a unix signal) or similar.
190 *
191 * @returns iprt status code.
192 * Will not return VERR_INTERRUPTED.
193 * @param hCondVar The condition variable to wait on.
194 * @param hRWSem The read/write semaphore to read-leave during
195 * the wait and which will be re-enter in read mode
196 * before returning.
197 * @param cMillies Number of milliseconds to wait. Use
198 * RT_INDEFINITE_WAIT to wait forever.
199 */
200RTDECL(int) RTCondVarRWReadWait(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
201
202/**
203 * Wait for the condition variable to be signaled, return on interruption.
204 *
205 * This function will not resume the wait if interrupted.
206 *
207 * @returns iprt status code.
208 * @param hCondVar The condition variable to wait on.
209 * @param hRWSem The read/write semaphore to read-leave during
210 * the wait and which will be re-enter in read mode
211 * before returning.
212 * @param cMillies Number of milliseconds to wait. Use
213 * RT_INDEFINITE_WAIT to wait forever.
214 */
215RTDECL(int) RTCondVarRWReadWaitNoResume(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
216
217/**
218 * Wait for the condition variable to be signaled, resume on interruption.
219 *
220 * This function will resume if the wait is interrupted by an async system event
221 * (like a unix signal) or similar.
222 *
223 * @returns iprt status code.
224 * Will not return VERR_INTERRUPTED.
225 * @param hCondVar The condition variable to wait on.
226 * @param pCritSect The critical section to leave during the wait
227 * and which will be re-enter before returning.
228 * @param cMillies Number of milliseconds to wait. Use
229 * RT_INDEFINITE_WAIT to wait forever.
230 */
231RTDECL(int) RTCondVarCritSectWait(RTCONDVAR hCondVar, PRTCRITSECT pCritSect, RTMSINTERVAL cMillies);
232
233/**
234 * Wait for the condition variable to be signaled, return on interruption.
235 *
236 * This function will not resume the wait if interrupted.
237 *
238 * @returns iprt status code.
239 * @param hCondVar The condition variable to wait on.
240 * @param pCritSect The critical section to leave during the wait
241 * and which will be re-enter before returning.
242 * @param cMillies Number of milliseconds to wait. Use
243 * RT_INDEFINITE_WAIT to wait forever.
244 */
245RTDECL(int) RTCondVarCritSectWaitNoResume(RTCONDVAR hCondVar, PRTCRITSECT pCritSect, RTMSINTERVAL cMillies);
246
247/**
248 * Sets the signaller thread to one specific thread.
249 *
250 * This is only used for validating usage and deadlock detection. When used
251 * after calls to RTCondVarAddSignaller, the specified thread will be the only
252 * signalling thread.
253 *
254 * @param hCondVar The condition variable.
255 * @param hThread The thread that will signal it. Pass
256 * NIL_RTTHREAD to indicate that there is no
257 * special signalling thread.
258 */
259RTDECL(void) RTCondVarSetSignaller(RTCONDVAR hCondVar, RTTHREAD hThread);
260
261/**
262 * To add more signalling threads.
263 *
264 * First call RTCondVarSetSignaller then add further threads with this.
265 *
266 * @param hCondVar The condition variable.
267 * @param hThread The thread that will signal it. NIL_RTTHREAD is
268 * not accepted.
269 */
270RTDECL(void) RTCondVarAddSignaller(RTCONDVAR hCondVar, RTTHREAD hThread);
271
272/**
273 * To remove a signalling thread.
274 *
275 * Reverts work done by RTCondVarAddSignaller and RTCondVarSetSignaller.
276 *
277 * @param hCondVar The condition variable.
278 * @param hThread A previously added thread.
279 */
280RTDECL(void) RTCondVarRemoveSignaller(RTCONDVAR hCondVar, RTTHREAD hThread);
281
282/** @} */
283
284RT_C_DECLS_END
285
286#endif /* !IPRT_INCLUDED_condvar_h */
287
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette