VirtualBox

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

Last change on this file since 57926 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
41RT_C_DECLS_BEGIN
42
43/** Pointer to a record union.
44 * @internal */
45typedef union RTLOCKVALRECUNION *PRTLOCKVALRECUNION;
46
47/**
48 * Source position.
49 */
50typedef 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;
64AssertCompileSize(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 */
109typedef 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. */
115typedef RTLOCKVALRECCORE *PRTLOCKVALRECCORE;
116/** Pointer to a const lock validator record core. */
117typedef 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 */
126typedef 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;
156AssertCompileSize(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 */
162typedef 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;
185AssertCompileSize(RTLOCKVALRECSHRDOWN, HC_ARCH_BITS == 32 ? 24 + 16 : 32 + 32);
186/** Pointer to a RTLOCKVALRECSHRDOWN. */
187typedef 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 */
195typedef 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;
235AssertCompileSize(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 */
246RTDECL(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 */
267RTDECL(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 */
288RTDECL(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 */
296RTDECL(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 */
319RTDECL(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 */
343RTDECL(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 */
352RTDECL(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 */
366RTDECL(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 */
382RTDECL(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 */
401RTDECL(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 */
411RTDECL(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 */
426RTDECL(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 */
440RTDECL(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 */
461RTDECL(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 */
476RTDECL(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 */
494RTDECL(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 */
521RTDECL(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 */
540RTDECL(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 */
566RTDECL(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 */
592RTDECL(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 */
602RTDECL(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 */
628RTDECL(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 */
656RTDECL(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 */
666RTDECL(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 */
680RTDECL(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 */
698RTDECL(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 */
725RTDECL(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 */
744RTDECL(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 */
756RTDECL(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 */
769RTDECL(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 */
781RTDECL(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 */
792RTDECL(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 */
808RTDECL(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 */
825RTDECL(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 */
840RTDECL(int32_t) RTLockValidatorWriteLockGetCount(RTTHREAD Thread);
841
842/**
843 * Works the THREADINT::cWriteLocks member, mostly internal.
844 *
845 * @param Thread The current thread.
846 */
847RTDECL(void) RTLockValidatorWriteLockInc(RTTHREAD Thread);
848
849/**
850 * Works the THREADINT::cWriteLocks member, mostly internal.
851 *
852 * @param Thread The current thread.
853 */
854RTDECL(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 */
867RTDECL(int32_t) RTLockValidatorReadLockGetCount(RTTHREAD Thread);
868
869/**
870 * Works the THREADINT::cReadLocks member.
871 *
872 * @param Thread The current thread.
873 */
874RTDECL(void) RTLockValidatorReadLockInc(RTTHREAD Thread);
875
876/**
877 * Works the THREADINT::cReadLocks member.
878 *
879 * @param Thread The current thread.
880 */
881RTDECL(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 */
889RTDECL(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 */
898RTDECL(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 */
910RTDECL(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 */
923RTDECL(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 */
951RTDECL(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 */
980RTDECL(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 */
999RTDECL(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 */
1017RTDECL(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 */
1026RTDECL(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 */
1038RTDECL(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 */
1047RTDECL(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 */
1056RTDECL(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 */
1068RTDECL(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 */
1077RTDECL(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 */
1085RTDECL(bool) RTLockValidatorSetEnabled(bool fEnabled);
1086
1087/**
1088 * Is the lock validator enabled?
1089 *
1090 * @returns True if enabled, false if not.
1091 */
1092RTDECL(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 */
1100RTDECL(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 */
1107RTDECL(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 */
1115RTDECL(bool) RTLockValidatorSetMayPanic(bool fPanic);
1116
1117/**
1118 * Can the lock validator cause panic.
1119 *
1120 * @returns True if it can, false if not.
1121 */
1122RTDECL(bool) RTLockValidatorMayPanic(void);
1123
1124
1125RT_C_DECLS_END
1126
1127/** @} */
1128
1129#endif
1130
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette