prolock.h (4643B)
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #ifndef prolock_h___ 7 #define prolock_h___ 8 9 #include "prtypes.h" 10 11 PR_BEGIN_EXTERN_C 12 13 /* 14 ** A locking mechanism, built on the existing PRLock definition, 15 ** is provided that will permit applications to define a Lock 16 ** Hierarchy (or Lock Ordering) schema. An application designed 17 ** using the Ordered Lock functions will terminate with a 18 ** diagnostic message when a lock inversion condition is 19 ** detected. 20 ** 21 ** The lock ordering detection is compile-time enabled only. In 22 ** optimized builds of NSPR, the Ordered Lock functions map 23 ** directly to PRLock functions, providing no lock order 24 ** detection. 25 ** 26 ** The Ordered Lock Facility is compiled in when DEBUG is defined at 27 ** compile-time. Ordered Lock can be forced on in optimized builds by 28 ** defining FORCE_NSPR_ORDERED_LOCK at compile-time. Both the 29 ** application using Ordered Lock and NSPR must be compiled with the 30 ** facility enabled to achieve the desired results. 31 ** 32 ** Application designers should use the macro interfaces to the Ordered 33 ** Lock facility to ensure that it is compiled out in optimized builds. 34 ** 35 ** Application designers are responsible for defining their own 36 ** lock hierarchy. 37 ** 38 ** Ordered Lock is thread-safe and SMP safe. 39 ** 40 ** See Also: prlock.h 41 ** 42 ** /lth. 10-Jun-1998. 43 ** 44 */ 45 46 /* 47 ** Opaque type for ordered lock. 48 ** ... Don't even think of looking in here. 49 ** 50 */ 51 52 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 53 typedef void * PROrderedLock; 54 #else 55 /* 56 ** Map PROrderedLock and methods onto PRLock when ordered locking 57 ** is not compiled in. 58 ** 59 */ 60 #include "prlock.h" 61 62 typedef PRLock PROrderedLock; 63 #endif 64 65 /* ----------------------------------------------------------------------- 66 ** FUNCTION: PR_CreateOrderedLock() -- Create an Ordered Lock 67 ** 68 ** DESCRIPTION: PR_CreateOrderedLock() creates an ordered lock. 69 ** 70 ** INPUTS: 71 ** order: user defined order of this lock. 72 ** name: name of the lock. For debugging purposes. 73 ** 74 ** OUTPUTS: returned 75 ** 76 ** RETURNS: PR_OrderedLock pointer 77 ** 78 ** RESTRICTIONS: 79 ** 80 */ 81 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 82 #define PR_CREATE_ORDERED_LOCK(order,name)\ 83 PR_CreateOrderedLock((order),(name)) 84 #else 85 #define PR_CREATE_ORDERED_LOCK(order) PR_NewLock() 86 #endif 87 88 NSPR_API(PROrderedLock *) 89 PR_CreateOrderedLock( 90 PRInt32 order, 91 const char *name 92 ); 93 94 /* ----------------------------------------------------------------------- 95 ** FUNCTION: PR_DestroyOrderedLock() -- Destroy an Ordered Lock 96 ** 97 ** DESCRIPTION: PR_DestroyOrderedLock() destroys the ordered lock 98 ** referenced by lock. 99 ** 100 ** INPUTS: lock: pointer to a PROrderedLock 101 ** 102 ** OUTPUTS: the lock is destroyed 103 ** 104 ** RETURNS: void 105 ** 106 ** RESTRICTIONS: 107 ** 108 */ 109 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 110 #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyOrderedLock((lock)) 111 #else 112 #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyLock((lock)) 113 #endif 114 115 NSPR_API(void) 116 PR_DestroyOrderedLock( 117 PROrderedLock *lock 118 ); 119 120 /* ----------------------------------------------------------------------- 121 ** FUNCTION: PR_LockOrderedLock() -- Lock an ordered lock 122 ** 123 ** DESCRIPTION: PR_LockOrderedLock() locks the ordered lock 124 ** referenced by lock. If the order of lock is less than or equal 125 ** to the order of the highest lock held by the locking thread, 126 ** the function asserts. 127 ** 128 ** INPUTS: lock: a pointer to a PROrderedLock 129 ** 130 ** OUTPUTS: The lock is held or the function asserts. 131 ** 132 ** RETURNS: void 133 ** 134 ** RESTRICTIONS: 135 ** 136 */ 137 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 138 #define PR_LOCK_ORDERED_LOCK(lock) PR_LockOrderedLock((lock)) 139 #else 140 #define PR_LOCK_ORDERED_LOCK(lock) PR_Lock((lock)) 141 #endif 142 143 NSPR_API(void) 144 PR_LockOrderedLock( 145 PROrderedLock *lock 146 ); 147 148 /* ----------------------------------------------------------------------- 149 ** FUNCTION: PR_UnlockOrderedLock() -- unlock and Ordered Lock 150 ** 151 ** DESCRIPTION: PR_UnlockOrderedLock() unlocks the lock referenced 152 ** by lock. 153 ** 154 ** INPUTS: lock: a pointer to a PROrderedLock 155 ** 156 ** OUTPUTS: the lock is unlocked 157 ** 158 ** RETURNS: 159 ** PR_SUCCESS 160 ** PR_FAILURE 161 ** 162 ** RESTRICTIONS: 163 ** 164 */ 165 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 166 #define PR_UNLOCK_ORDERED_LOCK(lock) PR_UnlockOrderedLock((lock)) 167 #else 168 #define PR_UNLOCK_ORDERED_LOCK(lock) PR_Unlock((lock)) 169 #endif 170 171 NSPR_API(PRStatus) 172 PR_UnlockOrderedLock( 173 PROrderedLock *lock 174 ); 175 176 PR_END_EXTERN_C 177 178 #endif /* prolock_h___ */