lockvalidator.h@ 62021

Last change on this file since 62021 was 57926, checked in by vboxsync, 9 years ago
IPRT: Doxygen clenaups (mostly).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 49.1 KB

Line
1	/** @file
2	* IPRT - Lock Validator.
3	*/
4
5	/*
6	* Copyright (C) 2009-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_lockvalidator_h
27	#define ___iprt_lockvalidator_h
28
29	#include <iprt/cdefs.h>
30	#include <iprt/types.h>
31	#include <iprt/assert.h>
32	#include <iprt/thread.h>
33	#include <iprt/stdarg.h>
34
35
36	/** @defgroup grp_rtlockval RTLockValidator - Lock Validator
37	* @ingroup grp_rt
38	* @{
39	*/
40
41	RT_C_DECLS_BEGIN
42
43	/** Pointer to a record union.
44	* @internal */
45	typedef union RTLOCKVALRECUNION *PRTLOCKVALRECUNION;
46
47	/**
48	* Source position.
49	*/
50	typedef struct RTLOCKVALSRCPOS
51	{
52	/** The file where the lock was taken. */
53	R3R0PTRTYPE(const char * volatile) pszFile;
54	/** The function where the lock was taken. */
55	R3R0PTRTYPE(const char * volatile) pszFunction;
56	/** Some ID indicating where the lock was taken, typically an address. */
57	RTHCUINTPTR volatile uId;
58	/** The line number in the file. */
59	uint32_t volatile uLine;
60	#if HC_ARCH_BITS == 64
61	uint32_t u32Padding; /*< Alignment padding. /
62	#endif
63	} RTLOCKVALSRCPOS;
64	AssertCompileSize(RTLOCKVALSRCPOS, HC_ARCH_BITS == 32 ? 16 : 32);
65	/* The pointer types are defined in iprt/types.h. */
66
67	/** @def RTLOCKVALSRCPOS_INIT
68	* Initializer for a RTLOCKVALSRCPOS variable.
69	*
70	* @param pszFile The file name. Optional (NULL).
71	* @param uLine The line number in that file. Optional (0).
72	* @param pszFunction The function. Optional (NULL).
73	* @param uId Some location ID, normally the return address.
74	* Optional (NULL).
75	*/
76	#if HC_ARCH_BITS == 64
77	# define RTLOCKVALSRCPOS_INIT(pszFile, uLine, pszFunction, uId) \
78	{ (pszFile), (pszFunction), (uId), (uLine), 0 }
79	#else
80	# define RTLOCKVALSRCPOS_INIT(pszFile, uLine, pszFunction, uId) \
81	{ (pszFile), (pszFunction), (uId), (uLine) }
82	#endif
83
84	/** @def RTLOCKVALSRCPOS_INIT_DEBUG_API
85	* Initializer for a RTLOCKVALSRCPOS variable in a typicial debug API
86	* variant. Assumes RT_SRC_POS_DECL and RTHCUINTPTR uId as arguments.
87	*/
88	#define RTLOCKVALSRCPOS_INIT_DEBUG_API() \
89	RTLOCKVALSRCPOS_INIT(pszFile, iLine, pszFunction, uId)
90
91	/** @def RTLOCKVALSRCPOS_INIT_NORMAL_API
92	* Initializer for a RTLOCKVALSRCPOS variable in a normal API
93	* variant. Assumes iprt/asm.h is included.
94	*/
95	#define RTLOCKVALSRCPOS_INIT_NORMAL_API() \
96	RTLOCKVALSRCPOS_INIT(__FILE__, __LINE__, __PRETTY_FUNCTION__, (uintptr_t)ASMReturnAddress())
97
98	/** @def RTLOCKVALSRCPOS_INIT_POS_NO_ID
99	* Initializer for a RTLOCKVALSRCPOS variable when no @c uId is present.
100	* Assumes iprt/asm.h is included.
101	*/
102	#define RTLOCKVALSRCPOS_INIT_POS_NO_ID() \
103	RTLOCKVALSRCPOS_INIT(pszFile, iLine, pszFunction, (uintptr_t)ASMReturnAddress())
104
105
106	/**
107	* Lock validator record core.
108	*/
109	typedef struct RTLOCKVALRECORE
110	{
111	/** The magic value indicating the record type. */
112	uint32_t volatile u32Magic;
113	} RTLOCKVALRECCORE;
114	/** Pointer to a lock validator record core. */
115	typedef RTLOCKVALRECCORE *PRTLOCKVALRECCORE;
116	/** Pointer to a const lock validator record core. */
117	typedef RTLOCKVALRECCORE const *PCRTLOCKVALRECCORE;
118
119
120	/**
121	* Record recording the exclusive ownership of a lock.
122	*
123	* This is typically part of the per-lock data structure when compiling with
124	* the lock validator.
125	*/
126	typedef struct RTLOCKVALRECEXCL
127	{
128	/** Record core with RTLOCKVALRECEXCL_MAGIC as the magic value. */
129	RTLOCKVALRECCORE Core;
130	/** Whether it's enabled or not. */
131	bool fEnabled;
132	/** Reserved. */
133	bool afReserved[3];
134	/** Source position where the lock was taken. */
135	RTLOCKVALSRCPOS SrcPos;
136	/** The current owner thread. */
137	RTTHREAD volatile hThread;
138	/** Pointer to the lock record below us. Only accessed by the owner. */
139	R3R0PTRTYPE(PRTLOCKVALRECUNION) pDown;
140	/** Recursion count */
141	uint32_t cRecursion;
142	/** The lock sub-class. */
143	uint32_t volatile uSubClass;
144	/** The lock class. */
145	RTLOCKVALCLASS hClass;
146	/** Pointer to the lock. */
147	RTHCPTR hLock;
148	/** Pointer to the next sibling record.
149	* This is used to find the read side of a read-write lock. */
150	R3R0PTRTYPE(PRTLOCKVALRECUNION) pSibling;
151	/** The lock name.
152	* @remarks The bytes beyond 32 are for better size alignment and can be
153	* taken and used for other purposes if it becomes necessary. */
154	char szName[32 + (HC_ARCH_BITS == 32 ? 12 : 8)];
155	} RTLOCKVALRECEXCL;
156	AssertCompileSize(RTLOCKVALRECEXCL, HC_ARCH_BITS == 32 ? 0x60 : 0x80);
157	/* The pointer type is defined in iprt/types.h. */
158
159	/**
160	* For recording the one ownership share.
161	*/
162	typedef struct RTLOCKVALRECSHRDOWN
163	{
164	/** Record core with RTLOCKVALRECSHRDOWN_MAGIC as the magic value. */
165	RTLOCKVALRECCORE Core;
166	/** Recursion count */
167	uint16_t cRecursion;
168	/** Static (true) or dynamic (false) allocated record. */
169	bool fStaticAlloc;
170	/** Reserved. */
171	bool fReserved;
172	/** The current owner thread. */
173	RTTHREAD volatile hThread;
174	/** Pointer to the lock record below us. Only accessed by the owner. */
175	R3R0PTRTYPE(PRTLOCKVALRECUNION) pDown;
176	/** Pointer back to the shared record. */
177	R3R0PTRTYPE(PRTLOCKVALRECSHRD) pSharedRec;
178	#if HC_ARCH_BITS == 32
179	/** Reserved. */
180	RTHCPTR pvReserved;
181	#endif
182	/** Source position where the lock was taken. */
183	RTLOCKVALSRCPOS SrcPos;
184	} RTLOCKVALRECSHRDOWN;
185	AssertCompileSize(RTLOCKVALRECSHRDOWN, HC_ARCH_BITS == 32 ? 24 + 16 : 32 + 32);
186	/** Pointer to a RTLOCKVALRECSHRDOWN. */
187	typedef RTLOCKVALRECSHRDOWN *PRTLOCKVALRECSHRDOWN;
188
189	/**
190	* Record recording the shared ownership of a lock.
191	*
192	* This is typically part of the per-lock data structure when compiling with
193	* the lock validator.
194	*/
195	typedef struct RTLOCKVALRECSHRD
196	{
197	/** Record core with RTLOCKVALRECSHRD_MAGIC as the magic value. */
198	RTLOCKVALRECCORE Core;
199	/** The lock sub-class. */
200	uint32_t volatile uSubClass;
201	/** The lock class. */
202	RTLOCKVALCLASS hClass;
203	/** Pointer to the lock. */
204	RTHCPTR hLock;
205	/** Pointer to the next sibling record.
206	* This is used to find the write side of a read-write lock. */
207	R3R0PTRTYPE(PRTLOCKVALRECUNION) pSibling;
208
209	/** The number of entries in the table.
210	* Updated before inserting and after removal. */
211	uint32_t volatile cEntries;
212	/** The index of the last entry (approximately). */
213	uint32_t volatile iLastEntry;
214	/** The max table size. */
215	uint32_t volatile cAllocated;
216	/** Set if the table is being reallocated, clear if not.
217	* This is used together with rtLockValidatorSerializeDetectionEnter to make
218	* sure there is exactly one thread doing the reallocation and that nobody is
219	* using the table at that point. */
220	bool volatile fReallocating;
221	/** Whether it's enabled or not. */
222	bool fEnabled;
223	/** Set if event semaphore signaller, clear if read-write semaphore. */
224	bool fSignaller;
225	/** Alignment padding. */
226	bool fPadding;
227	/** Pointer to a table containing pointers to records of all the owners. */
228	R3R0PTRTYPE(PRTLOCKVALRECSHRDOWN volatile *) papOwners;
229
230	/** The lock name.
231	* @remarks The bytes beyond 32 are for better size alignment and can be
232	* taken and used for other purposes if it becomes necessary. */
233	char szName[32 + (HC_ARCH_BITS == 32 ? 8 : 8)];
234	} RTLOCKVALRECSHRD;
235	AssertCompileSize(RTLOCKVALRECSHRD, HC_ARCH_BITS == 32 ? 0x50 : 0x60);
236
237
238	/**
239	* Makes the two records siblings.
240	*
241	* @returns VINF_SUCCESS on success, VERR_SEM_LV_INVALID_PARAMETER if either of
242	* the records are invalid.
243	* @param pRec1 Record 1.
244	* @param pRec2 Record 2.
245	*/
246	RTDECL(int) RTLockValidatorRecMakeSiblings(PRTLOCKVALRECCORE pRec1, PRTLOCKVALRECCORE pRec2);
247
248	/**
249	* Initialize a lock validator record.
250	*
251	* Use RTLockValidatorRecExclDelete to deinitialize it.
252	*
253	* @param pRec The record.
254	* @param hClass The class (no reference consumed). If NIL, the
255	* no lock order validation will be performed on
256	* this lock.
257	* @param uSubClass The sub-class. This is used to define lock
258	* order inside the same class. If you don't know,
259	* then pass RTLOCKVAL_SUB_CLASS_NONE.
260	* @param hLock The lock handle.
261	* @param fEnabled Pass @c false to explicitly disable lock
262	* validation, otherwise @c true.
263	* @param pszNameFmt Name format string for the lock validator,
264	* optional (NULL). Max length is 32 bytes.
265	* @param ... Format string arguments.
266	*/
267	RTDECL(void) RTLockValidatorRecExclInit(PRTLOCKVALRECEXCL pRec, RTLOCKVALCLASS hClass, uint32_t uSubClass, void *hLock,
268	bool fEnabled, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(6, 7);
269	/**
270	* Initialize a lock validator record.
271	*
272	* Use RTLockValidatorRecExclDelete to deinitialize it.
273	*
274	* @param pRec The record.
275	* @param hClass The class (no reference consumed). If NIL, the
276	* no lock order validation will be performed on
277	* this lock.
278	* @param uSubClass The sub-class. This is used to define lock
279	* order inside the same class. If you don't know,
280	* then pass RTLOCKVAL_SUB_CLASS_NONE.
281	* @param hLock The lock handle.
282	* @param fEnabled Pass @c false to explicitly disable lock
283	* validation, otherwise @c true.
284	* @param pszNameFmt Name format string for the lock validator,
285	* optional (NULL). Max length is 32 bytes.
286	* @param va Format string arguments.
287	*/
288	RTDECL(void) RTLockValidatorRecExclInitV(PRTLOCKVALRECEXCL pRec, RTLOCKVALCLASS hClass, uint32_t uSubClass, void *hLock,
289	bool fEnabled, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(6, 0);
290	/**
291	* Uninitialize a lock validator record previously initialized by
292	* RTLockRecValidatorInit.
293	*
294	* @param pRec The record. Must be valid.
295	*/
296	RTDECL(void) RTLockValidatorRecExclDelete(PRTLOCKVALRECEXCL pRec);
297
298	/**
299	* Create and initialize a lock validator record.
300	*
301	* Use RTLockValidatorRecExclDestroy to deinitialize and destroy the returned
302	* record.
303	*
304	* @return VINF_SUCCESS or VERR_NO_MEMORY.
305	* @param ppRec Where to return the record pointer.
306	* @param hClass The class (no reference consumed). If NIL, the
307	* no lock order validation will be performed on
308	* this lock.
309	* @param uSubClass The sub-class. This is used to define lock
310	* order inside the same class. If you don't know,
311	* then pass RTLOCKVAL_SUB_CLASS_NONE.
312	* @param hLock The lock handle.
313	* @param fEnabled Pass @c false to explicitly disable lock
314	* validation, otherwise @c true.
315	* @param pszNameFmt Name format string for the lock validator,
316	* optional (NULL). Max length is 32 bytes.
317	* @param ... Format string arguments.
318	*/
319	RTDECL(int) RTLockValidatorRecExclCreate(PRTLOCKVALRECEXCL ppRec, RTLOCKVALCLASS hClass, uint32_t uSubClass, void hLock,
320	bool fEnabled, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(6, 7);
321
322	/**
323	* Create and initialize a lock validator record.
324	*
325	* Use RTLockValidatorRecExclDestroy to deinitialize and destroy the returned
326	* record.
327	*
328	* @return VINF_SUCCESS or VERR_NO_MEMORY.
329	* @param ppRec Where to return the record pointer.
330	* @param hClass The class (no reference consumed). If NIL, the
331	* no lock order validation will be performed on
332	* this lock.
333	* @param uSubClass The sub-class. This is used to define lock
334	* order inside the same class. If you don't know,
335	* then pass RTLOCKVAL_SUB_CLASS_NONE.
336	* @param hLock The lock handle.
337	* @param fEnabled Pass @c false to explicitly disable lock
338	* validation, otherwise @c true.
339	* @param pszNameFmt Name format string for the lock validator,
340	* optional (NULL). Max length is 32 bytes.
341	* @param va Format string arguments.
342	*/
343	RTDECL(int) RTLockValidatorRecExclCreateV(PRTLOCKVALRECEXCL ppRec, RTLOCKVALCLASS hClass, uint32_t uSubClass, void hLock,
344	bool fEnabled, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(6, 0);
345
346	/**
347	* Deinitialize and destroy a record created by RTLockValidatorRecExclCreate.
348	*
349	* @param ppRec Pointer to the record pointer. Will be set to
350	* NULL.
351	*/
352	RTDECL(void) RTLockValidatorRecExclDestroy(PRTLOCKVALRECEXCL *ppRec);
353
354	/**
355	* Sets the sub-class of the record.
356	*
357	* It is recommended to try make sure that nobody is using this class while
358	* changing the value.
359	*
360	* @returns The old sub-class. RTLOCKVAL_SUB_CLASS_INVALID is returns if the
361	* lock validator isn't compiled in or either of the parameters are
362	* invalid.
363	* @param pRec The validator record.
364	* @param uSubClass The new sub-class value.
365	*/
366	RTDECL(uint32_t) RTLockValidatorRecExclSetSubClass(PRTLOCKVALRECEXCL pRec, uint32_t uSubClass);
367
368	/**
369	* Record the specified thread as lock owner and increment the write lock count.
370	*
371	* This function is typically called after acquiring the lock. It accounts for
372	* recursions so it can be used instead of RTLockValidatorRecExclRecursion. Use
373	* RTLockValidatorRecExclReleaseOwner to reverse the effect.
374	*
375	* @param pRec The validator record.
376	* @param hThreadSelf The handle of the calling thread. If not known,
377	* pass NIL_RTTHREAD and we'll figure it out.
378	* @param pSrcPos The source position of the lock operation.
379	* @param fFirstRecursion Set if it is the first recursion, clear if not
380	* sure.
381	*/
382	RTDECL(void) RTLockValidatorRecExclSetOwner(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf,
383	PCRTLOCKVALSRCPOS pSrcPos, bool fFirstRecursion);
384
385	/**
386	* Check the exit order and release (unset) the ownership.
387	*
388	* This is called by routines implementing releasing an exclusive lock,
389	* typically before getting down to the final lock releasing. Can be used for
390	* recursive releasing instead of RTLockValidatorRecExclUnwind.
391	*
392	* @retval VINF_SUCCESS on success.
393	* @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the order is wrong. Will have
394	* done all necessary whining and breakpointing before returning.
395	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
396	*
397	* @param pRec The validator record.
398	* @param fFinalRecursion Set if it's the final recursion, clear if not
399	* sure.
400	*/
401	RTDECL(int) RTLockValidatorRecExclReleaseOwner(PRTLOCKVALRECEXCL pRec, bool fFinalRecursion);
402
403	/**
404	* Clear the lock ownership and decrement the write lock count.
405	*
406	* This is only for special cases where we wish to drop lock validation
407	* recording. See RTLockValidatorRecExclCheckAndRelease.
408	*
409	* @param pRec The validator record.
410	*/
411	RTDECL(void) RTLockValidatorRecExclReleaseOwnerUnchecked(PRTLOCKVALRECEXCL pRec);
412
413	/**
414	* Checks and records a lock recursion.
415	*
416	* @retval VINF_SUCCESS on success.
417	* @retval VERR_SEM_LV_NESTED if the semaphore class forbids recursion. Gone
418	* thru the motions.
419	* @retval VERR_SEM_LV_WRONG_ORDER if the locking order is wrong. Gone thru
420	* the motions.
421	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
422	*
423	* @param pRec The validator record.
424	* @param pSrcPos The source position of the lock operation.
425	*/
426	RTDECL(int) RTLockValidatorRecExclRecursion(PRTLOCKVALRECEXCL pRec, PCRTLOCKVALSRCPOS pSrcPos);
427
428	/**
429	* Checks and records a lock unwind (releasing one recursion).
430	*
431	* This should be coupled with called to RTLockValidatorRecExclRecursion.
432	*
433	* @retval VINF_SUCCESS on success.
434	* @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the release order is wrong. Gone
435	* thru the motions.
436	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
437	*
438	* @param pRec The validator record.
439	*/
440	RTDECL(int) RTLockValidatorRecExclUnwind(PRTLOCKVALRECEXCL pRec);
441
442	/**
443	* Checks and records a mixed recursion.
444	*
445	* An example of a mixed recursion is a writer requesting read access to a
446	* SemRW.
447	*
448	* This should be coupled with called to RTLockValidatorRecExclUnwindMixed.
449	*
450	* @retval VINF_SUCCESS on success.
451	* @retval VERR_SEM_LV_NESTED if the semaphore class forbids recursion. Gone
452	* thru the motions.
453	* @retval VERR_SEM_LV_WRONG_ORDER if the locking order is wrong. Gone thru
454	* the motions.
455	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
456	*
457	* @param pRec The validator record it to accounted it to.
458	* @param pRecMixed The validator record it came in on.
459	* @param pSrcPos The source position of the lock operation.
460	*/
461	RTDECL(int) RTLockValidatorRecExclRecursionMixed(PRTLOCKVALRECEXCL pRec, PRTLOCKVALRECCORE pRecMixed, PCRTLOCKVALSRCPOS pSrcPos);
462
463	/**
464	* Checks and records the unwinding of a mixed recursion.
465	*
466	* This should be coupled with called to RTLockValidatorRecExclRecursionMixed.
467	*
468	* @retval VINF_SUCCESS on success.
469	* @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the release order is wrong. Gone
470	* thru the motions.
471	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
472	*
473	* @param pRec The validator record it was accounted to.
474	* @param pRecMixed The validator record it came in on.
475	*/
476	RTDECL(int) RTLockValidatorRecExclUnwindMixed(PRTLOCKVALRECEXCL pRec, PRTLOCKVALRECCORE pRecMixed);
477
478	/**
479	* Check the exclusive locking order.
480	*
481	* This is called by routines implementing exclusive lock acquisition.
482	*
483	* @retval VINF_SUCCESS on success.
484	* @retval VERR_SEM_LV_WRONG_ORDER if the order is wrong. Will have done all
485	* necessary whining and breakpointing before returning.
486	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
487	*
488	* @param pRec The validator record.
489	* @param hThreadSelf The handle of the calling thread. If not known,
490	* pass NIL_RTTHREAD and we'll figure it out.
491	* @param pSrcPos The source position of the lock operation.
492	* @param cMillies The timeout, in milliseconds.
493	*/
494	RTDECL(int) RTLockValidatorRecExclCheckOrder(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf,
495	PCRTLOCKVALSRCPOS pSrcPos, RTMSINTERVAL cMillies);
496
497	/**
498	* Do deadlock detection before blocking on exclusive access to a lock and
499	* change the thread state.
500	*
501	* @retval VINF_SUCCESS - thread is in the specified sleep state.
502	* @retval VERR_SEM_LV_DEADLOCK if blocking would deadlock. Gone thru the
503	* motions.
504	* @retval VERR_SEM_LV_NESTED if the semaphore isn't recursive and hThread is
505	* already the owner. Gone thru the motions.
506	* @retval VERR_SEM_LV_ILLEGAL_UPGRADE if it's a deadlock on the same lock.
507	* The caller must handle any legal upgrades without invoking this
508	* function (for now).
509	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
510	*
511	* @param pRec The validator record we're blocking on.
512	* @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD!
513	* @param pSrcPos The source position of the lock operation.
514	* @param fRecursiveOk Whether it's ok to recurse.
515	* @param cMillies The timeout, in milliseconds.
516	* @param enmSleepState The sleep state to enter on successful return.
517	* @param fReallySleeping Is it really going to sleep now or not. Use
518	* false before calls to other IPRT synchronization
519	* methods.
520	*/
521	RTDECL(int) RTLockValidatorRecExclCheckBlocking(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf,
522	PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk, RTMSINTERVAL cMillies,
523	RTTHREADSTATE enmSleepState, bool fReallySleeping);
524
525	/**
526	* RTLockValidatorRecExclCheckOrder and RTLockValidatorRecExclCheckBlocking
527	* baked into one call.
528	*
529	* @returns Any of the statuses returned by the two APIs.
530	* @param pRec The validator record.
531	* @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD!
532	* @param pSrcPos The source position of the lock operation.
533	* @param fRecursiveOk Whether it's ok to recurse.
534	* @param cMillies The timeout, in milliseconds.
535	* @param enmSleepState The sleep state to enter on successful return.
536	* @param fReallySleeping Is it really going to sleep now or not. Use
537	* false before calls to other IPRT synchronization
538	* methods.
539	*/
540	RTDECL(int) RTLockValidatorRecExclCheckOrderAndBlocking(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf,
541	PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk, RTMSINTERVAL cMillies,
542	RTTHREADSTATE enmSleepState, bool fReallySleeping);
543
544	/**
545	* Initialize a lock validator record for a shared lock.
546	*
547	* Use RTLockValidatorRecSharedDelete to deinitialize it.
548	*
549	* @param pRec The shared lock record.
550	* @param hClass The class (no reference consumed). If NIL, the
551	* no lock order validation will be performed on
552	* this lock.
553	* @param uSubClass The sub-class. This is used to define lock
554	* order inside the same class. If you don't know,
555	* then pass RTLOCKVAL_SUB_CLASS_NONE.
556	* @param hLock The lock handle.
557	* @param fSignaller Set if event semaphore signaller logic should be
558	* applied to this record, clear if read-write
559	* semaphore logic should be used.
560	* @param fEnabled Pass @c false to explicitly disable lock
561	* validation, otherwise @c true.
562	* @param pszNameFmt Name format string for the lock validator,
563	* optional (NULL). Max length is 32 bytes.
564	* @param ... Format string arguments.
565	*/
566	RTDECL(void) RTLockValidatorRecSharedInit(PRTLOCKVALRECSHRD pRec, RTLOCKVALCLASS hClass, uint32_t uSubClass,
567	void *hLock, bool fSignaller, bool fEnabled,
568	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(7, 8);
569
570	/**
571	* Initialize a lock validator record for a shared lock.
572	*
573	* Use RTLockValidatorRecSharedDelete to deinitialize it.
574	*
575	* @param pRec The shared lock record.
576	* @param hClass The class (no reference consumed). If NIL, the
577	* no lock order validation will be performed on
578	* this lock.
579	* @param uSubClass The sub-class. This is used to define lock
580	* order inside the same class. If you don't know,
581	* then pass RTLOCKVAL_SUB_CLASS_NONE.
582	* @param hLock The lock handle.
583	* @param fSignaller Set if event semaphore signaller logic should be
584	* applied to this record, clear if read-write
585	* semaphore logic should be used.
586	* @param fEnabled Pass @c false to explicitly disable lock
587	* validation, otherwise @c true.
588	* @param pszNameFmt Name format string for the lock validator,
589	* optional (NULL). Max length is 32 bytes.
590	* @param va Format string arguments.
591	*/
592	RTDECL(void) RTLockValidatorRecSharedInitV(PRTLOCKVALRECSHRD pRec, RTLOCKVALCLASS hClass, uint32_t uSubClass,
593	void *hLock, bool fSignaller, bool fEnabled,
594	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(7, 0);
595
596	/**
597	* Uninitialize a lock validator record previously initialized by
598	* RTLockValidatorRecSharedInit.
599	*
600	* @param pRec The shared lock record. Must be valid.
601	*/
602	RTDECL(void) RTLockValidatorRecSharedDelete(PRTLOCKVALRECSHRD pRec);
603
604	/**
605	* Create and initialize a lock validator record for a shared lock.
606	*
607	* Use RTLockValidatorRecSharedDestroy to deinitialize and destroy the returned
608	* record.
609	*
610	* @returns IPRT status code.
611	* @param ppRec Where to return the record pointer.
612	* @param hClass The class (no reference consumed). If NIL, the
613	* no lock order validation will be performed on
614	* this lock.
615	* @param uSubClass The sub-class. This is used to define lock
616	* order inside the same class. If you don't know,
617	* then pass RTLOCKVAL_SUB_CLASS_NONE.
618	* @param pvLock The lock handle or address.
619	* @param fSignaller Set if event semaphore signaller logic should be
620	* applied to this record, clear if read-write
621	* semaphore logic should be used.
622	* @param fEnabled Pass @c false to explicitly disable lock
623	* validation, otherwise @c true.
624	* @param pszNameFmt Name format string for the lock validator,
625	* optional (NULL). Max length is 32 bytes.
626	* @param ... Format string arguments.
627	*/
628	RTDECL(int) RTLockValidatorRecSharedCreate(PRTLOCKVALRECSHRD *ppRec, RTLOCKVALCLASS hClass, uint32_t uSubClass,
629	void *pvLock, bool fSignaller, bool fEnabled,
630	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(7, 8);
631
632	/**
633	* Create and initialize a lock validator record for a shared lock.
634	*
635	* Use RTLockValidatorRecSharedDestroy to deinitialize and destroy the returned
636	* record.
637	*
638	* @returns IPRT status code.
639	* @param ppRec Where to return the record pointer.
640	* @param hClass The class (no reference consumed). If NIL, the
641	* no lock order validation will be performed on
642	* this lock.
643	* @param uSubClass The sub-class. This is used to define lock
644	* order inside the same class. If you don't know,
645	* then pass RTLOCKVAL_SUB_CLASS_NONE.
646	* @param pvLock The lock handle or address.
647	* @param fSignaller Set if event semaphore signaller logic should be
648	* applied to this record, clear if read-write
649	* semaphore logic should be used.
650	* @param fEnabled Pass @c false to explicitly disable lock
651	* validation, otherwise @c true.
652	* @param pszNameFmt Name format string for the lock validator,
653	* optional (NULL). Max length is 32 bytes.
654	* @param va Format string arguments.
655	*/
656	RTDECL(int) RTLockValidatorRecSharedCreateV(PRTLOCKVALRECSHRD *ppRec, RTLOCKVALCLASS hClass, uint32_t uSubClass,
657	void *pvLock, bool fSignaller, bool fEnabled,
658	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(7, 0);
659
660	/**
661	* Deinitialize and destroy a record created by RTLockValidatorRecSharedCreate.
662	*
663	* @param ppRec Pointer to the record pointer. Will be set to
664	* NULL.
665	*/
666	RTDECL(void) RTLockValidatorRecSharedDestroy(PRTLOCKVALRECSHRD *ppRec);
667
668	/**
669	* Sets the sub-class of the record.
670	*
671	* It is recommended to try make sure that nobody is using this class while
672	* changing the value.
673	*
674	* @returns The old sub-class. RTLOCKVAL_SUB_CLASS_INVALID is returns if the
675	* lock validator isn't compiled in or either of the parameters are
676	* invalid.
677	* @param pRec The validator record.
678	* @param uSubClass The new sub-class value.
679	*/
680	RTDECL(uint32_t) RTLockValidatorRecSharedSetSubClass(PRTLOCKVALRECSHRD pRec, uint32_t uSubClass);
681
682	/**
683	* Check the shared locking order.
684	*
685	* This is called by routines implementing shared lock acquisition.
686	*
687	* @retval VINF_SUCCESS on success.
688	* @retval VERR_SEM_LV_WRONG_ORDER if the order is wrong. Will have done all
689	* necessary whining and breakpointing before returning.
690	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
691	*
692	* @param pRec The validator record.
693	* @param hThreadSelf The handle of the calling thread. If not known,
694	* pass NIL_RTTHREAD and we'll figure it out.
695	* @param pSrcPos The source position of the lock operation.
696	* @param cMillies Intended sleep time in milliseconds.
697	*/
698	RTDECL(int) RTLockValidatorRecSharedCheckOrder(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf,
699	PCRTLOCKVALSRCPOS pSrcPos, RTMSINTERVAL cMillies);
700
701	/**
702	* Do deadlock detection before blocking on shared access to a lock and change
703	* the thread state.
704	*
705	* @retval VINF_SUCCESS - thread is in the specified sleep state.
706	* @retval VERR_SEM_LV_DEADLOCK if blocking would deadlock. Gone thru the
707	* motions.
708	* @retval VERR_SEM_LV_NESTED if the semaphore isn't recursive and hThread is
709	* already the owner. Gone thru the motions.
710	* @retval VERR_SEM_LV_ILLEGAL_UPGRADE if it's a deadlock on the same lock.
711	* The caller must handle any legal upgrades without invoking this
712	* function (for now).
713	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
714	*
715	* @param pRec The validator record we're blocking on.
716	* @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD!
717	* @param pSrcPos The source position of the lock operation.
718	* @param fRecursiveOk Whether it's ok to recurse.
719	* @param cMillies Intended sleep time in milliseconds.
720	* @param enmSleepState The sleep state to enter on successful return.
721	* @param fReallySleeping Is it really going to sleep now or not. Use
722	* false before calls to other IPRT synchronization
723	* methods.
724	*/
725	RTDECL(int) RTLockValidatorRecSharedCheckBlocking(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf,
726	PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk, RTMSINTERVAL cMillies,
727	RTTHREADSTATE enmSleepState, bool fReallySleeping);
728
729	/**
730	* RTLockValidatorRecSharedCheckOrder and RTLockValidatorRecSharedCheckBlocking
731	* baked into one call.
732	*
733	* @returns Any of the statuses returned by the two APIs.
734	* @param pRec The validator record.
735	* @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD!
736	* @param pSrcPos The source position of the lock operation.
737	* @param fRecursiveOk Whether it's ok to recurse.
738	* @param cMillies Intended sleep time in milliseconds.
739	* @param enmSleepState The sleep state to enter on successful return.
740	* @param fReallySleeping Is it really going to sleep now or not. Use
741	* false before calls to other IPRT synchronization
742	* methods.
743	*/
744	RTDECL(int) RTLockValidatorRecSharedCheckOrderAndBlocking(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf,
745	PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk, RTMSINTERVAL cMillies,
746	RTTHREADSTATE enmSleepState, bool fReallySleeping);
747
748	/**
749	* Removes all current owners and makes hThread the only owner.
750	*
751	* @param pRec The validator record.
752	* @param hThread The thread handle of the owner. NIL_RTTHREAD is
753	* an alias for the current thread.
754	* @param pSrcPos The source position of the lock operation.
755	*/
756	RTDECL(void) RTLockValidatorRecSharedResetOwner(PRTLOCKVALRECSHRD pRec, RTTHREAD hThread, PCRTLOCKVALSRCPOS pSrcPos);
757
758	/**
759	* Adds an owner to a shared locking record.
760	*
761	* Takes recursion into account. This function is typically called after
762	* acquiring the lock in shared mode.
763	*
764	* @param pRec The validator record.
765	* @param hThread The thread handle of the owner. NIL_RTTHREAD is
766	* an alias for the current thread.
767	* @param pSrcPos The source position of the lock operation.
768	*/
769	RTDECL(void) RTLockValidatorRecSharedAddOwner(PRTLOCKVALRECSHRD pRec, RTTHREAD hThread, PCRTLOCKVALSRCPOS pSrcPos);
770
771	/**
772	* Removes an owner from a shared locking record.
773	*
774	* Takes recursion into account. This function is typically called before
775	* releasing the lock.
776	*
777	* @param pRec The validator record.
778	* @param hThread The thread handle of the owner. NIL_RTTHREAD is
779	* an alias for the current thread.
780	*/
781	RTDECL(void) RTLockValidatorRecSharedRemoveOwner(PRTLOCKVALRECSHRD pRec, RTTHREAD hThread);
782
783	/**
784	* Checks if the specified thread is one of the owners.
785	*
786	* @returns true if it is, false if not.
787	*
788	* @param pRec The validator record.
789	* @param hThread The thread handle of the owner. NIL_RTTHREAD is
790	* an alias for the current thread.
791	*/
792	RTDECL(bool) RTLockValidatorRecSharedIsOwner(PRTLOCKVALRECSHRD pRec, RTTHREAD hThread);
793
794	/**
795	* Check the exit order and release (unset) the shared ownership.
796	*
797	* This is called by routines implementing releasing the read/write lock.
798	*
799	* @retval VINF_SUCCESS on success.
800	* @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the order is wrong. Will have
801	* done all necessary whining and breakpointing before returning.
802	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
803	*
804	* @param pRec The validator record.
805	* @param hThreadSelf The handle of the calling thread. NIL_RTTHREAD
806	* is an alias for the current thread.
807	*/
808	RTDECL(int) RTLockValidatorRecSharedCheckAndRelease(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf);
809
810	/**
811	* Check the signaller of an event.
812	*
813	* This is called by routines implementing releasing the event semaphore (both
814	* kinds).
815	*
816	* @retval VINF_SUCCESS on success.
817	* @retval VERR_SEM_LV_NOT_SIGNALLER if the thread is not in the record. Will
818	* have done all necessary whining and breakpointing before returning.
819	* @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
820	*
821	* @param pRec The validator record.
822	* @param hThreadSelf The handle of the calling thread. NIL_RTTHREAD
823	* is an alias for the current thread.
824	*/
825	RTDECL(int) RTLockValidatorRecSharedCheckSignaller(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf);
826
827	/**
828	* Gets the number of write locks and critical sections the specified
829	* thread owns.
830	*
831	* This number does not include any nested lock/critect entries.
832	*
833	* Note that it probably will return 0 for non-strict builds since
834	* release builds doesn't do unnecessary diagnostic counting like this.
835	*
836	* @returns Number of locks on success (0+) and VERR_INVALID_HANDLER on failure
837	* @param Thread The thread we're inquiring about.
838	* @remarks Will only work for strict builds.
839	*/
840	RTDECL(int32_t) RTLockValidatorWriteLockGetCount(RTTHREAD Thread);
841
842	/**
843	* Works the THREADINT::cWriteLocks member, mostly internal.
844	*
845	* @param Thread The current thread.
846	*/
847	RTDECL(void) RTLockValidatorWriteLockInc(RTTHREAD Thread);
848
849	/**
850	* Works the THREADINT::cWriteLocks member, mostly internal.
851	*
852	* @param Thread The current thread.
853	*/
854	RTDECL(void) RTLockValidatorWriteLockDec(RTTHREAD Thread);
855
856	/**
857	* Gets the number of read locks the specified thread owns.
858	*
859	* Note that nesting read lock entry will be included in the
860	* total sum. And that it probably will return 0 for non-strict
861	* builds since release builds doesn't do unnecessary diagnostic
862	* counting like this.
863	*
864	* @returns Number of read locks on success (0+) and VERR_INVALID_HANDLER on failure
865	* @param Thread The thread we're inquiring about.
866	*/
867	RTDECL(int32_t) RTLockValidatorReadLockGetCount(RTTHREAD Thread);
868
869	/**
870	* Works the THREADINT::cReadLocks member.
871	*
872	* @param Thread The current thread.
873	*/
874	RTDECL(void) RTLockValidatorReadLockInc(RTTHREAD Thread);
875
876	/**
877	* Works the THREADINT::cReadLocks member.
878	*
879	* @param Thread The current thread.
880	*/
881	RTDECL(void) RTLockValidatorReadLockDec(RTTHREAD Thread);
882
883	/**
884	* Query which lock the specified thread is waiting on.
885	*
886	* @returns The lock handle value or NULL.
887	* @param hThread The thread in question.
888	*/
889	RTDECL(void *) RTLockValidatorQueryBlocking(RTTHREAD hThread);
890
891	/**
892	* Checks if the thread is running in the lock validator after it has entered a
893	* block state.
894	*
895	* @returns true if it is, false if it isn't.
896	* @param hThread The thread in question.
897	*/
898	RTDECL(bool) RTLockValidatorIsBlockedThreadInValidator(RTTHREAD hThread);
899
900	/**
901	* Checks if the calling thread is holding a lock in the specified class.
902	*
903	* @returns true if it holds a lock in the specific class, false if it
904	* doesn't.
905	*
906	* @param hCurrentThread The current thread. Pass NIL_RTTHREAD if you're
907	* lazy.
908	* @param hClass The class.
909	*/
910	RTDECL(bool) RTLockValidatorHoldsLocksInClass(RTTHREAD hCurrentThread, RTLOCKVALCLASS hClass);
911
912	/**
913	* Checks if the calling thread is holding a lock in the specified sub-class.
914	*
915	* @returns true if it holds a lock in the specific sub-class, false if it
916	* doesn't.
917	*
918	* @param hCurrentThread The current thread. Pass NIL_RTTHREAD if you're
919	* lazy.
920	* @param hClass The class.
921	* @param uSubClass The new sub-class value.
922	*/
923	RTDECL(bool) RTLockValidatorHoldsLocksInSubClass(RTTHREAD hCurrentThread, RTLOCKVALCLASS hClass, uint32_t uSubClass);
924
925
926
927	/**
928	* Creates a new lock validator class, all properties specified.
929	*
930	* @returns IPRT status code
931	* @param phClass Where to return the class handle.
932	* @param pSrcPos The source position of the create call.
933	* @param fAutodidact Whether the class should be allowed to teach
934	* itself new locking order rules (true), or if the
935	* user will teach it all it needs to know (false).
936	* @param fRecursionOk Whether to allow lock recursion or not.
937	* @param fStrictReleaseOrder Enforce strict lock release order or not.
938	* @param cMsMinDeadlock Used to raise the sleep interval at which
939	* deadlock detection kicks in. Minimum is 1 ms,
940	* while RT_INDEFINITE_WAIT will disable it.
941	* @param cMsMinOrder Used to raise the sleep interval at which lock
942	* order validation kicks in. Minimum is 1 ms,
943	* while RT_INDEFINITE_WAIT will disable it.
944	* @param pszNameFmt Class name format string, optional (NULL). Max
945	* length is 32 bytes.
946	* @param ... Format string arguments.
947	*
948	* @remarks The properties can be modified after creation by the
949	* RTLockValidatorClassSet* methods.
950	*/
951	RTDECL(int) RTLockValidatorClassCreateEx(PRTLOCKVALCLASS phClass, PCRTLOCKVALSRCPOS pSrcPos,
952	bool fAutodidact, bool fRecursionOk, bool fStrictReleaseOrder,
953	RTMSINTERVAL cMsMinDeadlock, RTMSINTERVAL cMsMinOrder,
954	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(8, 9);
955
956	/**
957	* Creates a new lock validator class, all properties specified.
958	*
959	* @returns IPRT status code
960	* @param phClass Where to return the class handle.
961	* @param pSrcPos The source position of the create call.
962	* @param fAutodidact Whether the class should be allowed to teach
963	* itself new locking order rules (true), or if the
964	* user will teach it all it needs to know (false).
965	* @param fRecursionOk Whether to allow lock recursion or not.
966	* @param fStrictReleaseOrder Enforce strict lock release order or not.
967	* @param cMsMinDeadlock Used to raise the sleep interval at which
968	* deadlock detection kicks in. Minimum is 1 ms,
969	* while RT_INDEFINITE_WAIT will disable it.
970	* @param cMsMinOrder Used to raise the sleep interval at which lock
971	* order validation kicks in. Minimum is 1 ms,
972	* while RT_INDEFINITE_WAIT will disable it.
973	* @param pszNameFmt Class name format string, optional (NULL). Max
974	* length is 32 bytes.
975	* @param va Format string arguments.
976	*
977	* @remarks The properties can be modified after creation by the
978	* RTLockValidatorClassSet* methods.
979	*/
980	RTDECL(int) RTLockValidatorClassCreateExV(PRTLOCKVALCLASS phClass, PCRTLOCKVALSRCPOS pSrcPos,
981	bool fAutodidact, bool fRecursionOk, bool fStrictReleaseOrder,
982	RTMSINTERVAL cMsMinDeadlock, RTMSINTERVAL cMsMinOrder,
983	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(8, 0);
984
985	/**
986	* Creates a new lock validator class.
987	*
988	* @returns IPRT status code
989	* @param phClass Where to return the class handle.
990	* @param fAutodidact Whether the class should be allowed to teach
991	* itself new locking order rules (true), or if the
992	* user will teach it all it needs to know (false).
993	* @param SRC_POS The source position where call is being made from.
994	* Use RT_SRC_POS when possible. Optional.
995	* @param pszNameFmt Class name format string, optional (NULL). Max
996	* length is 32 bytes.
997	* @param ... Format string arguments.
998	*/
999	RTDECL(int) RTLockValidatorClassCreate(PRTLOCKVALCLASS phClass, bool fAutodidact, RT_SRC_POS_DECL,
1000	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(6, 7);
1001
1002	/**
1003	* Creates a new lock validator class with a reference that is consumed by the
1004	* first call to RTLockValidatorClassRetain.
1005	*
1006	* This is tailored for use in the parameter list of a semaphore constructor.
1007	*
1008	* @returns Class handle with a reference that is automatically consumed by the
1009	* first retainer. NIL_RTLOCKVALCLASS if we run into trouble.
1010	*
1011	* @param SRC_POS The source position where call is being made from.
1012	* Use RT_SRC_POS when possible. Optional.
1013	* @param pszNameFmt Class name format string, optional (NULL). Max
1014	* length is 32 bytes.
1015	* @param ... Format string arguments.
1016	*/
1017	RTDECL(RTLOCKVALCLASS) RTLockValidatorClassCreateUnique(RT_SRC_POS_DECL,
1018	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(4, 5);
1019
1020	/**
1021	* Finds a class for the specified source position.
1022	*
1023	* @returns A handle to the class (not retained!) or NIL_RTLOCKVALCLASS.
1024	* @param pSrcPos The source position.
1025	*/
1026	RTDECL(RTLOCKVALCLASS) RTLockValidatorClassFindForSrcPos(PRTLOCKVALSRCPOS pSrcPos);
1027
1028	/**
1029	* Finds or creates a class given the source position.
1030	*
1031	* @returns Class handle (not retained!) or NIL_RTLOCKVALCLASS.
1032	* @param SRC_POS The source position where call is being made from.
1033	* Use RT_SRC_POS when possible. Optional.
1034	* @param pszNameFmt Class name format string, optional (NULL). Max
1035	* length is 32 bytes.
1036	* @param ... Format string arguments.
1037	*/
1038	RTDECL(RTLOCKVALCLASS) RTLockValidatorClassForSrcPos(RT_SRC_POS_DECL,
1039	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(4, 5);
1040
1041	/**
1042	* Retains a reference to a lock validator class.
1043	*
1044	* @returns New reference count; UINT32_MAX if the handle is invalid.
1045	* @param hClass Handle to the class.
1046	*/
1047	RTDECL(uint32_t) RTLockValidatorClassRetain(RTLOCKVALCLASS hClass);
1048
1049	/**
1050	* Releases a reference to a lock validator class.
1051	*
1052	* @returns New reference count. 0 if hClass is NIL_RTLOCKVALCLASS. UINT32_MAX
1053	* if the handle is invalid.
1054	* @param hClass Handle to the class.
1055	*/
1056	RTDECL(uint32_t) RTLockValidatorClassRelease(RTLOCKVALCLASS hClass);
1057
1058	/**
1059	* Teaches the class @a hClass that locks in the class @a hPriorClass can be
1060	* held when taking a lock of class @a hClass
1061	*
1062	* @returns IPRT status.
1063	* @param hClass Handle to the pupil class.
1064	* @param hPriorClass Handle to the class that can be held prior to
1065	* taking a lock in the pupil class. (No reference
1066	* is consumed.)
1067	*/
1068	RTDECL(int) RTLockValidatorClassAddPriorClass(RTLOCKVALCLASS hClass, RTLOCKVALCLASS hPriorClass);
1069
1070	/**
1071	* Enables or disables the strict release order enforcing.
1072	*
1073	* @returns IPRT status.
1074	* @param hClass Handle to the class to change.
1075	* @param fEnabled Enable it (true) or disable it (false).
1076	*/
1077	RTDECL(int) RTLockValidatorClassEnforceStrictReleaseOrder(RTLOCKVALCLASS hClass, bool fEnabled);
1078
1079	/**
1080	* Enables / disables the lock validator for new locks.
1081	*
1082	* @returns The old setting.
1083	* @param fEnabled The new setting.
1084	*/
1085	RTDECL(bool) RTLockValidatorSetEnabled(bool fEnabled);
1086
1087	/**
1088	* Is the lock validator enabled?
1089	*
1090	* @returns True if enabled, false if not.
1091	*/
1092	RTDECL(bool) RTLockValidatorIsEnabled(void);
1093
1094	/**
1095	* Controls whether the lock validator should be quiet or noisy (default).
1096	*
1097	* @returns The old setting.
1098	* @param fQuiet The new setting.
1099	*/
1100	RTDECL(bool) RTLockValidatorSetQuiet(bool fQuiet);
1101
1102	/**
1103	* Is the lock validator quiet or noisy?
1104	*
1105	* @returns True if it is quiet, false if noisy.
1106	*/
1107	RTDECL(bool) RTLockValidatorIsQuiet(void);
1108
1109	/**
1110	* Makes the lock validator panic (default) or not.
1111	*
1112	* @returns The old setting.
1113	* @param fPanic The new setting.
1114	*/
1115	RTDECL(bool) RTLockValidatorSetMayPanic(bool fPanic);
1116
1117	/**
1118	* Can the lock validator cause panic.
1119	*
1120	* @returns True if it can, false if not.
1121	*/
1122	RTDECL(bool) RTLockValidatorMayPanic(void);
1123
1124
1125	RT_C_DECLS_END
1126
1127	/** @} */
1128
1129	#endif
1130

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

source: vbox/trunk/include/iprt/lockvalidator.h@ 62021

Download in other formats: