critsect.h@ 58389

Last change on this file since 58389 was 57978, checked in by vboxsync, 9 years ago
IPRT: Doxygen warning fixes (last ones, hopefully).
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-2015 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
39	RT_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	*/
68	typedef 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;
91	AssertCompileSize(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	*/
120	RTDECL(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	*/
138	RTDECL(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	*/
153	RTDECL(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	*/
164	RTDECL(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	*/
180	RTDECL(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	*/
193	RTDECL(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	*/
209	RTDECL(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	*/
229	RTDECL(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	*/
249	RTDECL(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	*/
259	RTDECL(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	*/
268	RTDECL(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	*/
276	RTDECL(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	*/
285	DECLINLINE(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	*/
299	DECLINLINE(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	*/
311	DECLINLINE(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	*/
323	DECLINLINE(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	*/
334	DECLINLINE(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	*/
345	DECLINLINE(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	*/
383	typedef 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;
431	AssertCompileSize(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	*/
465	RTDECL(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	*/
483	RTDECL(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	*/
498	RTDECL(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	*/
511	RTDECL(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	*/
527	RTDECL(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	*/
541	RTDECL(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	*/
558	RTDECL(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	*/
566	RTDECL(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	*/
579	RTDECL(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	*/
594	RTDECL(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	*/
608	RTDECL(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	*/
625	RTDECL(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	*/
634	RTDECL(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	*/
643	RTDECL(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	*/
652	RTDECL(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	*/
673	RTDECL(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	*/
681	RTDECL(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	*/
689	RTDECL(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	*/
700	RTDECL(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	*/
711	DECLINLINE(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
741	RT_C_DECLS_END
742
743	#endif
744

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

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

Download in other formats: