VirtualBox

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

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

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