VirtualBox

source: vbox/trunk/include/iprt/semaphore.h@ 47356

Last change on this file since 47356 was 44528, checked in by vboxsync, 12 years ago

header (C) fixes

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 55.5 KB
Line 
1/** @file
2 * IPRT - Semaphore.
3 */
4
5/*
6 * Copyright (C) 2006-2012 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_semaphore_h
27#define ___iprt_semaphore_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31#if defined(RT_LOCK_STRICT_ORDER) && defined(IN_RING3)
32# include <iprt/lockvalidator.h>
33#endif
34
35
36RT_C_DECLS_BEGIN
37
38/** @defgroup grp_rt_sems RTSem - Semaphores
39 *
40 * This module implements all kinds of event and mutex semaphores; in addition
41 * to these, IPRT implements "critical sections", which are fast recursive
42 * mutexes (see @ref grp_rt_critsect ). C++ users may find @ref grp_rt_cpp_lock
43 * interesting.
44 *
45 * @ingroup grp_rt
46 * @{
47 */
48
49
50/** @name Generic Semaphore Wait Flags.
51 *
52 * @remarks Exactly one of RTSEMWAIT_FLAGS_RELATIVE and
53 * RTSEMWAIT_FLAGS_ABSOLUTE must be set, unless
54 * RTSEMWAIT_FLAGS_INDEFINITE is used.
55 *
56 * Exactly one of RTSEMWAIT_FLAGS_NANOSECS and
57 * RTSEMWAIT_FLAGS_MILLISECS must be set, unless
58 * RTSEMWAIT_FLAGS_INDEFINITE is used.
59 *
60 * Exactly one of RTSEMWAIT_FLAGS_RESUME and RTSEMWAIT_FLAGS_NORESUME
61 * must be set.
62 *
63 * The interruptible vs resume stuff is ring-0 vs ring-3 semantics.
64 *
65 * @{ */
66/** The timeout is relative. */
67#define RTSEMWAIT_FLAGS_RELATIVE RT_BIT_32(0)
68/** The timeout is absolute. */
69#define RTSEMWAIT_FLAGS_ABSOLUTE RT_BIT_32(1)
70/** The timeout is specified in nanoseconds. */
71#define RTSEMWAIT_FLAGS_NANOSECS RT_BIT_32(2)
72/** The timeout is specified in milliseconds. */
73#define RTSEMWAIT_FLAGS_MILLISECS RT_BIT_32(3)
74/** Indefinite wait.
75 * The relative/absolute and nano-/millisecond flags are ignored. */
76#define RTSEMWAIT_FLAGS_INDEFINITE RT_BIT_32(4)
77/** Mask covering the time related bits. */
78#define RTSEMWAIT_FLAGS_TIME_MASK UINT32_C(0x0000001f)
79
80/** Interruptible wait. */
81#define RTSEMWAIT_FLAGS_INTERRUPTIBLE RT_BIT_32(5)
82/** No automatic resume, same as interruptible. */
83#define RTSEMWAIT_FLAGS_NORESUME RTSEMWAIT_FLAGS_INTERRUPTIBLE
84/** Uninterruptible wait. */
85#define RTSEMWAIT_FLAGS_UNINTERRUPTIBLE RT_BIT_32(6)
86/** Resume on interrupt, same as uninterruptible. */
87#define RTSEMWAIT_FLAGS_RESUME RTSEMWAIT_FLAGS_UNINTERRUPTIBLE
88
89/** Macro for validate the flags. */
90#define RTSEMWAIT_FLAGS_ARE_VALID(fFlags) \
91 ( !((fFlags) & UINT32_C(0xffffff80)) \
92 && ( ((fFlags) & RTSEMWAIT_FLAGS_INDEFINITE) \
93 ? ( (((fFlags) & UINT32_C(0x20))) ^ (((fFlags) >> 1) & UINT32_C(0x20)) ) == UINT32_C(0x20) \
94 : ( (((fFlags) & UINT32_C(0x25))) ^ (((fFlags) >> 1) & UINT32_C(0x25)) ) == UINT32_C(0x25) ))
95/** @} */
96
97
98
99/** @defgroup grp_rt_sems_event RTSemEvent - Single Release Event Semaphores
100 *
101 * Event semaphores can be used for inter-thread communication when one thread
102 * wants to notify another thread that something happened. A thread can block
103 * ("wait") on an event semaphore until it is signalled by another thread; see
104 * RTSemEventCreate, RTSemEventSignal and RTSemEventWait.
105 *
106 * @{ */
107
108/**
109 * Create an event semaphore.
110 *
111 * @returns iprt status code.
112 * @param phEventSem Where to store the handle to the newly created
113 * event semaphore.
114 */
115RTDECL(int) RTSemEventCreate(PRTSEMEVENT phEventSem);
116
117/**
118 * Create an event semaphore.
119 *
120 * @returns iprt status code.
121 * @param phEventSem Where to store the handle to the newly created
122 * event semaphore.
123 * @param fFlags Flags, any combination of the
124 * RTSEMEVENT_FLAGS_XXX \#defines.
125 * @param hClass The class (no reference consumed). Since we
126 * don't do order checks on event semaphores, the
127 * use of the class is limited to controlling the
128 * timeout threshold for deadlock detection.
129 * @param pszNameFmt Name format string for the lock validator,
130 * optional (NULL). Max length is 32 bytes.
131 * @param ... Format string arguments.
132 */
133RTDECL(int) RTSemEventCreateEx(PRTSEMEVENT phEventSem, uint32_t fFlags, RTLOCKVALCLASS hClass, const char *pszNameFmt, ...);
134
135/** @name RTSemMutexCreateEx flags
136 * @{ */
137/** Disables lock validation. */
138#define RTSEMEVENT_FLAGS_NO_LOCK_VAL UINT32_C(0x00000001)
139/** Bootstrap hack for use with certain memory allocator locks only! */
140#define RTSEMEVENT_FLAGS_BOOTSTRAP_HACK UINT32_C(0x00000004)
141/** @} */
142
143/**
144 * Destroy an event semaphore.
145 *
146 * @returns iprt status code.
147 * @param hEventSem Handle of the event semaphore. NIL_RTSEMEVENT
148 * is quietly ignored (VINF_SUCCESS).
149 */
150RTDECL(int) RTSemEventDestroy(RTSEMEVENT hEventSem);
151
152/**
153 * Signal an event semaphore.
154 *
155 * The event semaphore will be signaled and automatically reset after exactly
156 * one thread have successfully returned from RTSemEventWait() after
157 * waiting/polling on that semaphore.
158 *
159 * @returns iprt status code.
160 * @param hEventSem The event semaphore to signal.
161 *
162 * @remarks ring-0: This works when preemption is disabled. However it is
163 * system specific whether it works in interrupt context or with
164 * interrupts disabled.
165 */
166RTDECL(int) RTSemEventSignal(RTSEMEVENT hEventSem);
167
168/**
169 * Wait for the event semaphore to be signaled, resume on interruption.
170 *
171 * This function will resume if the wait is interrupted by an async system event
172 * (like a unix signal) or similar.
173 *
174 * @returns iprt status code.
175 * Will not return VERR_INTERRUPTED.
176 * @param hEventSem The event semaphore to wait on.
177 * @param cMillies Number of milliseconds to wait.
178 */
179RTDECL(int) RTSemEventWait(RTSEMEVENT hEventSem, RTMSINTERVAL cMillies);
180
181/**
182 * Wait for the event semaphore to be signaled, return on interruption.
183 *
184 * This function will not resume the wait if interrupted.
185 *
186 * @returns iprt status code.
187 * @param hEventSem The event semaphore to wait on.
188 * @param cMillies Number of milliseconds to wait.
189 */
190RTDECL(int) RTSemEventWaitNoResume(RTSEMEVENT hEventSem, RTMSINTERVAL cMillies);
191
192/**
193 * Extended API for waiting on an event semaphore to be signaled.
194 *
195 * @returns IPRT status code.
196 * @param hEventSem The event semaphore to wait on.
197 * @param fFlags Combination of RTSEMWAIT_FLAGS_XXX.
198 * @param uTimeout The timeout, ignored if
199 * RTSEMWAIT_FLAGS_INDEFINITE is set in @a flags.
200 * Whether this is absolute or relative,
201 * milliseconds or nanoseconds depends on the @a
202 * fFlags value. Do not pass RT_INDEFINITE_WAIT
203 * here, use RTSEMWAIT_FLAGS_INDEFINITE instead.
204 */
205RTDECL(int) RTSemEventWaitEx(RTSEMEVENT hEventSem, uint32_t fFlags, uint64_t uTimeout);
206
207/**
208 * Debug version of RTSemEventWaitEx that tracks the location.
209 *
210 * @returns IPRT status code, see RTSemEventWaitEx.
211 * @param hEventSem The event semaphore to wait on.
212 * @param fFlags See RTSemEventWaitEx.
213 * @param uTimeout See RTSemEventWaitEx.
214 * @param uId Some kind of locking location ID. Typically a
215 * return address up the stack. Optional (0).
216 * @param pszFile The file where the lock is being acquired from.
217 * Optional.
218 * @param iLine The line number in that file. Optional (0).
219 * @param pszFunction The function where the lock is being acquired
220 * from. Optional.
221 */
222RTDECL(int) RTSemEventWaitExDebug(RTSEMEVENT hEventSem, uint32_t fFlags, uint64_t uTimeout,
223 RTHCUINTPTR uId, RT_SRC_POS_DECL);
224
225/**
226 * Gets the best timeout resolution that RTSemEventWaitEx can do.
227 *
228 * @returns The resolution in nanoseconds.
229 */
230RTDECL(uint32_t) RTSemEventGetResolution(void);
231
232/**
233 * Sets the signaller thread to one specific thread.
234 *
235 * This is only used for validating usage and deadlock detection. When used
236 * after calls to RTSemEventAddSignaller, the specified thread will be the only
237 * signalling thread.
238 *
239 * @param hEventSem The event semaphore.
240 * @param hThread The thread that will signal it. Pass
241 * NIL_RTTHREAD to indicate that there is no
242 * special signalling thread.
243 */
244RTDECL(void) RTSemEventSetSignaller(RTSEMEVENT hEventSem, RTTHREAD hThread);
245
246/**
247 * To add more signalling threads.
248 *
249 * First call RTSemEventSetSignaller then add further threads with this.
250 *
251 * @param hEventSem The event semaphore.
252 * @param hThread The thread that will signal it. NIL_RTTHREAD is
253 * not accepted.
254 */
255RTDECL(void) RTSemEventAddSignaller(RTSEMEVENT hEventSem, RTTHREAD hThread);
256
257/**
258 * To remove a signalling thread.
259 *
260 * Reverts work done by RTSemEventAddSignaller and RTSemEventSetSignaller.
261 *
262 * @param hEventSem The event semaphore.
263 * @param hThread A previously added thread.
264 */
265RTDECL(void) RTSemEventRemoveSignaller(RTSEMEVENT hEventSem, RTTHREAD hThread);
266
267/** @} */
268
269
270/** @defgroup grp_rt_sems_event_multi RTSemEventMulti - Multiple Release Event Semaphores
271 *
272 * A variant of @ref grp_rt_sems_event where all threads will be unblocked when
273 * signalling the semaphore.
274 *
275 * @{ */
276
277/**
278 * Creates a multiple release event semaphore.
279 *
280 * @returns iprt status code.
281 * @param phEventMultiSem Where to store the handle to the newly created
282 * multiple release event semaphore.
283 */
284RTDECL(int) RTSemEventMultiCreate(PRTSEMEVENTMULTI phEventMultiSem);
285
286/**
287 * Creates a multiple release event semaphore.
288 *
289 * @returns iprt status code.
290 * @param phEventMultiSem Where to store the handle to the newly created
291 * multiple release event semaphore.
292 * @param fFlags Flags, any combination of the
293 * RTSEMEVENTMULTI_FLAGS_XXX \#defines.
294 * @param hClass The class (no reference consumed). Since we
295 * don't do order checks on event semaphores, the
296 * use of the class is limited to controlling the
297 * timeout threshold for deadlock detection.
298 * @param pszNameFmt Name format string for the lock validator,
299 * optional (NULL). Max length is 32 bytes.
300 * @param ... Format string arguments.
301 */
302RTDECL(int) RTSemEventMultiCreateEx(PRTSEMEVENTMULTI phEventMultiSem, uint32_t fFlags, RTLOCKVALCLASS hClass,
303 const char *pszNameFmt, ...);
304
305/** @name RTSemMutexCreateEx flags
306 * @{ */
307/** Disables lock validation. */
308#define RTSEMEVENTMULTI_FLAGS_NO_LOCK_VAL UINT32_C(0x00000001)
309/** @} */
310
311/**
312 * Destroy an event multi semaphore.
313 *
314 * @returns iprt status code.
315 * @param hEventMultiSem The multiple release event semaphore. NIL is
316 * quietly ignored (VINF_SUCCESS).
317 */
318RTDECL(int) RTSemEventMultiDestroy(RTSEMEVENTMULTI hEventMultiSem);
319
320/**
321 * Signal an event multi semaphore.
322 *
323 * @returns iprt status code.
324 * @param hEventMultiSem The multiple release event semaphore.
325 *
326 * @remarks ring-0: This works when preemption is disabled. However it is
327 * system specific whether it works in interrupt context or with
328 * interrupts disabled.
329 */
330RTDECL(int) RTSemEventMultiSignal(RTSEMEVENTMULTI hEventMultiSem);
331
332/**
333 * Resets an event multi semaphore to non-signaled state.
334 *
335 * @returns iprt status code.
336 * @param hEventMultiSem The multiple release event semaphore.
337 */
338RTDECL(int) RTSemEventMultiReset(RTSEMEVENTMULTI hEventMultiSem);
339
340/**
341 * Wait for the event multi semaphore to be signaled, resume on interruption.
342 *
343 * This function will resume if the wait is interrupted by an async
344 * system event (like a unix signal) or similar.
345 *
346 * @returns iprt status code.
347 * Will not return VERR_INTERRUPTED.
348 * @param hEventMultiSem The multiple release event semaphore.
349 * @param cMillies Number of milliseconds to wait.
350 */
351RTDECL(int) RTSemEventMultiWait(RTSEMEVENTMULTI hEventMultiSem, RTMSINTERVAL cMillies);
352
353/**
354 * Wait for the event multi semaphore to be signaled, return on interruption.
355 *
356 * This function will not resume the wait if interrupted.
357 *
358 * @returns iprt status code.
359 * @param hEventMultiSem The multiple release event semaphore.
360 * @param cMillies Number of milliseconds to wait.
361 * @todo Rename to RTSemEventMultiWaitIntr since it is mainly for
362 * ring-0 consumption.
363 */
364RTDECL(int) RTSemEventMultiWaitNoResume(RTSEMEVENTMULTI hEventMultiSem, RTMSINTERVAL cMillies);
365
366/**
367 * Extended API for waiting on an event semaphore to be signaled.
368 *
369 * @returns IPRT status code.
370 * @param hEventMultiSem The multiple release event semaphore to wait
371 * on.
372 * @param fFlags Combination of the RTSEMWAIT_FLAGS_XXX.
373 * @param uTimeout The timeout, ignored if
374 * RTSEMWAIT_FLAGS_INDEFINITE is set in @a flags.
375 * Whether this is absolute or relative,
376 * milliseconds or nanoseconds depends on the @a
377 * fFlags value. Do not pass RT_INDEFINITE_WAIT
378 * here, use RTSEMWAIT_FLAGS_INDEFINITE instead.
379 */
380RTDECL(int) RTSemEventMultiWaitEx(RTSEMEVENTMULTI hEventMultiSem, uint32_t fFlags, uint64_t uTimeout);
381
382/**
383 * Debug version of RTSemEventMultiWaitEx that tracks the location.
384
385 * @returns IPRT status code, see RTSemEventMultiWaitEx.
386 * @param hEventMultiSem The multiple release event semaphore handle.
387 * @param fFlags See RTSemEventMultiWaitEx.
388 * @param uTimeout See RTSemEventMultiWaitEx.
389 * @param uId Some kind of locking location ID. Typically a
390 * return address up the stack. Optional (0).
391 * @param pszFile The file where the lock is being acquired from.
392 * Optional.
393 * @param iLine The line number in that file. Optional (0).
394 * @param pszFunction The function where the lock is being acquired
395 * from. Optional.
396 */
397RTDECL(int) RTSemEventMultiWaitExDebug(RTSEMEVENTMULTI hEventMultiSem, uint32_t fFlags, uint64_t uTimeout,
398 RTHCUINTPTR uId, RT_SRC_POS_DECL);
399
400/**
401 * Gets the best timeout resolution that RTSemEventMultiWaitEx can do.
402 *
403 * @returns The resolution in nanoseconds.
404 */
405RTDECL(uint32_t) RTSemEventMultiGetResolution(void);
406
407/**
408 * Sets the signaller thread to one specific thread.
409 *
410 * This is only used for validating usage and deadlock detection. When used
411 * after calls to RTSemEventAddSignaller, the specified thread will be the only
412 * signalling thread.
413 *
414 * @param hEventMultiSem The multiple release event semaphore.
415 * @param hThread The thread that will signal it. Pass
416 * NIL_RTTHREAD to indicate that there is no
417 * special signalling thread.
418 */
419RTDECL(void) RTSemEventMultiSetSignaller(RTSEMEVENTMULTI hEventMultiSem, RTTHREAD hThread);
420
421/**
422 * To add more signalling threads.
423 *
424 * First call RTSemEventSetSignaller then add further threads with this.
425 *
426 * @param hEventMultiSem The multiple release event semaphore.
427 * @param hThread The thread that will signal it. NIL_RTTHREAD is
428 * not accepted.
429 */
430RTDECL(void) RTSemEventMultiAddSignaller(RTSEMEVENTMULTI hEventMultiSem, RTTHREAD hThread);
431
432/**
433 * To remove a signalling thread.
434 *
435 * Reverts work done by RTSemEventAddSignaller and RTSemEventSetSignaller.
436 *
437 * @param hEventMultiSem The multiple release event semaphore.
438 * @param hThread A previously added thread.
439 */
440RTDECL(void) RTSemEventMultiRemoveSignaller(RTSEMEVENTMULTI hEventMultiSem, RTTHREAD hThread);
441
442/** @} */
443
444
445/** @defgroup grp_rt_sems_mutex RTSemMutex - Mutex semaphores.
446 *
447 * Mutex semaphores protect a section of code or data to which access must be
448 * exclusive. Only one thread can hold access to a critical section at one
449 * time. See RTSemMutexCreate, RTSemMutexRequest and RTSemMutexRelease.
450 *
451 * @remarks These are less efficient than "fast mutexes" and "critical
452 * sections", which IPRT implements as well; see @ref
453 * grp_rt_sems_fast_mutex and @ref grp_rt_critsect .
454 *
455 * @{ */
456
457/**
458 * Create a mutex semaphore.
459 *
460 * @returns iprt status code.
461 * @param phMutexSem Where to store the mutex semaphore handle.
462 */
463RTDECL(int) RTSemMutexCreate(PRTSEMMUTEX phMutexSem);
464
465/**
466 * Creates a read/write semaphore.
467 *
468 * @returns iprt status code.
469 * @param phRWSem Where to store the handle to the newly created
470 * RW semaphore.
471 * @param fFlags Flags, any combination of the
472 * RTSEMMUTEX_FLAGS_XXX \#defines.
473 * @param hClass The class (no reference consumed). If NIL, no
474 * lock order validation will be performed on this
475 * lock.
476 * @param uSubClass The sub-class. This is used to define lock
477 * order within a class. RTLOCKVAL_SUB_CLASS_NONE
478 * is the recommended value here.
479 * @param pszNameFmt Name format string for the lock validator,
480 * optional (NULL). Max length is 32 bytes.
481 * @param ... Format string arguments.
482 */
483RTDECL(int) RTSemMutexCreateEx(PRTSEMMUTEX phMutexSem, uint32_t fFlags,
484 RTLOCKVALCLASS hClass, uint32_t uSubClass, const char *pszNameFmt, ...);
485
486/** @name RTSemMutexCreateEx flags
487 * @{ */
488/** Disables lock validation. */
489#define RTSEMMUTEX_FLAGS_NO_LOCK_VAL UINT32_C(0x00000001)
490/** @} */
491
492
493/**
494 * Destroy a mutex semaphore.
495 *
496 * @returns iprt status code.
497 * @param hMutexSem The mutex semaphore to destroy. NIL is quietly
498 * ignored (VINF_SUCCESS).
499 */
500RTDECL(int) RTSemMutexDestroy(RTSEMMUTEX hMutexSem);
501
502/**
503 * Changes the lock validator sub-class of the mutex semaphore.
504 *
505 * It is recommended to try make sure that nobody is using this semaphore while
506 * changing the value.
507 *
508 * @returns The old sub-class. RTLOCKVAL_SUB_CLASS_INVALID is returns if the
509 * lock validator isn't compiled in or either of the parameters are
510 * invalid.
511 * @param hMutexSem The handle to the mutex semaphore.
512 * @param uSubClass The new sub-class value.
513 */
514RTDECL(uint32_t) RTSemMutexSetSubClass(RTSEMMUTEX hMutexSem, uint32_t uSubClass);
515
516/**
517 * Request ownership of a mutex semaphore, resume on interruption.
518 *
519 * This function will resume if the wait is interrupted by an async
520 * system event (like a unix signal) or similar.
521 *
522 * The same thread may request a mutex semaphore multiple times,
523 * a nested counter is kept to make sure it's released on the right
524 * RTSemMutexRelease() call.
525 *
526 * @returns iprt status code.
527 * Will not return VERR_INTERRUPTED.
528 * @param hMutexSem The mutex semaphore to request ownership over.
529 * @param cMillies The number of milliseconds to wait.
530 */
531RTDECL(int) RTSemMutexRequest(RTSEMMUTEX hMutexSem, RTMSINTERVAL cMillies);
532
533/**
534 * Request ownership of a mutex semaphore, return on interruption.
535 *
536 * This function will not resume the wait if interrupted.
537 *
538 * The same thread may request a mutex semaphore multiple times,
539 * a nested counter is kept to make sure it's released on the right
540 * RTSemMutexRelease() call.
541 *
542 * @returns iprt status code.
543 * @param hMutexSem The mutex semaphore to request ownership over.
544 * @param cMillies The number of milliseconds to wait.
545 */
546RTDECL(int) RTSemMutexRequestNoResume(RTSEMMUTEX hMutexSem, RTMSINTERVAL cMillies);
547
548/**
549 * Debug version of RTSemMutexRequest that tracks the location.
550 *
551 * @returns iprt status code.
552 * Will not return VERR_INTERRUPTED.
553 * @param hMutexSem The mutex semaphore to request ownership over.
554 * @param cMillies The number of milliseconds to wait.
555 * @param uId Some kind of locking location ID. Typically a
556 * return address up the stack. Optional (0).
557 * @param pszFile The file where the lock is being acquired from.
558 * Optional.
559 * @param iLine The line number in that file. Optional (0).
560 * @param pszFunction The function where the lock is being acquired
561 * from. Optional.
562 */
563RTDECL(int) RTSemMutexRequestDebug(RTSEMMUTEX hMutexSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
564
565/**
566 * Debug version of RTSemMutexRequestNoResume that tracks the location.
567 *
568 * @returns iprt status code.
569 * @param hMutexSem The mutex semaphore to request ownership over.
570 * @param cMillies The number of milliseconds to wait.
571 * @param uId Some kind of locking location ID. Typically a
572 * return address up the stack. Optional (0).
573 * @param pszFile The file where the lock is being acquired from.
574 * Optional.
575 * @param iLine The line number in that file. Optional (0).
576 * @param pszFunction The function where the lock is being acquired
577 * from. Optional.
578 */
579RTDECL(int) RTSemMutexRequestNoResumeDebug(RTSEMMUTEX hMutexSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
580
581/**
582 * Request ownership of a mutex semaphore, extended edition.
583 *
584 * The same thread may request a mutex semaphore multiple times,
585 * a nested counter is kept to make sure it's released on the right
586 * RTSemMutexRelease() call.
587 *
588 * @returns iprt status code.
589 * @param hMutexSem The mutex semaphore to request ownership over.
590 * @param fFlags Combination of the RTSEMWAIT_FLAGS_XXX.
591 * @param uTimeout The timeout, ignored if
592 * RTSEMWAIT_FLAGS_INDEFINITE is set in @a flags.
593 * Whether this is absolute or relative,
594 * milliseconds or nanoseconds depends on the @a
595 * fFlags value. Do not pass RT_INDEFINITE_WAIT
596 * here, use RTSEMWAIT_FLAGS_INDEFINITE instead.
597 */
598RTDECL(int) RTSemMutexRequestEx(RTSEMMUTEX hMutexSem, uint32_t fFlags, uint64_t uTimeout);
599
600/**
601 * Debug version of RTSemMutexRequestEx that tracks the location.
602 *
603 * @returns iprt status code.
604 * @param hMutexSem The mutex semaphore to request ownership over.
605 * @param fFlags See RTSemMutexRequestEx.
606 * @param uTimeout See RTSemMutexRequestEx.
607 * @param uId Some kind of locking location ID. Typically a
608 * return address up the stack. Optional (0).
609 * @param pszFile The file where the lock is being acquired from.
610 * Optional.
611 * @param iLine The line number in that file. Optional (0).
612 * @param pszFunction The function where the lock is being acquired
613 * from. Optional.
614 */
615RTDECL(int) RTSemMutexRequestExDebug(RTSEMMUTEX hMutexSem, uint32_t fFlags, uint64_t uTimeout,
616 RTHCUINTPTR uId, RT_SRC_POS_DECL);
617
618/**
619 * Release the ownership of a mutex semaphore.
620 *
621 * @returns iprt status code.
622 * @param hMutexSem The mutex to release the ownership of. It goes
623 * without saying the the calling thread must own
624 * it.
625 */
626RTDECL(int) RTSemMutexRelease(RTSEMMUTEX hMutexSem);
627
628/**
629 * Checks if the mutex semaphore is owned or not.
630 *
631 * @returns true if owned, false if not.
632 * @param hMutexSem The mutex semaphore.
633 */
634RTDECL(bool) RTSemMutexIsOwned(RTSEMMUTEX hMutexSem);
635
636/* Strict build: Remap the two request calls to the debug versions. */
637#if defined(RT_STRICT) && !defined(RTSEMMUTEX_WITHOUT_REMAPPING) && !defined(RT_WITH_MANGLING)
638# ifdef ___iprt_asm_h
639# define RTSemMutexRequest(hMutexSem, cMillies) RTSemMutexRequestDebug((hMutexSem), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
640# define RTSemMutexRequestNoResume(hMutexSem, cMillies) RTSemMutexRequestNoResumeDebug((hMutexSem), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
641# define RTSemMutexRequestEx(hMutexSem, fFlags, uTimeout) RTSemMutexRequestExDebug((hMutexSem), (fFlags), (uTimeout), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
642# else
643# define RTSemMutexRequest(hMutexSem, cMillies) RTSemMutexRequestDebug((hMutexSem), (cMillies), 0, RT_SRC_POS)
644# define RTSemMutexRequestNoResume(hMutexSem, cMillies) RTSemMutexRequestNoResumeDebug((hMutexSem), (cMillies), 0, RT_SRC_POS)
645# define RTSemMutexRequestEx(hMutexSem, fFlags, uTimeout) RTSemMutexRequestExDebug((hMutexSem), (fFlags), (uTimeout), 0, RT_SRC_POS)
646# endif
647#endif
648
649/* Strict lock order: Automatically classify locks by init location. */
650#if defined(RT_LOCK_STRICT_ORDER) && defined(IN_RING3) && !defined(RTSEMMUTEX_WITHOUT_REMAPPING) && !defined(RT_WITH_MANGLING)
651# define RTSemMutexCreate(phMutexSem) \
652 RTSemMutexCreateEx((phMutexSem), 0 /*fFlags*/, \
653 RTLockValidatorClassForSrcPos(RT_SRC_POS, NULL), \
654 RTLOCKVAL_SUB_CLASS_NONE, NULL)
655#endif
656
657/** @} */
658
659
660/** @defgroup grp_rt_sems_fast_mutex RTSemFastMutex - Fast Mutex Semaphores
661 *
662 * Fast mutexes work like regular mutexes in that they allow only a single
663 * thread access to a critical piece of code or data. As opposed to mutexes,
664 * they require no syscall if the fast mutex is not held (like critical
665 * sections). Unlike critical sections however, they are *not* recursive.
666 *
667 * @remarks The fast mutexes has sideeffects on IRQL on Windows hosts. So use
668 * with care and test on windows with driver verifier.
669 *
670 * @{ */
671
672/**
673 * Create a fast mutex semaphore.
674 *
675 * @returns iprt status code.
676 * @param phFastMtx Where to store the handle to the newly created
677 * fast mutex semaphore.
678 *
679 * @remarks Fast mutex semaphores are not recursive.
680 */
681RTDECL(int) RTSemFastMutexCreate(PRTSEMFASTMUTEX phFastMtx);
682
683/**
684 * Destroy a fast mutex semaphore.
685 *
686 * @returns iprt status code.
687 * @param hFastMtx Handle to the fast mutex semaphore. NIL is
688 * quietly ignored (VINF_SUCCESS).
689 */
690RTDECL(int) RTSemFastMutexDestroy(RTSEMFASTMUTEX hFastMtx);
691
692/**
693 * Request ownership of a fast mutex semaphore.
694 *
695 * The same thread may request a mutex semaphore multiple times,
696 * a nested counter is kept to make sure it's released on the right
697 * RTSemMutexRelease() call.
698 *
699 * @returns iprt status code.
700 * @param hFastMtx Handle to the fast mutex semaphore.
701 */
702RTDECL(int) RTSemFastMutexRequest(RTSEMFASTMUTEX hFastMtx);
703
704/**
705 * Release the ownership of a fast mutex semaphore.
706 *
707 * @returns iprt status code.
708 * @param hFastMtx Handle to the fast mutex semaphore. It goes
709 * without saying the the calling thread must own
710 * it.
711 */
712RTDECL(int) RTSemFastMutexRelease(RTSEMFASTMUTEX hFastMtx);
713
714/** @} */
715
716
717/** @defgroup grp_rt_sems_spin_mutex RTSemSpinMutex - Spinning Mutex Semaphores
718 *
719 * A very adaptive variant of mutex semaphore that is tailored for the ring-0
720 * logger.
721 *
722 * @{ */
723
724/**
725 * Creates a spinning mutex semaphore.
726 *
727 * @returns iprt status code.
728 * @retval VERR_INVALID_PARAMETER on invalid flags.
729 * @retval VERR_NO_MEMORY if out of memory for the semaphore structure and
730 * handle.
731 *
732 * @param phSpinMtx Where to return the handle to the create semaphore.
733 * @param fFlags Flags, see RTSEMSPINMUTEX_FLAGS_XXX.
734 */
735RTDECL(int) RTSemSpinMutexCreate(PRTSEMSPINMUTEX phSpinMtx, uint32_t fFlags);
736
737/** @name RTSemSpinMutexCreate flags.
738 * @{ */
739/** Always take the semaphore in a IRQ safe way.
740 * (In plain words: always disable interrupts.) */
741#define RTSEMSPINMUTEX_FLAGS_IRQ_SAFE RT_BIT_32(0)
742/** Mask of valid flags. */
743#define RTSEMSPINMUTEX_FLAGS_VALID_MASK UINT32_C(0x00000001)
744/** @} */
745
746/**
747 * Destroys a spinning mutex semaphore.
748 *
749 * @returns iprt status code.
750 * @retval VERR_INVALID_HANDLE (or crash) if the handle is invalid. (NIL will
751 * not cause this status.)
752 *
753 * @param hSpinMtx The semaphore handle. NIL_RTSEMSPINMUTEX is ignored
754 * quietly (VINF_SUCCESS).
755 */
756RTDECL(int) RTSemSpinMutexDestroy(RTSEMSPINMUTEX hSpinMtx);
757
758/**
759 * Request the spinning mutex semaphore.
760 *
761 * This may block if the context we're called in allows this. If not it will
762 * spin. If called in an interrupt context, we will only spin if the current
763 * owner isn't interrupted. Also, on some systems it is not always possible to
764 * wake up blocking threads in all contexts, so, which will either be indicated
765 * by returning VERR_SEM_BAD_CONTEXT or by temporarily switching the semaphore
766 * into pure spinlock state.
767 *
768 * Preemption will be disabled upon return. IRQs may also be disabled.
769 *
770 * @returns iprt status code.
771 * @retval VERR_SEM_BAD_CONTEXT if the context it's called in isn't suitable
772 * for releasing it if someone is sleeping on it.
773 * @retval VERR_SEM_DESTROYED if destroyed.
774 * @retval VERR_SEM_NESTED if held by the caller. Asserted.
775 * @retval VERR_INVALID_HANDLE if the handle is invalid. Asserted
776 *
777 * @param hSpinMtx The semaphore handle.
778 */
779RTDECL(int) RTSemSpinMutexRequest(RTSEMSPINMUTEX hSpinMtx);
780
781/**
782 * Like RTSemSpinMutexRequest but it won't block or spin if the semaphore is
783 * held by someone else.
784 *
785 * @returns iprt status code.
786 * @retval VERR_SEM_BUSY if held by someone else.
787 * @retval VERR_SEM_DESTROYED if destroyed.
788 * @retval VERR_SEM_NESTED if held by the caller. Asserted.
789 * @retval VERR_INVALID_HANDLE if the handle is invalid. Asserted
790 *
791 * @param hSpinMtx The semaphore handle.
792 */
793RTDECL(int) RTSemSpinMutexTryRequest(RTSEMSPINMUTEX hSpinMtx);
794
795/**
796 * Releases the semaphore previously acquired by RTSemSpinMutexRequest or
797 * RTSemSpinMutexTryRequest.
798 *
799 * @returns iprt status code.
800 * @retval VERR_SEM_DESTROYED if destroyed.
801 * @retval VERR_NOT_OWNER if not owner. Asserted.
802 * @retval VERR_INVALID_HANDLE if the handle is invalid. Asserted.
803 *
804 * @param hSpinMtx The semaphore handle.
805 */
806RTDECL(int) RTSemSpinMutexRelease(RTSEMSPINMUTEX hSpinMtx);
807
808/** @} */
809
810
811/** @defgroup grp_rt_sem_rw RTSemRW - Read / Write Semaphores
812 *
813 * Read/write semaphores are a fancier version of mutexes in that they grant
814 * read access to the protected data to several threads at the same time but
815 * allow only one writer at a time. This can make code scale better at the
816 * expense of slightly more overhead in mutex management.
817 *
818 * @{ */
819
820/**
821 * Creates a read/write semaphore.
822 *
823 * @returns iprt status code.
824 * @param phRWSem Where to store the handle to the newly created
825 * RW semaphore.
826 */
827RTDECL(int) RTSemRWCreate(PRTSEMRW phRWSem);
828
829/**
830 * Creates a read/write semaphore.
831 *
832 * @returns iprt status code.
833 * @param phRWSem Where to store the handle to the newly created
834 * RW semaphore.
835 * @param fFlags Flags, any combination of the RTSEMRW_FLAGS_XXX
836 * \#defines.
837 * @param hClass The class (no reference consumed). If NIL, no
838 * lock order validation will be performed on this
839 * lock.
840 * @param uSubClass The sub-class. This is used to define lock
841 * order within a class. RTLOCKVAL_SUB_CLASS_NONE
842 * is the recommended value here.
843 * @param pszNameFmt Name format string for the lock validator,
844 * optional (NULL). Max length is 32 bytes.
845 * @param ... Format string arguments.
846 */
847RTDECL(int) RTSemRWCreateEx(PRTSEMRW phRWSem, uint32_t fFlags,
848 RTLOCKVALCLASS hClass, uint32_t uSubClass, const char *pszNameFmt, ...);
849
850/** @name RTSemRWCreateEx flags
851 * @{ */
852/** Disables lock validation. */
853#define RTSEMRW_FLAGS_NO_LOCK_VAL UINT32_C(0x00000001)
854/** @} */
855
856/**
857 * Destroys a read/write semaphore.
858 *
859 * @returns iprt status code.
860 * @param hRWSem Handle to the read/write semaphore. NIL is
861 * quietly ignored (VINF_SUCCESS).
862 */
863RTDECL(int) RTSemRWDestroy(RTSEMRW hRWSem);
864
865/**
866 * Changes the lock validator sub-class of the read/write semaphore.
867 *
868 * It is recommended to try make sure that nobody is using this semaphore while
869 * changing the value.
870 *
871 * @returns The old sub-class. RTLOCKVAL_SUB_CLASS_INVALID is returns if the
872 * lock validator isn't compiled in or either of the parameters are
873 * invalid.
874 * @param hRWSem Handle to the read/write semaphore.
875 * @param uSubClass The new sub-class value.
876 */
877RTDECL(uint32_t) RTSemRWSetSubClass(RTSEMRW hRWSem, uint32_t uSubClass);
878
879/**
880 * Request read access to a read/write semaphore, resume on interruption
881 *
882 * @returns iprt status code.
883 * @retval VINF_SUCCESS on success.
884 * @retval VERR_INTERRUPT if the wait was interrupted.
885 * @retval VERR_INVALID_HANDLE if hRWSem is invalid.
886 *
887 * @param hRWSem Handle to the read/write semaphore.
888 * @param cMillies The number of milliseconds to wait.
889 */
890RTDECL(int) RTSemRWRequestRead(RTSEMRW hRWSem, RTMSINTERVAL cMillies);
891
892/**
893 * Request read access to a read/write semaphore, return on interruption
894 *
895 * @returns iprt status code.
896 * @retval VINF_SUCCESS on success.
897 * @retval VERR_INTERRUPT if the wait was interrupted.
898 * @retval VERR_INVALID_HANDLE if hRWSem is invalid.
899 *
900 * @param hRWSem Handle to the read/write semaphore.
901 * @param cMillies The number of milliseconds to wait.
902 */
903RTDECL(int) RTSemRWRequestReadNoResume(RTSEMRW hRWSem, RTMSINTERVAL cMillies);
904
905/**
906 * Debug version of RTSemRWRequestRead that tracks the location.
907 *
908 * @returns iprt status code.
909 * @retval VINF_SUCCESS on success.
910 * @retval VERR_INTERRUPT if the wait was interrupted.
911 * @retval VERR_INVALID_HANDLE if hRWSem is invalid.
912 *
913 * @param hRWSem Handle to the read/write semaphore.
914 * @param cMillies The number of milliseconds to wait.
915 * @param uId Some kind of locking location ID. Typically a
916 * return address up the stack. Optional (0).
917 * @param pszFile The file where the lock is being acquired from.
918 * Optional.
919 * @param iLine The line number in that file. Optional (0).
920 * @param pszFunction The function where the lock is being acquired
921 * from. Optional.
922 */
923RTDECL(int) RTSemRWRequestReadDebug(RTSEMRW hRWSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
924
925/**
926 * Debug version of RTSemRWRequestWriteNoResume that tracks the location.
927 *
928 * @returns iprt status code.
929 * @retval VINF_SUCCESS on success.
930 * @retval VERR_INTERRUPT if the wait was interrupted.
931 * @retval VERR_INVALID_HANDLE if hRWSem is invalid.
932 *
933 * @param hRWSem Handle to the read/write semaphore.
934 * @param cMillies The number of milliseconds to wait.
935 * @param uId Some kind of locking location ID. Typically a
936 * return address up the stack. Optional (0).
937 * @param pszFile The file where the lock is being acquired from.
938 * Optional.
939 * @param iLine The line number in that file. Optional (0).
940 * @param pszFunction The function where the lock is being acquired
941 * from. Optional.
942 */
943RTDECL(int) RTSemRWRequestReadNoResumeDebug(RTSEMRW hRWSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
944
945/**
946 * Request read access to a read/write semaphore, extended edition.
947 *
948 * @returns iprt status code.
949 * @retval VINF_SUCCESS on success.
950 * @retval VERR_INTERRUPT if the wait was interrupted.
951 * @retval VERR_TIMEOUT if the wait timed out.
952 * @retval VERR_INVALID_HANDLE if hRWSem is invalid.
953 *
954 * @param hRWSem Handle to the read/write semaphore.
955 * @param fFlags Combination of the RTSEMWAIT_FLAGS_XXX.
956 * @param uTimeout The timeout, ignored if
957 * RTSEMWAIT_FLAGS_INDEFINITE is set in @a flags.
958 * Whether this is absolute or relative,
959 * milliseconds or nanoseconds depends on the @a
960 * fFlags value. Do not pass RT_INDEFINITE_WAIT
961 * here, use RTSEMWAIT_FLAGS_INDEFINITE instead.
962 */
963RTDECL(int) RTSemRWRequestReadEx(RTSEMRW hRWSem, uint32_t fFlags, uint64_t uTimeout);
964
965
966/**
967 * Debug version of RTSemRWRequestReadEx that tracks the location.
968 *
969 * @returns iprt status code.
970 * @retval VINF_SUCCESS on success.
971 * @retval VERR_INTERRUPT if the wait was interrupted.
972 * @retval VERR_TIMEOUT if the wait timed out.
973 * @retval VERR_INVALID_HANDLE if hRWSem is invalid.
974 *
975 * @param hRWSem Handle to the read/write semaphore.
976 * @param fFlags See RTSemRWRequestReadEx.
977 * @param uTimeout See RTSemRWRequestReadEx.
978 * @param uId Some kind of locking location ID. Typically a
979 * return address up the stack. Optional (0).
980 * @param pszFile The file where the lock is being acquired from.
981 * Optional.
982 * @param iLine The line number in that file. Optional (0).
983 * @param pszFunction The function where the lock is being acquired
984 * from. Optional.
985 */
986RTDECL(int) RTSemRWRequestReadExDebug(RTSEMRW hRWSem, uint32_t fFlags, uint64_t uTimeout,
987 RTHCUINTPTR uId, RT_SRC_POS_DECL);
988
989/**
990 * Release read access to a read/write semaphore.
991 *
992 * @returns iprt status code.
993 * @param hRWSem Handle to the read/write semaphore. It goes
994 * without saying that caller must own read
995 * privileges to the semaphore.
996 */
997RTDECL(int) RTSemRWReleaseRead(RTSEMRW hRWSem);
998
999/**
1000 * Request write access to a read/write semaphore, resume on interruption.
1001 *
1002 * @returns iprt status code.
1003 * @retval VINF_SUCCESS on success.
1004 * @retval VERR_DEADLOCK if the caller owned the read lock.
1005 * @retval VERR_INVALID_HANDLE if hRWSem is invalid.
1006 *
1007 * @param hRWSem Handle to the read/write semaphore.
1008 * @param cMillies The number of milliseconds to wait.
1009 */
1010RTDECL(int) RTSemRWRequestWrite(RTSEMRW hRWSem, RTMSINTERVAL cMillies);
1011
1012/**
1013 * Request write access to a read/write semaphore, return on interruption.
1014 *
1015 * @returns iprt status code.
1016 * @retval VINF_SUCCESS on success.
1017 * @retval VERR_INTERRUPT if the wait was interrupted.
1018 * @retval VERR_DEADLOCK if the caller owned the read lock.
1019 * @retval VERR_INVALID_HANDLE if hRWSem is invalid.
1020 *
1021 * @param hRWSem Handle to the read/write semaphore.
1022 * @param cMillies The number of milliseconds to wait.
1023 */
1024RTDECL(int) RTSemRWRequestWriteNoResume(RTSEMRW hRWSem, RTMSINTERVAL cMillies);
1025
1026/**
1027 * Debug version of RTSemRWRequestWrite that tracks the location.
1028 *
1029 * @returns IPRT status code, see RTSemRWRequestWrite.
1030 * @param hRWSem Handle to the read/write semaphore.
1031 * @param cMillies The number of milliseconds to wait.
1032 * @param uId Some kind of locking location ID. Typically a
1033 * return address up the stack. Optional (0).
1034 * @param pszFile The file where the lock is being acquired from.
1035 * Optional.
1036 * @param iLine The line number in that file. Optional (0).
1037 * @param pszFunction The function where the lock is being acquired
1038 * from. Optional.
1039 */
1040RTDECL(int) RTSemRWRequestWriteDebug(RTSEMRW hRWSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
1041
1042/**
1043 * Debug version of RTSemRWRequestWriteNoResume that tracks the location.
1044 *
1045 * @returns IPRT status code, see RTSemRWRequestWriteNoResume.
1046 * @param hRWSem Handle to the read/write semaphore.
1047 * @param cMillies The number of milliseconds to wait.
1048 * @param uId Some kind of locking location ID. Typically a
1049 * return address up the stack. Optional (0).
1050 * @param pszFile The file where the lock is being acquired from.
1051 * Optional.
1052 * @param iLine The line number in that file. Optional (0).
1053 * @param pszFunction The function where the lock is being acquired
1054 * from. Optional.
1055 */
1056RTDECL(int) RTSemRWRequestWriteNoResumeDebug(RTSEMRW hRWSem, RTMSINTERVAL cMillies, RTHCUINTPTR uId, RT_SRC_POS_DECL);
1057
1058/**
1059 * Request write access to a read/write semaphore, extended edition.
1060 *
1061 * @returns iprt status code.
1062 * @retval VINF_SUCCESS on success.
1063 * @retval VERR_INTERRUPTED if the wait was interrupted.
1064 * @retval VERR_TIMEOUT if the wait timed out.
1065 * @retval VERR_DEADLOCK if the caller owned the read lock. Do not depend on
1066 * this as it is implementation specific.
1067 * @retval VERR_INVALID_HANDLE if hRWSem is invalid.
1068 *
1069 * @param hRWSem Handle to the read/write semaphore.
1070 * @param fFlags Combination of the RTSEMWAIT_FLAGS_XXX.
1071 * @param uTimeout The timeout, ignored if
1072 * RTSEMWAIT_FLAGS_INDEFINITE is set in @a flags.
1073 * Whether this is absolute or relative,
1074 * milliseconds or nanoseconds depends on the @a
1075 * fFlags value. Do not pass RT_INDEFINITE_WAIT
1076 * here, use RTSEMWAIT_FLAGS_INDEFINITE instead.
1077 */
1078RTDECL(int) RTSemRWRequestWriteEx(RTSEMRW hRWSem, uint32_t fFlags, uint64_t uTimeout);
1079
1080/**
1081 * Debug version of RTSemRWRequestWriteEx that tracks the location.
1082 *
1083 * @returns IPRT status code, see RTSemRWRequestWriteEx.
1084 * @param hRWSem Handle to the read/write semaphore.
1085 * @param fFlags See RTSemRWRequestWriteEx.
1086 * @param uTimeout See RTSemRWRequestWriteEx.
1087 * @param uId Some kind of locking location ID. Typically a
1088 * return address up the stack. Optional (0).
1089 * @param pszFile The file where the lock is being acquired from.
1090 * Optional.
1091 * @param iLine The line number in that file. Optional (0).
1092 * @param pszFunction The function where the lock is being acquired
1093 * from. Optional.
1094 */
1095RTDECL(int) RTSemRWRequestWriteExDebug(RTSEMRW hRWSem, uint32_t fFlags, uint64_t uTimeout,
1096 RTHCUINTPTR uId, RT_SRC_POS_DECL);
1097
1098/**
1099 * Release write access to a read/write semaphore.
1100 *
1101 * @returns iprt status code.
1102 * @param hRWSem Handle to the read/write semaphore. Goes
1103 * without saying that caller must have write
1104 * access to the semaphore.
1105 */
1106RTDECL(int) RTSemRWReleaseWrite(RTSEMRW hRWSem);
1107
1108/**
1109 * Checks if the caller is the exclusive semaphore owner.
1110 *
1111 * @returns true / false accoringly.
1112 * @param hRWSem Handle to the read/write semaphore.
1113 */
1114RTDECL(bool) RTSemRWIsWriteOwner(RTSEMRW hRWSem);
1115
1116/**
1117 * Checks if the caller is one of the read owners of the semaphore.
1118 *
1119 * @note !CAUTION! This API doesn't work reliably if lock validation isn't
1120 * enabled. Meaning, the answer is not trustworhty unless
1121 * RT_LOCK_STRICT or RTSEMRW_STRICT was defined at build time. Also,
1122 * make sure you do not use RTSEMRW_FLAGS_NO_LOCK_VAL when creating
1123 * the semaphore. And finally, if you used a locking class, don't
1124 * disable deadlock detection by setting cMsMinDeadlock to
1125 * RT_INDEFINITE_WAIT.
1126 *
1127 * In short, only use this for assertions.
1128 *
1129 * @returns true if reader, false if not.
1130 * @param hRWSem Handle to the read/write semaphore.
1131 * @param fWannaHear What you'd like to hear when lock validation is
1132 * not available. (For avoiding asserting all over
1133 * the place.)
1134 */
1135RTDECL(bool) RTSemRWIsReadOwner(RTSEMRW hRWSem, bool fWannaHear);
1136
1137/**
1138 * Gets the write recursion count.
1139 *
1140 * @returns The write recursion count (0 if bad semaphore handle).
1141 * @param hRWSem Handle to the read/write semaphore.
1142 */
1143RTDECL(uint32_t) RTSemRWGetWriteRecursion(RTSEMRW hRWSem);
1144
1145/**
1146 * Gets the read recursion count of the current writer.
1147 *
1148 * @returns The read recursion count (0 if bad semaphore handle).
1149 * @param hRWSem Handle to the read/write semaphore.
1150 */
1151RTDECL(uint32_t) RTSemRWGetWriterReadRecursion(RTSEMRW hRWSem);
1152
1153/**
1154 * Gets the current number of reads.
1155 *
1156 * This includes all read recursions, so it might be higher than the number of
1157 * read owners. It does not include reads done by the current writer.
1158 *
1159 * @returns The read count (0 if bad semaphore handle).
1160 * @param hRWSem Handle to the read/write semaphore.
1161 */
1162RTDECL(uint32_t) RTSemRWGetReadCount(RTSEMRW hRWSem);
1163
1164/* Strict build: Remap the four request calls to the debug versions. */
1165#if defined(RT_STRICT) && !defined(RTSEMRW_WITHOUT_REMAPPING) && !defined(RT_WITH_MANGLING)
1166# ifdef ___iprt_asm_h
1167# define RTSemRWRequestRead(hRWSem, cMillies) RTSemRWRequestReadDebug((hRWSem), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
1168# define RTSemRWRequestReadNoResume(hRWSem, cMillies) RTSemRWRequestReadNoResumeDebug((hRWSem), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
1169# define RTSemRWRequestWrite(hRWSem, cMillies) RTSemRWRequestWriteDebug((hRWSem), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
1170# define RTSemRWRequestWriteNoResume(hRWSem, cMillies) RTSemRWRequestWriteNoResumeDebug((hRWSem), (cMillies), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
1171# define RTSemRWRequestWriteEx(hRWSem, fFlags, uTimeout) RTSemRWRequestWriteExDebug((hRWSem), (fFlags), (uTimeout), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
1172# else
1173# define RTSemRWRequestRead(hRWSem, cMillies) RTSemRWRequestReadDebug((hRWSem), (cMillies), 0, RT_SRC_POS)
1174# define RTSemRWRequestReadNoResume(hRWSem, cMillies) RTSemRWRequestReadNoResumeDebug((hRWSem), (cMillies), 0, RT_SRC_POS)
1175# define RTSemRWRequestWrite(hRWSem, cMillies) RTSemRWRequestWriteDebug((hRWSem), (cMillies), 0, RT_SRC_POS)
1176# define RTSemRWRequestWriteNoResume(hRWSem, cMillies) RTSemRWRequestWriteNoResumeDebug((hRWSem), (cMillies), 0, RT_SRC_POS)
1177# define RTSemRWRequestWriteEx(hRWSem, fFlags, uTimeout) RTSemRWRequestWriteExDebug((hRWSem), (fFlags), (uTimeout), 0, RT_SRC_POS)
1178# endif
1179#endif
1180
1181/* Strict lock order: Automatically classify locks by init location. */
1182#if defined(RT_LOCK_STRICT_ORDER) && defined(IN_RING3) && !defined(RTSEMRW_WITHOUT_REMAPPING) && !defined(RT_WITH_MANGLING)
1183# define RTSemRWCreate(phSemRW) \
1184 RTSemRWCreateEx((phSemRW), 0 /*fFlags*/, \
1185 RTLockValidatorClassForSrcPos(RT_SRC_POS, NULL), \
1186 RTLOCKVAL_SUB_CLASS_NONE, NULL)
1187#endif
1188
1189/** @} */
1190
1191
1192/** @defgroup grp_rt_sems_pingpong RTSemPingPong - Ping-Pong Construct
1193 *
1194 * Serialization of a two way communication.
1195 *
1196 * @{ */
1197
1198/**
1199 * Ping-pong speaker
1200 */
1201typedef enum RTPINGPONGSPEAKER
1202{
1203 /** Not initialized. */
1204 RTPINGPONGSPEAKER_UNINITIALIZE = 0,
1205 /** Ping is speaking, Pong is waiting. */
1206 RTPINGPONGSPEAKER_PING,
1207 /** Pong is signaled, Ping is waiting. */
1208 RTPINGPONGSPEAKER_PONG_SIGNALED,
1209 /** Pong is speaking, Ping is waiting. */
1210 RTPINGPONGSPEAKER_PONG,
1211 /** Ping is signaled, Pong is waiting. */
1212 RTPINGPONGSPEAKER_PING_SIGNALED,
1213 /** Hack to ensure that it's at least 32-bits wide. */
1214 RTPINGPONGSPEAKER_HACK = 0x7fffffff
1215} RTPINGPONGSPEAKER;
1216
1217/**
1218 * Ping-Pong construct.
1219 *
1220 * Two threads, one saying Ping and the other saying Pong. The construct
1221 * makes sure they don't speak out of turn and that they can wait and poll
1222 * on the conversation.
1223 */
1224typedef struct RTPINGPONG
1225{
1226 /** The semaphore the Ping thread waits on. */
1227 RTSEMEVENT Ping;
1228 /** The semaphore the Pong thread waits on. */
1229 RTSEMEVENT Pong;
1230 /** The current speaker. */
1231 volatile RTPINGPONGSPEAKER enmSpeaker;
1232#if HC_ARCH_BITS == 64
1233 /** Padding the structure to become a multiple of sizeof(RTHCPTR). */
1234 uint32_t u32Padding;
1235#endif
1236} RTPINGPONG;
1237/** Pointer to Ping-Pong construct. */
1238typedef RTPINGPONG *PRTPINGPONG;
1239
1240/**
1241 * Init a Ping-Pong construct.
1242 *
1243 * @returns iprt status code.
1244 * @param pPP Pointer to the ping-pong structure which needs initialization.
1245 */
1246RTDECL(int) RTSemPingPongInit(PRTPINGPONG pPP);
1247
1248/**
1249 * Deletes a Ping-Pong construct.
1250 *
1251 * @returns iprt status code.
1252 * @param pPP Pointer to the ping-pong structure which is to be destroyed.
1253 * (I.e. put into uninitialized state.)
1254 */
1255RTDECL(int) RTSemPingPongDelete(PRTPINGPONG pPP);
1256
1257/**
1258 * Signals the pong thread in a ping-pong construct. (I.e. sends ping.)
1259 * This is called by the ping thread.
1260 *
1261 * @returns iprt status code.
1262 * @param pPP Pointer to the ping-pong structure to ping.
1263 */
1264RTDECL(int) RTSemPing(PRTPINGPONG pPP);
1265
1266/**
1267 * Signals the ping thread in a ping-pong construct. (I.e. sends pong.)
1268 * This is called by the pong thread.
1269 *
1270 * @returns iprt status code.
1271 * @param pPP Pointer to the ping-pong structure to pong.
1272 */
1273RTDECL(int) RTSemPong(PRTPINGPONG pPP);
1274
1275/**
1276 * Wait function for the ping thread.
1277 *
1278 * @returns iprt status code.
1279 * Will not return VERR_INTERRUPTED.
1280 * @param pPP Pointer to the ping-pong structure to wait on.
1281 * @param cMillies Number of milliseconds to wait.
1282 */
1283RTDECL(int) RTSemPingWait(PRTPINGPONG pPP, RTMSINTERVAL cMillies);
1284
1285/**
1286 * Wait function for the pong thread.
1287 *
1288 * @returns iprt status code.
1289 * Will not return VERR_INTERRUPTED.
1290 * @param pPP Pointer to the ping-pong structure to wait on.
1291 * @param cMillies Number of milliseconds to wait.
1292 */
1293RTDECL(int) RTSemPongWait(PRTPINGPONG pPP, RTMSINTERVAL cMillies);
1294
1295
1296/**
1297 * Checks if the pong thread is speaking.
1298 *
1299 * @returns true / false.
1300 * @param pPP Pointer to the ping-pong structure.
1301 * @remark This is NOT the same as !RTSemPongIsSpeaker().
1302 */
1303DECLINLINE(bool) RTSemPingIsSpeaker(PRTPINGPONG pPP)
1304{
1305 RTPINGPONGSPEAKER enmSpeaker = pPP->enmSpeaker;
1306 return enmSpeaker == RTPINGPONGSPEAKER_PING;
1307}
1308
1309
1310/**
1311 * Checks if the pong thread is speaking.
1312 *
1313 * @returns true / false.
1314 * @param pPP Pointer to the ping-pong structure.
1315 * @remark This is NOT the same as !RTSemPingIsSpeaker().
1316 */
1317DECLINLINE(bool) RTSemPongIsSpeaker(PRTPINGPONG pPP)
1318{
1319 RTPINGPONGSPEAKER enmSpeaker = pPP->enmSpeaker;
1320 return enmSpeaker == RTPINGPONGSPEAKER_PONG;
1321}
1322
1323
1324/**
1325 * Checks whether the ping thread should wait.
1326 *
1327 * @returns true / false.
1328 * @param pPP Pointer to the ping-pong structure.
1329 * @remark This is NOT the same as !RTSemPongShouldWait().
1330 */
1331DECLINLINE(bool) RTSemPingShouldWait(PRTPINGPONG pPP)
1332{
1333 RTPINGPONGSPEAKER enmSpeaker = pPP->enmSpeaker;
1334 return enmSpeaker == RTPINGPONGSPEAKER_PONG
1335 || enmSpeaker == RTPINGPONGSPEAKER_PONG_SIGNALED
1336 || enmSpeaker == RTPINGPONGSPEAKER_PING_SIGNALED;
1337}
1338
1339
1340/**
1341 * Checks whether the pong thread should wait.
1342 *
1343 * @returns true / false.
1344 * @param pPP Pointer to the ping-pong structure.
1345 * @remark This is NOT the same as !RTSemPingShouldWait().
1346 */
1347DECLINLINE(bool) RTSemPongShouldWait(PRTPINGPONG pPP)
1348{
1349 RTPINGPONGSPEAKER enmSpeaker = pPP->enmSpeaker;
1350 return enmSpeaker == RTPINGPONGSPEAKER_PING
1351 || enmSpeaker == RTPINGPONGSPEAKER_PING_SIGNALED
1352 || enmSpeaker == RTPINGPONGSPEAKER_PONG_SIGNALED;
1353}
1354
1355/** @} */
1356
1357
1358/** @defgroup grp_rt_sems_xroads RTSemXRoads - Crossroads
1359 *
1360 * The crossroads semaphore is intended to prevent two classes of incompatible
1361 * events from occurring simultaneously, like south/north bound traffic and
1362 * west/east bound traffic at a 4-way junction.
1363 *
1364 * @remarks In order to simplify the implementation, the current flow is always
1365 * given priority. So, it won't work at all well when busy!
1366 *
1367 * @remarks "XRoads" is used as a name because it is briefer than "crossroads"
1368 * and it slightly stresses that is a 4 way crossing to the users of
1369 * American English.
1370 * @{
1371 */
1372
1373/**
1374 * Creates a crossroads semaphore.
1375 *
1376 * @returns IPRT status code.
1377 *
1378 * @param phXRoads Where to return the handle to the newly created
1379 * crossroads semaphore.
1380 */
1381RTDECL(int) RTSemXRoadsCreate(PRTSEMXROADS phXRoads);
1382
1383/**
1384 * Destroys a crossroads semaphore.
1385 *
1386 * @returns IPRT status code.
1387 *
1388 * @param hXRoads Handle to the crossroads semaphore that is to be
1389 * destroyed. NIL_RTSEMXROADS is quitetly ignored
1390 * (VINF_SUCCESS).
1391 */
1392RTDECL(int) RTSemXRoadsDestroy(RTSEMXROADS hXRoads);
1393
1394/**
1395 * Enter the crossroads from the south or north.
1396 *
1397 * (Coupled with RTSemXRoadsNSLeave.)
1398 *
1399 * @returns IPRT status code.
1400 * @param hXRoads Handle to the crossroads semaphore.
1401 */
1402RTDECL(int) RTSemXRoadsNSEnter(RTSEMXROADS hXRoads);
1403
1404/**
1405 * Leave the crossroads to the north or south.
1406 *
1407 * (Coupled with RTSemXRoadsNSEnter.)
1408 *
1409 * @returns IPRT status code.
1410 * @param hXRoads Handle to the crossroads semaphore.
1411 */
1412RTDECL(int) RTSemXRoadsNSLeave(RTSEMXROADS hXRoads);
1413
1414/**
1415 * Leave the crossroads from the east or west.
1416 *
1417 * (Coupled with RTSemXRoadsEWLeave.)
1418 *
1419 * @returns IPRT status code.
1420 * @param hXRoads Handle to the crossroads semaphore.
1421 */
1422RTDECL(int) RTSemXRoadsEWEnter(RTSEMXROADS hXRoads);
1423
1424/**
1425 * Leave the crossroads to the west or east.
1426 *
1427 * (Coupled with RTSemXRoadsEWEnter.)
1428 *
1429 * @returns IPRT status code.
1430 * @param hXRoads Handle to the crossroads semaphore.
1431 */
1432RTDECL(int) RTSemXRoadsEWLeave(RTSEMXROADS hXRoads);
1433
1434/** @} */
1435
1436/** @} */
1437
1438RT_C_DECLS_END
1439
1440#endif
1441
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