lockvalidator.h@ 95897

Last change on this file since 95897 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 49.2 KB

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

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

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

Download in other formats: