lockvalidator.h revision 2805b95732a8d26015a397626b96049a6e6573e7
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * IPRT - Lock Validator.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * Copyright (C) 2009 Sun Microsystems, Inc.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * available from http://www.virtualbox.org. This file is free software;
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * you can redistribute it and/or modify it under the terms of the GNU
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * General Public License (GPL) as published by the Free Software
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * The contents of this file may alternatively be used under the terms
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * of the Common Development and Distribution License Version 1.0
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * VirtualBox OSE distribution, in which case the provisions of the
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * CDDL are applicable instead of those of the GPL.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * You may elect to license modified versions of this file under the
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * terms and conditions of either the GPL or the CDDL or both.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * additional information or have any questions.
88acfa6629a7976c0583c1712d2b5b22a87a5121vboxsync/** @defgroup grp_rtlockval RTLockValidator - Lock Validator
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @ingroup grp_rt
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync/** Pointer to a record union.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * @internal */
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsynctypedef union RTLOCKVALRECUNION *PRTLOCKVALRECUNION;
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * Source position.
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The file where the lock was taken. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The function where the lock was taken. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Some ID indicating where the lock was taken, typically an address. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The line number in the file. */
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsyncAssertCompileSize(RTLOCKVALSRCPOS, HC_ARCH_BITS == 32 ? 16 : 32);
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync/* The pointer types are defined in iprt/types.h. */
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync/** @def RTLOCKVALSRCPOS_INIT
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync * Initializer for a RTLOCKVALSRCPOS variable.
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * @param pszFile The file name. Optional (NULL).
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * @param uLine The line number in that file. Optional (0).
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * @param pszFunction The function. Optional (NULL).
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * @param uId Some location ID, normally the return address.
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * Optional (NULL).
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync# define RTLOCKVALSRCPOS_INIT(pszFile, uLine, pszFunction, uId) \
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync# define RTLOCKVALSRCPOS_INIT(pszFile, uLine, pszFunction, uId) \
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync/** @def RTLOCKVALSRCPOS_INIT_DEBUG_API
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync * Initializer for a RTLOCKVALSRCPOS variable in a typicial debug API
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * variant. Assumes RT_SRC_POS_DECL and RTHCUINTPTR uId as arguments.
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync RTLOCKVALSRCPOS_INIT(pszFile, iLine, pszFunction, uId)
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync/** @def RTLOCKVALSRCPOS_INIT_NORMAL_API
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync * Initializer for a RTLOCKVALSRCPOS variable in a normal API
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * variant. Assumes iprt/asm.h is included.
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync RTLOCKVALSRCPOS_INIT(__FILE__, __LINE__, __PRETTY_FUNCTION__, (uintptr_t)ASMReturnAddress())
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync/** @def RTLOCKVALSRCPOS_INIT_POS_NO_ID
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * Initializer for a RTLOCKVALSRCPOS variable when no @c uId is present.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * Assumes iprt/asm.h is included.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync RTLOCKVALSRCPOS_INIT(pszFile, iLine, pszFunction, (uintptr_t)ASMReturnAddress())
8077a3fb4024022d405598797d3ed75c667a912fvboxsync/** Pointer to a record of one ownership share. */
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * Lock validator record core.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync /** The magic value indicating the record type. */
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync/** Pointer to a lock validator record core. */
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync/** Pointer to a const lock validator record core. */
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync * Record recording the exclusive ownership of a lock.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * This is typically part of the per-lock data structure when compiling with
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * the lock validator.
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync /** Record core with RTLOCKVALRECEXCL_MAGIC as the magic value. */
c0ae9fb031e70c0e5f4098a46ab11262097c88f9vboxsync /** Whether it's enabled or not. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Reserved. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Source position where the lock was taken. */
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync /** The current owner thread. */
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync /** Pointer to the lock record below us. Only accessed by the owner. */
a2b66e2b8b92cf2d0706078798036035cb9fa94dvboxsync /** Recursion count */
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync /** The lock sub-class. */
a2b66e2b8b92cf2d0706078798036035cb9fa94dvboxsync /** The lock class. */
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync /** Pointer to the lock. */
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync /** The lock name. */
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync /** Pointer to the next sibling record.
8077a3fb4024022d405598797d3ed75c667a912fvboxsync * This is used to find the read side of a read-write lock. */
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsyncAssertCompileSize(RTLOCKVALRECEXCL, HC_ARCH_BITS == 32 ? 8 + 16 + 32 : 8 + 32 + 56);
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync/* The pointer type is defined in iprt/types.h. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * For recording the one ownership share.
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync /** Record core with RTLOCKVALRECSHRDOWN_MAGIC as the magic value. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Recursion count */
3cd31efc45d9b3b5118748be299da2f298307cddvboxsync /** Static (true) or dynamic (false) allocated record. */
3cd31efc45d9b3b5118748be299da2f298307cddvboxsync /** Reserved. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The current owner thread. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Pointer to the lock record below us. Only accessed by the owner. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Pointer back to the shared record. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Reserved. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Source position where the lock was taken. */
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsyncAssertCompileSize(RTLOCKVALRECSHRDOWN, HC_ARCH_BITS == 32 ? 24 + 16 : 32 + 32);
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync/** Pointer to a RTLOCKVALRECSHRDOWN. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * Record recording the shared ownership of a lock.
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * This is typically part of the per-lock data structure when compiling with
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * the lock validator.
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync /** Record core with RTLOCKVALRECSHRD_MAGIC as the magic value. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The lock sub-class. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The lock class. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Pointer to the lock. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The lock name. */
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync /** Pointer to the next sibling record.
8077a3fb4024022d405598797d3ed75c667a912fvboxsync * This is used to find the write side of a read-write lock. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The number of entries in the table.
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * Updated before inserting and after removal. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The index of the last entry (approximately). */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** The max table size. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Set if the table is being reallocated, clear if not.
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * This is used together with rtLockValidatorSerializeDetectionEnter to make
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * sure there is exactly one thread doing the reallocation and that nobody is
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * using the table at that point. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync bool volatile fReallocating;
c0ae9fb031e70c0e5f4098a46ab11262097c88f9vboxsync /** Whether it's enabled or not. */
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync /** Set if event semaphore signaller, clear if read-write semaphore. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Alignment padding. */
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Pointer to a table containing pointers to records of all the owners. */
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync R3R0PTRTYPE(PRTLOCKVALRECSHRDOWN volatile *) papOwners;
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync /** Alignment padding. */
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsyncAssertCompileSize(RTLOCKVALRECSHRD, HC_ARCH_BITS == 32 ? 24 + 20 + 4 : 40 + 24);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Makes the two records siblings.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @returns VINF_SUCCESS on success, VERR_SEM_LV_INVALID_PARAMETER if either of
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * the records are invalid.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec1 Record 1.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec2 Record 2.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecMakeSiblings(PRTLOCKVALRECCORE pRec1, PRTLOCKVALRECCORE pRec2);
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * Initialize a lock validator record.
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync * Use RTLockValidatorRecExclDelete to deinitialize it.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param pRec The record.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param hClass The class (no reference consumed). If NIL, the
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * no lock order validation will be performed on
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * this lock.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param uSubClass The sub-class. This is used to define lock
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * order inside the same class. If you don't know,
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * then pass RTLOCKVAL_SUB_CLASS_NONE.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param pszName The lock name (optional).
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param hLock The lock handle.
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * @param fEnabled Pass @c false to explicitly disable lock
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * validation, otherwise @c true.
2805b95732a8d26015a397626b96049a6e6573e7vboxsyncRTDECL(void) RTLockValidatorRecExclInit(PRTLOCKVALRECEXCL pRec, RTLOCKVALCLASS hClass, uint32_t uSubClass,
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * Uninitialize a lock validator record previously initialized by
cb5363b6fa48f10b080cb6195f56c0823f7c0b0fvboxsync * RTLockRecValidatorInit.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param pRec The record. Must be valid.
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsyncRTDECL(void) RTLockValidatorRecExclDelete(PRTLOCKVALRECEXCL pRec);
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * Create and initialize a lock validator record.
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync * Use RTLockValidatorRecExclDestroy to deinitialize and destroy the returned
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @return VINF_SUCCESS or VERR_NO_MEMORY.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param ppRec Where to return the record pointer.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param hClass The class (no reference consumed). If NIL, the
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * no lock order validation will be performed on
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * this lock.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param uSubClass The sub-class. This is used to define lock
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * order inside the same class. If you don't know,
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * then pass RTLOCKVAL_SUB_CLASS_NONE.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param pszName The lock name (optional).
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param hLock The lock handle.
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * @param fEnabled Pass @c false to explicitly disable lock
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * validation, otherwise @c true.
2805b95732a8d26015a397626b96049a6e6573e7vboxsyncRTDECL(int) RTLockValidatorRecExclCreate(PRTLOCKVALRECEXCL *ppRec, RTLOCKVALCLASS hClass, uint32_t uSubClass,
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync * Deinitialize and destroy a record created by RTLockValidatorRecExclCreate.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param ppRec Pointer to the record pointer. Will be set to
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsyncRTDECL(void) RTLockValidatorRecExclDestroy(PRTLOCKVALRECEXCL *ppRec);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Record the specified thread as lock owner and increment the write lock count.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * This function is typically called after acquiring the lock. It accounts for
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * recursions so it can be used instead of RTLockValidatorRecExclRecursion. Use
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * RTLockValidatorRecExclReleaseOwner to reverse the effect.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param hThreadSelf The handle of the calling thread. If not known,
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * pass NIL_RTTHREAD and we'll figure it out.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pSrcPos The source position of the lock operation.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param fFirstRecursion Set if it is the first recursion, clear if not
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(void) RTLockValidatorRecExclSetOwner(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf,
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Check the exit order and release (unset) the ownership.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * This is called by routines implementing releasing an exclusive lock,
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * typically before getting down to the final lock releaseing. Can be used for
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * recursive releasing instead of RTLockValidatorRecExclUnwind.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @retval VINF_SUCCESS on success.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the order is wrong. Will have
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * done all necessary whining and breakpointing before returning.
08870164da59f90379b1ea9b5a2476296c362217vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param pRec The validator record.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param fFinalRecursion Set if it's the final recursion, clear if not
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecExclReleaseOwner(PRTLOCKVALRECEXCL pRec, bool fFinalRecursion);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Clear the lock ownership and decrement the write lock count.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * This is only for special cases where we wish to drop lock validation
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * recording. See RTLockValidatorRecExclCheckAndRelease.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(void) RTLockValidatorRecExclReleaseOwnerUnchecked(PRTLOCKVALRECEXCL pRec);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Checks and records a lock recursion.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VINF_SUCCESS on success.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_NESTED if the semaphore class forbids recursion. Gone
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * thru the motions.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_WRONG_ORDER if the locking order is wrong. Gone thru
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * the motions.
2f8244f574b4b9f99af99b7472984f3e60ea93d0vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record.
2f8244f574b4b9f99af99b7472984f3e60ea93d0vboxsync * @param pSrcPos The source position of the lock operation.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecExclRecursion(PRTLOCKVALRECEXCL pRec, PCRTLOCKVALSRCPOS pSrcPos);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Checks and records a lock unwind (releasing one recursion).
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * This should be coupled with called to RTLockValidatorRecExclRecursion.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VINF_SUCCESS on success.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the release order is wrong. Gone
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * thru the motions.
2f8244f574b4b9f99af99b7472984f3e60ea93d0vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecExclUnwind(PRTLOCKVALRECEXCL pRec);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Checks and records a mixed recursion.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * An example of a mixed recursion is a writer requesting read access to a
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * This should be coupled with called to RTLockValidatorRecExclUnwindMixed.
c68a3984216eaa85ae7144b3b0d9b168276dbcf3vboxsync * @retval VINF_SUCCESS on success.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_NESTED if the semaphore class forbids recursion. Gone
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * thru the motions.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_WRONG_ORDER if the locking order is wrong. Gone thru
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * the motions.
08870164da59f90379b1ea9b5a2476296c362217vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record it to accounted it to.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRecMixed The validator record it came in on.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pSrcPos The source position of the lock operation.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecExclRecursionMixed(PRTLOCKVALRECEXCL pRec, PRTLOCKVALRECCORE pRecMixed, PCRTLOCKVALSRCPOS pSrcPos);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Checks and records the unwinding of a mixed recursion.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * This should be coupled with called to RTLockValidatorRecExclRecursionMixed.
2f8244f574b4b9f99af99b7472984f3e60ea93d0vboxsync * @retval VINF_SUCCESS on success.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the release order is wrong. Gone
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * thru the motions.
2f8244f574b4b9f99af99b7472984f3e60ea93d0vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record it was accounted to.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRecMixed The validator record it came in on.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecExclUnwindMixed(PRTLOCKVALRECEXCL pRec, PRTLOCKVALRECCORE pRecMixed);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Check the exclusive locking order.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * This is called by routines implementing exclusive lock acquisition.
08870164da59f90379b1ea9b5a2476296c362217vboxsync * @retval VINF_SUCCESS on success.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_WRONG_ORDER if the order is wrong. Will have done all
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * necessary whining and breakpointing before returning.
08870164da59f90379b1ea9b5a2476296c362217vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
c68a3984216eaa85ae7144b3b0d9b168276dbcf3vboxsync * @param pRec The validator record.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param hThreadSelf The handle of the calling thread. If not known,
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * pass NIL_RTTHREAD and we'll figure it out.
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * @param pSrcPos The source position of the lock operation.
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * @param cMillies The timeout, in milliseconds.
2805b95732a8d26015a397626b96049a6e6573e7vboxsyncRTDECL(int) RTLockValidatorRecExclCheckOrder(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf,
c364b6c44a252ab65b514fa8f9a665cc5e33a1cevboxsync * Do deadlock detection before blocking on exclusive access to a lock and
c364b6c44a252ab65b514fa8f9a665cc5e33a1cevboxsync * change the thread state.
c364b6c44a252ab65b514fa8f9a665cc5e33a1cevboxsync * @retval VINF_SUCCESS - thread is in the specified sleep state.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_DEADLOCK if blocking would deadlock. Gone thru the
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_NESTED if the semaphore isn't recursive and hThread is
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * already the owner. Gone thru the motions.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_ILLEGAL_UPGRADE if it's a deadlock on the same lock.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * The caller must handle any legal upgrades without invoking this
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * function (for now).
2f8244f574b4b9f99af99b7472984f3e60ea93d0vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record we're blocking on.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD!
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pSrcPos The source position of the lock operation.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param fRecursiveOk Whether it's ok to recurse.
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * @param cMillies The timeout, in milliseconds.
c364b6c44a252ab65b514fa8f9a665cc5e33a1cevboxsync * @param enmSleepState The sleep state to enter on successful return.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param fReallySleeping Is it really going to sleep now or not. Use
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * false before calls to other IPRT synchronization
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecExclCheckBlocking(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf,
2805b95732a8d26015a397626b96049a6e6573e7vboxsync PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk, RTMSINTERVAL cMillies,
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync RTTHREADSTATE enmSleepState, bool fReallySleeping);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * RTLockValidatorRecExclCheckOrder and RTLockValidatorRecExclCheckBlocking
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * baked into one call.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @returns Any of the statuses returned by the two APIs.
08870164da59f90379b1ea9b5a2476296c362217vboxsync * @param pRec The validator record.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD!
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pSrcPos The source position of the lock operation.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param fRecursiveOk Whether it's ok to recurse.
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * @param cMillies The timeout, in milliseconds.
c364b6c44a252ab65b514fa8f9a665cc5e33a1cevboxsync * @param enmSleepState The sleep state to enter on successful return.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param fReallySleeping Is it really going to sleep now or not. Use
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * false before calls to other IPRT synchronization
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecExclCheckOrderAndBlocking(PRTLOCKVALRECEXCL pRec, RTTHREAD hThreadSelf,
2805b95732a8d26015a397626b96049a6e6573e7vboxsync PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk, RTMSINTERVAL cMillies,
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync RTTHREADSTATE enmSleepState, bool fReallySleeping);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Initialize a lock validator record for a shared lock.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Use RTLockValidatorRecSharedDelete to deinitialize it.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The shared lock record.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param hClass The class (no reference consumed). If NIL, the
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * no lock order validation will be performed on
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * this lock.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param uSubClass The sub-class. This is used to define lock
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * order inside the same class. If you don't know,
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * then pass RTLOCKVAL_SUB_CLASS_NONE.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pszName The lock name (optional).
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param hLock The lock handle.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param fSignaller Set if event semaphore signaller logic should be
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * applied to this record, clear if read-write
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * semaphore logic should be used.
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * @param fEnabled Pass @c false to explicitly disable lock
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * validation, otherwise @c true.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsyncRTDECL(void) RTLockValidatorRecSharedInit(PRTLOCKVALRECSHRD pRec, RTLOCKVALCLASS hClass, uint32_t uSubClass,
2805b95732a8d26015a397626b96049a6e6573e7vboxsync const char *pszName, void *hLock, bool fSignaller, bool fEnabled);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Uninitialize a lock validator record previously initialized by
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * RTLockValidatorRecSharedInit.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The shared lock record. Must be valid.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(void) RTLockValidatorRecSharedDelete(PRTLOCKVALRECSHRD pRec);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Check the shared locking order.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * This is called by routines implementing shared lock acquisition.
2f8244f574b4b9f99af99b7472984f3e60ea93d0vboxsync * @retval VINF_SUCCESS on success.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_WRONG_ORDER if the order is wrong. Will have done all
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * necessary whining and breakpointing before returning.
2f8244f574b4b9f99af99b7472984f3e60ea93d0vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param hThreadSelf The handle of the calling thread. If not known,
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * pass NIL_RTTHREAD and we'll figure it out.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pSrcPos The source position of the lock operation.
2805b95732a8d26015a397626b96049a6e6573e7vboxsyncRTDECL(int) RTLockValidatorRecSharedCheckOrder(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf,
c364b6c44a252ab65b514fa8f9a665cc5e33a1cevboxsync * Do deadlock detection before blocking on shared access to a lock and change
c364b6c44a252ab65b514fa8f9a665cc5e33a1cevboxsync * the thread state.
c364b6c44a252ab65b514fa8f9a665cc5e33a1cevboxsync * @retval VINF_SUCCESS - thread is in the specified sleep state.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_DEADLOCK if blocking would deadlock. Gone thru the
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_NESTED if the semaphore isn't recursive and hThread is
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * already the owner. Gone thru the motions.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_ILLEGAL_UPGRADE if it's a deadlock on the same lock.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * The caller must handle any legal upgrades without invoking this
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * function (for now).
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record we're blocking on.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD!
4b0369e0c9bcae37f2801e0f7b92509bbbaf4becvboxsync * @param pSrcPos The source position of the lock operation.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param fRecursiveOk Whether it's ok to recurse.
c364b6c44a252ab65b514fa8f9a665cc5e33a1cevboxsync * @param enmSleepState The sleep state to enter on successful return.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param fReallySleeping Is it really going to sleep now or not. Use
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * false before calls to other IPRT synchronization
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecSharedCheckBlocking(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf,
2805b95732a8d26015a397626b96049a6e6573e7vboxsync PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk, RTMSINTERVAL cMillies,
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync RTTHREADSTATE enmSleepState, bool fReallySleeping);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * RTLockValidatorRecSharedCheckOrder and RTLockValidatorRecSharedCheckBlocking
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * baked into one call.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @returns Any of the statuses returned by the two APIs.
5d1fc7f6c660e826d7f81c580fbf4278dd44c6bdvboxsync * @param pRec The validator record.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param hThreadSelf The current thread. Shall not be NIL_RTTHREAD!
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pSrcPos The source position of the lock operation.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param fRecursiveOk Whether it's ok to recurse.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param enmSleepState The sleep state to enter on successful return.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param fReallySleeping Is it really going to sleep now or not. Use
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * false before calls to other IPRT synchronization
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecSharedCheckOrderAndBlocking(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf,
2805b95732a8d26015a397626b96049a6e6573e7vboxsync PCRTLOCKVALSRCPOS pSrcPos, bool fRecursiveOk, RTMSINTERVAL cMillies,
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync RTTHREADSTATE enmSleepState, bool fReallySleeping);
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * Removes all current owners and makes hThread the only owner.
88acfa6629a7976c0583c1712d2b5b22a87a5121vboxsync * @param pRec The validator record.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param hThread The thread handle of the owner. NIL_RTTHREAD is
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * an alias for the current thread.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param pSrcPos The source position of the lock operation.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsyncRTDECL(void) RTLockValidatorRecSharedResetOwner(PRTLOCKVALRECSHRD pRec, RTTHREAD hThread, PCRTLOCKVALSRCPOS pSrcPos);
f73c807e7ef6a1a6c10ec5cd9b36ee835cfaa241vboxsync * Adds an owner to a shared locking record.
f73c807e7ef6a1a6c10ec5cd9b36ee835cfaa241vboxsync * Takes recursion into account. This function is typically called after
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * acquiring the lock in shared mode.
88acfa6629a7976c0583c1712d2b5b22a87a5121vboxsync * @param pRec The validator record.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param hThread The thread handle of the owner. NIL_RTTHREAD is
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * an alias for the current thread.
f73c807e7ef6a1a6c10ec5cd9b36ee835cfaa241vboxsync * @param pSrcPos The source position of the lock operation.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsyncRTDECL(void) RTLockValidatorRecSharedAddOwner(PRTLOCKVALRECSHRD pRec, RTTHREAD hThread, PCRTLOCKVALSRCPOS pSrcPos);
f73c807e7ef6a1a6c10ec5cd9b36ee835cfaa241vboxsync * Removes an owner from a shared locking record.
f73c807e7ef6a1a6c10ec5cd9b36ee835cfaa241vboxsync * Takes recursion into account. This function is typically called before
f73c807e7ef6a1a6c10ec5cd9b36ee835cfaa241vboxsync * releaseing the lock.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @param pRec The validator record.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param hThread The thread handle of the owner. NIL_RTTHREAD is
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * an alias for the current thread.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsyncRTDECL(void) RTLockValidatorRecSharedRemoveOwner(PRTLOCKVALRECSHRD pRec, RTTHREAD hThread);
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * Check the exit order and release (unset) the shared ownership.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * This is called by routines implementing releasing the read/write lock.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VINF_SUCCESS on success.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_WRONG_RELEASE_ORDER if the order is wrong. Will have
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * done all necessary whining and breakpointing before returning.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param pRec The validator record.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param hThreadSelf The handle of the calling thread. NIL_RTTHREAD
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * is an alias for the current thread.
e75313c24325ec7bec84fa349abb39e246b6cc86vboxsyncRTDECL(int) RTLockValidatorRecSharedCheckAndRelease(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf);
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * Check the signaller of an event.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * This is called by routines implementing releasing the event sempahore (both
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @retval VINF_SUCCESS on success.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @retval VERR_SEM_LV_NOT_SIGNALLER if the thread is not in the record. Will
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * have done all necessary whining and breakpointing before returning.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @retval VERR_SEM_LV_INVALID_PARAMETER if the input is invalid.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param pRec The validator record.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * @param hThreadSelf The handle of the calling thread. NIL_RTTHREAD
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsync * is an alias for the current thread.
0fcf82b2591711fa8980e8f5d9cad1b8f222d6d7vboxsyncRTDECL(int) RTLockValidatorRecSharedCheckSignaller(PRTLOCKVALRECSHRD pRec, RTTHREAD hThreadSelf);
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * Gets the number of write locks and critical sections the specified
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * thread owns.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * This number does not include any nested lock/critect entries.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * Note that it probably will return 0 for non-strict builds since
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * release builds doesn't do unnecessary diagnostic counting like this.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * @returns Number of locks on success (0+) and VERR_INVALID_HANDLER on failure
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * @param Thread The thread we're inquiring about.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * @remarks Will only work for strict builds.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsyncRTDECL(int32_t) RTLockValidatorWriteLockGetCount(RTTHREAD Thread);
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * Works the THREADINT::cWriteLocks member, mostly internal.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * @param Thread The current thread.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsyncRTDECL(void) RTLockValidatorWriteLockInc(RTTHREAD Thread);
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * Works the THREADINT::cWriteLocks member, mostly internal.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * @param Thread The current thread.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsyncRTDECL(void) RTLockValidatorWriteLockDec(RTTHREAD Thread);
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * Gets the number of read locks the specified thread owns.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * Note that nesting read lock entry will be included in the
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * total sum. And that it probably will return 0 for non-strict
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * builds since release builds doesn't do unnecessary diagnostic
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * counting like this.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * @returns Number of read locks on success (0+) and VERR_INVALID_HANDLER on failure
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * @param Thread The thread we're inquiring about.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsyncRTDECL(int32_t) RTLockValidatorReadLockGetCount(RTTHREAD Thread);
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * Works the THREADINT::cReadLocks member.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * @param Thread The current thread.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsyncRTDECL(void) RTLockValidatorReadLockInc(RTTHREAD Thread);
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * Works the THREADINT::cReadLocks member.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsync * @param Thread The current thread.
f0dd841cb99154da8ec0a31cae2f89044895a23fvboxsyncRTDECL(void) RTLockValidatorReadLockDec(RTTHREAD Thread);
ff3996360d63d42b188c1696d4760641a7762ce9vboxsync * Query which lock the specified thread is waiting on.
ff3996360d63d42b188c1696d4760641a7762ce9vboxsync * @returns The lock handle value or NULL.
ff3996360d63d42b188c1696d4760641a7762ce9vboxsync * @param hThread The thread in question.
ff3996360d63d42b188c1696d4760641a7762ce9vboxsyncRTDECL(void *) RTLockValidatorQueryBlocking(RTTHREAD hThread);
4f01cec078ae67d28fea17a1f5f4511fe8090a62vboxsync * Checks if the thread is running in the lock validator after it has entered a
4f01cec078ae67d28fea17a1f5f4511fe8090a62vboxsync * block state.
4f01cec078ae67d28fea17a1f5f4511fe8090a62vboxsync * @returns true if it is, false if it isn't.
4f01cec078ae67d28fea17a1f5f4511fe8090a62vboxsync * @param hThread The thread in question.
4f01cec078ae67d28fea17a1f5f4511fe8090a62vboxsyncRTDECL(bool) RTLockValidatorIsBlockedThreadInValidator(RTTHREAD hThread);
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * Creates a new lock validator class, all properties specified.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @returns IPRT status code
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param phClass Where to return the class handle.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param pSrcPos The source position of the create call.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param fAutodidact Whether the class should be allowed to teach
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * itself new locking order rules (true), or if the
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * user will teach it all it needs to know (false).
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * @param fRecursionOk Whether to allow lock recursion or not.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param cMsMinDeadlock Used to raise the sleep interval at which
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * deadlock detection kicks in. Minimum is 1 ms,
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * while RT_INDEFINITE_WAIT will disable it.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param cMsMinOrder Used to raise the sleep interval at which lock
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * order validation kicks in. Minimum is 1 ms,
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * while RT_INDEFINITE_WAIT will disable it.
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * @remarks The properties can be modified after creation by the
2805b95732a8d26015a397626b96049a6e6573e7vboxsync * RTLockValidatorClassSet* methods.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsyncRTDECL(int) RTLockValidatorClassCreateEx(PRTLOCKVALCLASS phClass, PCRTLOCKVALSRCPOS pSrcPos,
2805b95732a8d26015a397626b96049a6e6573e7vboxsync RTMSINTERVAL cMsMinDeadlock, RTMSINTERVAL cMsMinOrder);
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * Creates a new lock validator class.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @returns IPRT status code
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param phClass Where to return the class handle.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param fAutodidact Whether the class should be allowed to teach
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * itself new locking order rules (true), or if the
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * user will teach it all it needs to know (false).
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param pszFile The source position of the call, file.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param iLine The source position of the call, line.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param pszFunction The source position of the call, function.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsyncRTDECL(int) RTLockValidatorClassCreate(PRTLOCKVALCLASS phClass, bool fAutodidact, RT_SRC_POS_DECL);
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * Finds a class for the specified source position.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @returns A handle to the class (not retained!) or NIL_RTLOCKVALCLASS.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param pSrcPos The source position.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsyncRTDECL(RTLOCKVALCLASS) RTLockValidatorClassFindForSrcPos(PRTLOCKVALSRCPOS pSrcPos);
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * Finds or creates a class given the source position.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @returns Class handle (not retained!) or NIL_RTLOCKVALCLASS.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param pszFile The source file.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param iLine The line in that source file.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param pszFunction The function name.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsyncRTDECL(RTLOCKVALCLASS) RTLockValidatorClassForSrcPos(RT_SRC_POS_DECL);
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * Retains a reference to a lock validator class.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @returns New reference count; UINT32_MAX if the handle is invalid.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param hClass Handle to the class.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsyncRTDECL(uint32_t) RTLockValidatorClassRetain(RTLOCKVALCLASS hClass);
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * Releases a reference to a lock validator class.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @returns New reference count; UINT32_MAX if the handle is invalid.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param hClass Handle to the class.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsyncRTDECL(uint32_t) RTLockValidatorClassRelease(RTLOCKVALCLASS hClass);
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * Teaches the class @a hClass that locks in the class @a hPriorClass can be
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * held when taking a lock of class @hClass
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @returns IPRT status.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param hClass Handle to the pupil class.
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * @param hPriorClass Handle to the class that can be held prior to
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * taking a lock in the pupil class. (No reference
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync * is consumed.)
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsyncRTDECL(int) RTLockValidatorClassAddPriorClass(RTLOCKVALCLASS hClass, RTLOCKVALCLASS hPriorClass);
c0ae9fb031e70c0e5f4098a46ab11262097c88f9vboxsync * Enables / disables the lock validator for new locks.
c0ae9fb031e70c0e5f4098a46ab11262097c88f9vboxsync * @returns The old setting.
c0ae9fb031e70c0e5f4098a46ab11262097c88f9vboxsync * @param fEnabled The new setting.
c0ae9fb031e70c0e5f4098a46ab11262097c88f9vboxsyncRTDECL(bool) RTLockValidatorSetEnabled(bool fEnabled);
c0ae9fb031e70c0e5f4098a46ab11262097c88f9vboxsync * Is the lock validator enabled?
c0ae9fb031e70c0e5f4098a46ab11262097c88f9vboxsync * @returns True if enabled, false if not.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * Controls whether the lock validator should be quiet or noisy (default).
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * @returns The old setting.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * @param fQuiet The new setting.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * Is the lock validator quiet or noisy?
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * @returns True if it is quiet, false if noisy.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * Makes the lock validator panic (default) or not.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * @returns The old setting.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * @param fPanic The new setting.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsyncRTDECL(bool) RTLockValidatorSetMayPanic(bool fPanic);
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * Can the lock validator cause panic.
2b14f26c96a20e40e9a0c9e3c41b41315f6c6e96vboxsync * @returns True if it can, false if not.