VirtualBox

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

Last change on this file since 97583 was 96407, checked in by vboxsync, 2 years ago

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