VirtualBox

source: vbox/trunk/include/iprt/critsect.h@ 73768

Last change on this file since 73768 was 69105, checked in by vboxsync, 7 years ago

include/iprt/: (C) year
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 27.9 KB
Line 
1/** @file
2 * IPRT - Critical Sections.
3 */
4
5/*
6 * Copyright (C) 2006-2017 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_critsect_h
27#define ___iprt_critsect_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31#include <iprt/assert.h>
32#if defined(IN_RING3) || defined(IN_RING0)
33# include <iprt/thread.h>
34#endif
35#ifdef RT_LOCK_STRICT_ORDER
36# include <iprt/lockvalidator.h>
37#endif
38
39RT_C_DECLS_BEGIN
40
41/** @defgroup grp_rt_critsect RTCritSect - Critical Sections
42 *
43 * "Critical section" synchronization primitives can be used to
44 * protect a section of code or data to which access must be exclusive;
45 * only one thread can hold access to a critical section at one time.
46 *
47 * A critical section is a fast recursive write lock; if the critical
48 * section is not acquired, then entering it is fast (requires no system
49 * call). IPRT uses the Windows terminology here; on other platform, this
50 * might be called a "futex" or a "fast mutex". As opposed to IPRT
51 * "fast mutexes" (see @ref grp_rt_sems_fast_mutex ), critical sections
52 * are recursive.
53 *
54 * Use RTCritSectInit to initialize a critical section; use RTCritSectEnter
55 * and RTCritSectLeave to acquire and release access.
56 *
57 * For an overview of all types of synchronization primitives provided
58 * by IPRT (event, mutex/fast mutex/read-write mutex semaphores), see
59 * @ref grp_rt_sems .
60 *
61 * @ingroup grp_rt
62 * @{
63 */
64
65/**
66 * Critical section.
67 */
68typedef struct RTCRITSECT
69{
70 /** Magic used to validate the section state.
71 * RTCRITSECT_MAGIC is the value of an initialized & operational section. */
72 volatile uint32_t u32Magic;
73 /** Number of lockers.
74 * -1 if the section is free. */
75 volatile int32_t cLockers;
76 /** The owner thread. */
77 volatile RTNATIVETHREAD NativeThreadOwner;
78 /** Number of nested enter operations performed.
79 * Greater or equal to 1 if owned, 0 when free.
80 */
81 volatile int32_t cNestings;
82 /** Section flags - the RTCRITSECT_FLAGS_* \#defines. */
83 uint32_t fFlags;
84 /** The semaphore to block on. */
85 RTSEMEVENT EventSem;
86 /** Lock validator record. Only used in strict builds. */
87 R3R0PTRTYPE(PRTLOCKVALRECEXCL) pValidatorRec;
88 /** Alignmnet padding. */
89 RTHCPTR Alignment;
90} RTCRITSECT;
91AssertCompileSize(RTCRITSECT, HC_ARCH_BITS == 32 ? 32 : 48);
92
93/** RTCRITSECT::u32Magic value. (Hiromi Uehara) */
94#define RTCRITSECT_MAGIC UINT32_C(0x19790326)
95
96/** @name RTCritSectInitEx flags / RTCRITSECT::fFlags
97 * @{ */
98/** If set, nesting(/recursion) is not allowed. */
99#define RTCRITSECT_FLAGS_NO_NESTING UINT32_C(0x00000001)
100/** Disables lock validation. */
101#define RTCRITSECT_FLAGS_NO_LOCK_VAL UINT32_C(0x00000002)
102/** Bootstrap hack for use with certain memory allocator locks only! */
103#define RTCRITSECT_FLAGS_BOOTSTRAP_HACK UINT32_C(0x00000004)
104/** If set, the critical section becomes a dummy that doesn't serialize any
105 * threads. This flag can only be set at creation time.
106 *
107 * The intended use is avoiding lots of conditional code where some component
108 * might or might not require entering a critical section before access. */
109#define RTCRITSECT_FLAGS_NOP UINT32_C(0x00000008)
110/** Indicates that this is a ring-0 critical section. */
111#define RTCRITSECT_FLAGS_RING0 UINT32_C(0x00000010)
112/** @} */
113
114
115#if defined(IN_RING3) || defined(IN_RING0)
116
117/**
118 * Initialize a critical section.
119 */
120RTDECL(int) RTCritSectInit(PRTCRITSECT pCritSect);
121
122/**
123 * Initialize a critical section.
124 *
125 * @returns iprt status code.
126 * @param pCritSect Pointer to the critical section structure.
127 * @param fFlags Flags, any combination of the RTCRITSECT_FLAGS
128 * \#defines.
129 * @param hClass The class (no reference consumed). If NIL, no lock
130 * order validation will be performed on this lock.
131 * @param uSubClass The sub-class. This is used to define lock order
132 * within a class. RTLOCKVAL_SUB_CLASS_NONE is the
133 * recommended value here.
134 * @param pszNameFmt Name format string for the lock validator, optional
135 * (NULL). Max length is 32 bytes.
136 * @param ... Format string arguments.
137 */
138RTDECL(int) RTCritSectInitEx(PRTCRITSECT pCritSect, uint32_t fFlags, RTLOCKVALCLASS hClass, uint32_t uSubClass,
139 const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(5, 6);
140
141/**
142 * Changes the lock validator sub-class of the critical section.
143 *
144 * It is recommended to try make sure that nobody is using this critical section
145 * while changing the value.
146 *
147 * @returns The old sub-class. RTLOCKVAL_SUB_CLASS_INVALID is returns if the
148 * lock validator isn't compiled in or either of the parameters are
149 * invalid.
150 * @param pCritSect The critical section.
151 * @param uSubClass The new sub-class value.
152 */
153RTDECL(uint32_t) RTCritSectSetSubClass(PRTCRITSECT pCritSect, uint32_t uSubClass);
154
155/**
156 * Enter a critical section.
157 *
158 * @returns VINF_SUCCESS on success.
159 * @returns VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
160 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
161 * during the operation.
162 * @param pCritSect The critical section.
163 */
164RTDECL(int) RTCritSectEnter(PRTCRITSECT pCritSect);
165
166/**
167 * Enter a critical section.
168 *
169 * @returns IPRT status code.
170 * @retval VINF_SUCCESS on success.
171 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
172 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
173 * during the operation.
174 *
175 * @param pCritSect The critical section.
176 * @param uId Where we're entering the section.
177 * @param SRC_POS The source position where call is being made from.
178 * Use RT_SRC_POS when possible. Optional.
179 */
180RTDECL(int) RTCritSectEnterDebug(PRTCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL);
181
182/**
183 * Try enter a critical section.
184 *
185 * @retval VINF_SUCCESS on success.
186 * @retval VERR_SEM_BUSY if the critsect was owned.
187 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
188 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
189 * during the operation.
190 *
191 * @param pCritSect The critical section.
192 */
193RTDECL(int) RTCritSectTryEnter(PRTCRITSECT pCritSect);
194
195/**
196 * Try enter a critical section.
197 *
198 * @retval VINF_SUCCESS on success.
199 * @retval VERR_SEM_BUSY if the critsect was owned.
200 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
201 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
202 * during the operation.
203 *
204 * @param pCritSect The critical section.
205 * @param uId Where we're entering the section.
206 * @param SRC_POS The source position where call is being made from.
207 * Use RT_SRC_POS when possible. Optional.
208 */
209RTDECL(int) RTCritSectTryEnterDebug(PRTCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL);
210
211# ifdef IN_RING3 /* Crazy APIs: ring-3 only. */
212
213/**
214 * Enter multiple critical sections.
215 *
216 * This function will enter ALL the specified critical sections before returning.
217 *
218 * @returns VINF_SUCCESS on success.
219 * @returns VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
220 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
221 * during the operation.
222 * @param cCritSects Number of critical sections in the array.
223 * @param papCritSects Array of critical section pointers.
224 *
225 * @remark Please note that this function will not necessarily come out favourable in a
226 * fight with other threads which are using the normal RTCritSectEnter() function.
227 * Therefore, avoid having to enter multiple critical sections!
228 */
229RTDECL(int) RTCritSectEnterMultiple(size_t cCritSects, PRTCRITSECT *papCritSects);
230
231/**
232 * Enter multiple critical sections.
233 *
234 * This function will enter ALL the specified critical sections before returning.
235 *
236 * @returns VINF_SUCCESS on success.
237 * @returns VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
238 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
239 * during the operation.
240 *
241 * @param cCritSects Number of critical sections in the array.
242 * @param papCritSects Array of critical section pointers.
243 * @param uId Where we're entering the section.
244 * @param SRC_POS The source position where call is being made from.
245 * Use RT_SRC_POS when possible. Optional.
246 *
247 * @remark See RTCritSectEnterMultiple().
248 */
249RTDECL(int) RTCritSectEnterMultipleDebug(size_t cCritSects, PRTCRITSECT *papCritSects, RTUINTPTR uId, RT_SRC_POS_DECL);
250
251# endif /* IN_RING3 */
252
253/**
254 * Leave a critical section.
255 *
256 * @returns VINF_SUCCESS.
257 * @param pCritSect The critical section.
258 */
259RTDECL(int) RTCritSectLeave(PRTCRITSECT pCritSect);
260
261/**
262 * Leave multiple critical sections.
263 *
264 * @returns VINF_SUCCESS.
265 * @param cCritSects Number of critical sections in the array.
266 * @param papCritSects Array of critical section pointers.
267 */
268RTDECL(int) RTCritSectLeaveMultiple(size_t cCritSects, PRTCRITSECT *papCritSects);
269
270/**
271 * Deletes a critical section.
272 *
273 * @returns VINF_SUCCESS.
274 * @param pCritSect The critical section.
275 */
276RTDECL(int) RTCritSectDelete(PRTCRITSECT pCritSect);
277
278/**
279 * Checks the caller is the owner of the critical section.
280 *
281 * @returns true if owner.
282 * @returns false if not owner.
283 * @param pCritSect The critical section.
284 */
285DECLINLINE(bool) RTCritSectIsOwner(PCRTCRITSECT pCritSect)
286{
287 return pCritSect->NativeThreadOwner == RTThreadNativeSelf();
288}
289
290#endif /* IN_RING3 || IN_RING0 */
291
292/**
293 * Checks the section is owned by anyone.
294 *
295 * @returns true if owned.
296 * @returns false if not owned.
297 * @param pCritSect The critical section.
298 */
299DECLINLINE(bool) RTCritSectIsOwned(PCRTCRITSECT pCritSect)
300{
301 return pCritSect->NativeThreadOwner != NIL_RTNATIVETHREAD;
302}
303
304/**
305 * Gets the thread id of the critical section owner.
306 *
307 * @returns Thread id of the owner thread if owned.
308 * @returns NIL_RTNATIVETHREAD is not owned.
309 * @param pCritSect The critical section.
310 */
311DECLINLINE(RTNATIVETHREAD) RTCritSectGetOwner(PCRTCRITSECT pCritSect)
312{
313 return pCritSect->NativeThreadOwner;
314}
315
316/**
317 * Checks if a critical section is initialized or not.
318 *
319 * @returns true if initialized.
320 * @returns false if not initialized.
321 * @param pCritSect The critical section.
322 */
323DECLINLINE(bool) RTCritSectIsInitialized(PCRTCRITSECT pCritSect)
324{
325 return pCritSect->u32Magic == RTCRITSECT_MAGIC;
326}
327
328/**
329 * Gets the recursion depth.
330 *
331 * @returns The recursion depth.
332 * @param pCritSect The Critical section
333 */
334DECLINLINE(uint32_t) RTCritSectGetRecursion(PCRTCRITSECT pCritSect)
335{
336 return pCritSect->cNestings;
337}
338
339/**
340 * Gets the waiter count
341 *
342 * @returns The waiter count
343 * @param pCritSect The Critical section
344 */
345DECLINLINE(int32_t) RTCritSectGetWaiters(PCRTCRITSECT pCritSect)
346{
347 return pCritSect->cLockers;
348}
349
350/* Lock strict build: Remap the three enter calls to the debug versions. */
351#if defined(RT_LOCK_STRICT) && !defined(RTCRITSECT_WITHOUT_REMAPPING) && !defined(RT_WITH_MANGLING)
352# ifdef ___iprt_asm_h
353# define RTCritSectEnter(pCritSect) RTCritSectEnterDebug(pCritSect, (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
354# define RTCritSectTryEnter(pCritSect) RTCritSectTryEnterDebug(pCritSect, (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
355# define RTCritSectEnterMultiple(cCritSects, pCritSect) RTCritSectEnterMultipleDebug((cCritSects), (pCritSect), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
356# else
357# define RTCritSectEnter(pCritSect) RTCritSectEnterDebug(pCritSect, 0, RT_SRC_POS)
358# define RTCritSectTryEnter(pCritSect) RTCritSectTryEnterDebug(pCritSect, 0, RT_SRC_POS)
359# define RTCritSectEnterMultiple(cCritSects, pCritSect) RTCritSectEnterMultipleDebug((cCritSects), (pCritSect), 0, RT_SRC_POS)
360# endif
361#endif
362
363/* Strict lock order: Automatically classify locks by init location. */
364#if defined(RT_LOCK_STRICT_ORDER) && defined(IN_RING3) && !defined(RTCRITSECT_WITHOUT_REMAPPING) && !defined(RT_WITH_MANGLING)
365# define RTCritSectInit(pCritSect) \
366 RTCritSectInitEx((pCritSect), 0 /*fFlags*/, \
367 RTLockValidatorClassForSrcPos(RT_SRC_POS, NULL), \
368 RTLOCKVAL_SUB_CLASS_NONE, NULL)
369#endif
370
371/** @} */
372
373
374
375/** @defgroup grp_rt_critsectrw RTCritSectRw - Read/Write Critical Sections
376 * @ingroup grp_rt
377 * @{
378 */
379
380/**
381 * Read/write critical section.
382 */
383typedef struct RTCRITSECTRW
384{
385 /** Magic used to validate the section state.
386 * RTCRITSECTRW_MAGIC is the value of an initialized & operational section. */
387 volatile uint32_t u32Magic;
388
389 /** Indicates whether hEvtRead needs resetting. */
390 bool volatile fNeedReset;
391 /** Explicit alignment padding. */
392 bool volatile afPadding[1];
393 /** Section flags - the RTCRITSECT_FLAGS_* \#defines. */
394 uint16_t fFlags;
395
396 /** The state variable.
397 * All accesses are atomic and it bits are defined like this:
398 * Bits 0..14 - cReads.
399 * Bit 15 - Unused.
400 * Bits 16..31 - cWrites. - doesn't make sense here
401 * Bit 31 - fDirection; 0=Read, 1=Write.
402 * Bits 32..46 - cWaitingReads
403 * Bit 47 - Unused.
404 * Bits 48..62 - cWaitingWrites
405 * Bit 63 - Unused.
406 */
407 uint64_t volatile u64State;
408 /** The write owner. */
409 RTNATIVETHREAD volatile hNativeWriter;
410 /** The number of reads made by the current writer. */
411 uint32_t volatile cWriterReads;
412 /** The number of recursions made by the current writer. (The initial grabbing
413 * of the lock counts as the first one.) */
414 uint32_t volatile cWriteRecursions;
415
416 /** What the writer threads are blocking on. */
417 RTSEMEVENT hEvtWrite;
418 /** What the read threads are blocking on when waiting for the writer to
419 * finish. */
420 RTSEMEVENTMULTI hEvtRead;
421
422 /** The validator record for the writer. */
423 R3R0PTRTYPE(PRTLOCKVALRECEXCL) pValidatorWrite;
424 /** The validator record for the readers. */
425 R3R0PTRTYPE(PRTLOCKVALRECSHRD) pValidatorRead;
426#if HC_ARCH_BITS == 32
427 /** Size padding. */
428 RTHCPTR HCPtrPadding;
429#endif
430} RTCRITSECTRW;
431AssertCompileSize(RTCRITSECTRW, HC_ARCH_BITS == 32 ? 48 : 64);
432
433/** RTCRITSECTRW::u32Magic value. (Eric Allan Dolphy, Jr.) */
434#define RTCRITSECTRW_MAGIC UINT32_C(0x19280620)
435/** RTCRITSECTRW::u32Magic dead value. */
436#define RTCRITSECTRW_MAGIC_DEAD UINT32_C(0x19640629)
437
438/** @name RTCRITSECTRW::u64State values.
439 * @note Using RTCSRW instead of RTCRITSECTRW to save space.
440 * @{ */
441#define RTCSRW_CNT_BITS 15
442#define RTCSRW_CNT_MASK UINT64_C(0x00007fff)
443
444#define RTCSRW_CNT_RD_SHIFT 0
445#define RTCSRW_CNT_RD_MASK (RTCSRW_CNT_MASK << RTCSRW_CNT_RD_SHIFT)
446#define RTCSRW_CNT_WR_SHIFT 16
447#define RTCSRW_CNT_WR_MASK (RTCSRW_CNT_MASK << RTCSRW_CNT_WR_SHIFT)
448
449#define RTCSRW_DIR_SHIFT 31
450#define RTCSRW_DIR_MASK RT_BIT_64(RTCSRW_DIR_SHIFT)
451#define RTCSRW_DIR_READ UINT64_C(0)
452#define RTCSRW_DIR_WRITE UINT64_C(1)
453
454#define RTCSRW_WAIT_CNT_RD_SHIFT 32
455#define RTCSRW_WAIT_CNT_RD_MASK (RTCSRW_CNT_MASK << RTCSRW_WAIT_CNT_RD_SHIFT)
456/* #define RTCSRW_WAIT_CNT_WR_SHIFT 48 */
457/* #define RTCSRW_WAIT_CNT_WR_MASK (RTCSRW_CNT_MASK << RTCSRW_WAIT_CNT_WR_SHIFT) */
458/** @} */
459
460#if defined(IN_RING3) || defined(IN_RING0)
461
462/**
463 * Initialize a critical section.
464 */
465RTDECL(int) RTCritSectRwInit(PRTCRITSECTRW pThis);
466
467/**
468 * Initialize a critical section.
469 *
470 * @returns IPRT status code.
471 * @param pThis Pointer to the read/write critical section.
472 * @param fFlags Flags, any combination of the RTCRITSECT_FLAGS
473 * \#defines.
474 * @param hClass The class (no reference consumed). If NIL, no lock
475 * order validation will be performed on this lock.
476 * @param uSubClass The sub-class. This is used to define lock order
477 * within a class. RTLOCKVAL_SUB_CLASS_NONE is the
478 * recommended value here.
479 * @param pszNameFmt Name format string for the lock validator, optional
480 * (NULL). Max length is 32 bytes.
481 * @param ... Format string arguments.
482 */
483RTDECL(int) RTCritSectRwInitEx(PRTCRITSECTRW pThis, uint32_t fFlags, RTLOCKVALCLASS hClass, uint32_t uSubClass,
484 const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(5, 6);
485
486/**
487 * Changes the lock validator sub-class of the critical section.
488 *
489 * It is recommended to try make sure that nobody is using this critical section
490 * while changing the value.
491 *
492 * @returns The old sub-class. RTLOCKVAL_SUB_CLASS_INVALID is returns if the
493 * lock validator isn't compiled in or either of the parameters are
494 * invalid.
495 * @param pThis Pointer to the read/write critical section.
496 * @param uSubClass The new sub-class value.
497 */
498RTDECL(uint32_t) RTCritSectRwSetSubClass(PRTCRITSECTRW pThis, uint32_t uSubClass);
499
500
501/**
502 * Enter a critical section with shared (read) access.
503 *
504 * @returns IPRT status code.
505 * @retval VINF_SUCCESS on success.
506 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
507 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
508 * during the operation.
509 * @param pThis Pointer to the read/write critical section.
510 */
511RTDECL(int) RTCritSectRwEnterShared(PRTCRITSECTRW pThis);
512
513/**
514 * Enter a critical section with shared (read) access.
515 *
516 * @returns IPRT status code.
517 * @retval VINF_SUCCESS on success.
518 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
519 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
520 * during the operation.
521 *
522 * @param pThis Pointer to the read/write critical section.
523 * @param uId Where we're entering the section.
524 * @param SRC_POS The source position where call is being made from.
525 * Use RT_SRC_POS when possible. Optional.
526 */
527RTDECL(int) RTCritSectRwEnterSharedDebug(PRTCRITSECTRW pThis, RTHCUINTPTR uId, RT_SRC_POS_DECL);
528
529/**
530 * Try enter a critical section with shared (read) access.
531 *
532 * @returns IPRT status code.
533 * @retval VINF_SUCCESS on success.
534 * @retval VERR_SEM_BUSY if the critsect was owned.
535 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
536 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
537 * during the operation.
538 *
539 * @param pThis Pointer to the read/write critical section.
540 */
541RTDECL(int) RTCritSectRwTryEnterShared(PRTCRITSECTRW pThis);
542
543/**
544 * Try enter a critical section with shared (read) access.
545 *
546 * @returns IPRT status code.
547 * @retval VINF_SUCCESS on success.
548 * @retval VERR_SEM_BUSY if the critsect was owned.
549 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
550 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
551 * during the operation.
552 *
553 * @param pThis Pointer to the read/write critical section.
554 * @param uId Where we're entering the section.
555 * @param SRC_POS The source position where call is being made from.
556 * Use RT_SRC_POS when possible. Optional.
557 */
558RTDECL(int) RTCritSectRwTryEnterSharedDebug(PRTCRITSECTRW pThis, RTHCUINTPTR uId, RT_SRC_POS_DECL);
559
560/**
561 * Leave a critical section held with shared access.
562 *
563 * @returns IPRT status code.
564 * @param pThis Pointer to the read/write critical section.
565 */
566RTDECL(int) RTCritSectRwLeaveShared(PRTCRITSECTRW pThis);
567
568
569/**
570 * Enter a critical section with exclusive (write) access.
571 *
572 * @returns IPRT status code.
573 * @retval VINF_SUCCESS on success.
574 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
575 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
576 * during the operation.
577 * @param pThis Pointer to the read/write critical section.
578 */
579RTDECL(int) RTCritSectRwEnterExcl(PRTCRITSECTRW pThis);
580
581/**
582 * Enter a critical section with exclusive (write) access.
583 *
584 * @retval VINF_SUCCESS on success.
585 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
586 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
587 * during the operation.
588 *
589 * @param pThis Pointer to the read/write critical section.
590 * @param uId Where we're entering the section.
591 * @param SRC_POS The source position where call is being made from.
592 * Use RT_SRC_POS when possible. Optional.
593 */
594RTDECL(int) RTCritSectRwEnterExclDebug(PRTCRITSECTRW pThis, RTHCUINTPTR uId, RT_SRC_POS_DECL);
595
596/**
597 * Try enter a critical section with exclusive (write) access.
598 *
599 * @returns IPRT status code.
600 * @retval VINF_SUCCESS on success.
601 * @retval VERR_SEM_BUSY if the critsect was owned.
602 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
603 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
604 * during the operation.
605 *
606 * @param pThis Pointer to the read/write critical section.
607 */
608RTDECL(int) RTCritSectRwTryEnterExcl(PRTCRITSECTRW pThis);
609
610/**
611 * Try enter a critical section with exclusive (write) access.
612 *
613 * @returns IPRT status code.
614 * @retval VINF_SUCCESS on success.
615 * @retval VERR_SEM_BUSY if the critsect was owned.
616 * @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
617 * @retval VERR_SEM_DESTROYED if the critical section is delete before or
618 * during the operation.
619 *
620 * @param pThis Pointer to the read/write critical section.
621 * @param uId Where we're entering the section.
622 * @param SRC_POS The source position where call is being made from.
623 * Use RT_SRC_POS when possible. Optional.
624 */
625RTDECL(int) RTCritSectRwTryEnterExclDebug(PRTCRITSECTRW pThis, RTHCUINTPTR uId, RT_SRC_POS_DECL);
626
627/**
628 * Leave a critical section held exclusively.
629 *
630 * @returns IPRT status code; VINF_SUCCESS, VERR_NOT_OWNER, VERR_SEM_DESTROYED,
631 * or VERR_WRONG_ORDER.
632 * @param pThis Pointer to the read/write critical section.
633 */
634RTDECL(int) RTCritSectRwLeaveExcl(PRTCRITSECTRW pThis);
635
636
637/**
638 * Deletes a critical section.
639 *
640 * @returns VINF_SUCCESS.
641 * @param pThis Pointer to the read/write critical section.
642 */
643RTDECL(int) RTCritSectRwDelete(PRTCRITSECTRW pThis);
644
645/**
646 * Checks the caller is the exclusive (write) owner of the critical section.
647 *
648 * @retval true if owner.
649 * @retval false if not owner.
650 * @param pThis Pointer to the read/write critical section.
651 */
652RTDECL(bool) RTCritSectRwIsWriteOwner(PRTCRITSECTRW pThis);
653
654/**
655 * Checks if the caller is one of the read owners of the critical section.
656 *
657 * @note !CAUTION! This API doesn't work reliably if lock validation isn't
658 * enabled. Meaning, the answer is not trustworhty unless
659 * RT_LOCK_STRICT or RTCRITSECTRW_STRICT was defined at build time.
660 * Also, make sure you do not use RTCRITSECTRW_FLAGS_NO_LOCK_VAL when
661 * creating the semaphore. And finally, if you used a locking class,
662 * don't disable deadlock detection by setting cMsMinDeadlock to
663 * RT_INDEFINITE_WAIT.
664 *
665 * In short, only use this for assertions.
666 *
667 * @returns @c true if reader, @c false if not.
668 * @param pThis Pointer to the read/write critical section.
669 * @param fWannaHear What you'd like to hear when lock validation is not
670 * available. (For avoiding asserting all over the
671 * place.)
672 */
673RTDECL(bool) RTCritSectRwIsReadOwner(PRTCRITSECTRW pThis, bool fWannaHear);
674
675/**
676 * Gets the write recursion count.
677 *
678 * @returns The write recursion count (0 if bad critsect).
679 * @param pThis Pointer to the read/write critical section.
680 */
681RTDECL(uint32_t) RTCritSectRwGetWriteRecursion(PRTCRITSECTRW pThis);
682
683/**
684 * Gets the read recursion count of the current writer.
685 *
686 * @returns The read recursion count (0 if bad critsect).
687 * @param pThis Pointer to the read/write critical section.
688 */
689RTDECL(uint32_t) RTCritSectRwGetWriterReadRecursion(PRTCRITSECTRW pThis);
690
691/**
692 * Gets the current number of reads.
693 *
694 * This includes all read recursions, so it might be higher than the number of
695 * read owners. It does not include reads done by the current writer.
696 *
697 * @returns The read count (0 if bad critsect).
698 * @param pThis Pointer to the read/write critical section.
699 */
700RTDECL(uint32_t) RTCritSectRwGetReadCount(PRTCRITSECTRW pThis);
701
702#endif /* IN_RING3 || IN_RING0 */
703
704/**
705 * Checks if a critical section is initialized or not.
706 *
707 * @retval true if initialized.
708 * @retval false if not initialized.
709 * @param pThis Pointer to the read/write critical section.
710 */
711DECLINLINE(bool) RTCritSectRwIsInitialized(PCRTCRITSECTRW pThis)
712{
713 return pThis->u32Magic == RTCRITSECTRW_MAGIC;
714}
715
716/* Lock strict build: Remap the three enter calls to the debug versions. */
717#if defined(RT_LOCK_STRICT) && !defined(RTCRITSECTRW_WITHOUT_REMAPPING) && !defined(RT_WITH_MANGLING)
718# ifdef ___iprt_asm_h
719# define RTCritSectRwEnterExcl(pThis) RTCritSectRwEnterExclDebug(pThis, (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
720# define RTCritSectRwTryEnterExcl(pThis) RTCritSectRwTryEnterExclDebug(pThis, (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
721# define RTCritSectRwEnterShared(pThis) RTCritSectRwEnterSharedDebug(pThis, (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
722# define RTCritSectRwTryEnterShared(pThis) RTCritSectRwTryEnterSharedDebug(pThis, (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
723# else
724# define RTCritSectRwEnterExcl(pThis) RTCritSectRwEnterExclDebug(pThis, 0, RT_SRC_POS)
725# define RTCritSectRwTryEnterExcl(pThis) RTCritSectRwTryEnterExclDebug(pThis, 0, RT_SRC_POS)
726# define RTCritSectRwEnterShared(pThis) RTCritSectRwEnterSharedDebug(pThis, 0, RT_SRC_POS)
727# define RTCritSectRwTryEnterShared(pThis) RTCritSectRwTryEnterSharedDebug(pThis, 0, RT_SRC_POS)
728# endif
729#endif
730
731/* Strict lock order: Automatically classify locks by init location. */
732#if defined(RT_LOCK_STRICT_ORDER) && defined(IN_RING3) && !defined(RTCRITSECTRW_WITHOUT_REMAPPING) && !defined(RT_WITH_MANGLING)
733# define RTCritSectRwInit(a_pThis) \
734 RTCritSectRwInitEx((a_pThis), 0 /*fFlags*/, \
735 RTLockValidatorClassForSrcPos(RT_SRC_POS, NULL), \
736 RTLOCKVAL_SUB_CLASS_NONE, NULL)
737#endif
738
739/** @} */
740
741RT_C_DECLS_END
742
743#endif
744
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use