VirtualBox

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

Last change on this file since 86716 was 82968, checked in by vboxsync, 5 years ago

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