critsect.h@ 106061

Last change on this file since 106061 was 106061, checked in by vboxsync, 2 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 29.4 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: