1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* 3 * The contents of this file are subject to the Mozilla Public 4 * License Version 1.1 (the "License"); you may not use this file 5 * except in compliance with the License. You may obtain a copy of 6 * the License at http://www.mozilla.org/MPL/ 7 * 8 * Software distributed under the License is distributed on an "AS 9 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or 10 * implied. See the License for the specific language governing 11 * rights and limitations under the License. 12 * 13 * The Original Code is the Netscape Portable Runtime (NSPR). 14 * 15 * The Initial Developer of the Original Code is Netscape 16 * Communications Corporation. Portions created by Netscape are 17 * Copyright (C) 1998-2000 Netscape Communications Corporation. All 18 * Rights Reserved. 19 * 20 * Contributor(s): 21 * 22 * Alternatively, the contents of this file may be used under the 23 * terms of the GNU General Public License Version 2 or later (the 24 * "GPL"), in which case the provisions of the GPL are applicable 25 * instead of those above. If you wish to allow use of your 26 * version of this file only under the terms of the GPL and not to 27 * allow others to use your version of this file under the MPL, 28 * indicate your decision by deleting the provisions above and 29 * replace them with the notice and other provisions requiored by 30 * the GPL. If you do not delete the provisions above, a recipient 31 * may use your version of this file under either the MPL or the 32 * GPL. 33 */ 34 35 #ifndef prolock_h___ 36 #define prolock_h___ 37 38 #include "prtypes.h" 39 40 PR_BEGIN_EXTERN_C 41 42 /* 43 ** A locking mechanism, built on the existing PRLock definiion, 44 ** is provided that will permit applications to define a Lock 45 ** Hierarchy (or Lock Ordering) schema. An application designed 46 ** using the Ordered Lock functions will terminate with a 47 ** diagnostic message when a lock inversion condition is 48 ** detected. 49 ** 50 ** The lock ordering detection is complile-time enabled only. in 51 ** optimized builds of NSPR, the Ordered Lock functions map 52 ** directly to PRLock functions, providing no lock order 53 ** detection. 54 ** 55 ** The Ordered Lock Facility is compiled in when DEBUG is defined at 56 ** compile time. Ordered Lock can be forced on in optimized builds by 57 ** defining FORCE_NSPR_ORDERED_LOCK at compile time. Both the 58 ** application using Ordered Lock and NSPR must be compiled with the 59 ** facility enabled to achieve the desired results. 60 ** 61 ** Application designers should use the macro interfaces to the Ordered 62 ** Lock facility to ensure that it is compiled out in optimized builds. 63 ** 64 ** Application designers are responsible for defining their own 65 ** lock hierarchy. 66 ** 67 ** Ordered Lock is thread-safe and SMP safe. 68 ** 69 ** See Also: prlock.h 70 ** 71 ** /lth. 10-Jun-1998. 72 ** 73 */ 74 75 /* 76 ** Opaque type for ordered lock. 77 ** ... Don't even think of looking in here. 78 ** 79 */ 80 81 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 82 typedef void * PROrderedLock; 83 #else 84 /* 85 ** Map PROrderedLock and methods onto PRLock when ordered locking 86 ** is not compiled in. 87 ** 88 */ 89 #include "prlock.h" 90 91 typedef PRLock PROrderedLock; 92 #endif 93 94 /* ----------------------------------------------------------------------- 95 ** FUNCTION: PR_CreateOrderedLock() -- Create an Ordered Lock 96 ** 97 ** DESCRIPTION: PR_CreateOrderedLock() creates an ordered lock. 98 ** 99 ** INPUTS: 100 ** order: user defined order of this lock. 101 ** name: name of the lock. For debugging purposes. 102 ** 103 ** OUTPUTS: returned 104 ** 105 ** RETURNS: PR_OrderedLock pointer 106 ** 107 ** RESTRICTIONS: 108 ** 109 */ 110 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 111 #define PR_CREATE_ORDERED_LOCK(order,name)\ 112 PR_CreateOrderedLock((order),(name)) 113 #else 114 #define PR_CREATE_ORDERED_LOCK(order) PR_NewLock() 115 #endif 116 117 NSPR_API(PROrderedLock *) 118 PR_CreateOrderedLock( 119 PRInt32 order, 120 const char *name 121 ); 122 123 /* ----------------------------------------------------------------------- 124 ** FUNCTION: PR_DestroyOrderedLock() -- Destroy an Ordered Lock 125 ** 126 ** DESCRIPTION: PR_DestroyOrderedLock() destroys the ordered lock 127 ** referenced by lock. 128 ** 129 ** INPUTS: lock: pointer to a PROrderedLock 130 ** 131 ** OUTPUTS: the lock is destroyed 132 ** 133 ** RETURNS: void 134 ** 135 ** RESTRICTIONS: 136 ** 137 */ 138 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 139 #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyOrderedLock((lock)) 140 #else 141 #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyLock((lock)) 142 #endif 143 144 NSPR_API(void) 145 PR_DestroyOrderedLock( 146 PROrderedLock *lock 147 ); 148 149 /* ----------------------------------------------------------------------- 150 ** FUNCTION: PR_LockOrderedLock() -- Lock an ordered lock 151 ** 152 ** DESCRIPTION: PR_LockOrderedLock() locks the ordered lock 153 ** referenced by lock. If the order of lock is less than or equal 154 ** to the order of the highest lock held by the locking thread, 155 ** the function asserts. 156 ** 157 ** INPUTS: lock: a pointer to a PROrderedLock 158 ** 159 ** OUTPUTS: The lock is held or the fucntion asserts. 160 ** 161 ** RETURNS: void 162 ** 163 ** RESTRICTIONS: 164 ** 165 */ 166 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 167 #define PR_LOCK_ORDERED_LOCK(lock) PR_LockOrderedLock((lock)) 168 #else 169 #define PR_LOCK_ORDERED_LOCK(lock) PR_Lock((lock)) 170 #endif 171 172 NSPR_API(void) 173 PR_LockOrderedLock( 174 PROrderedLock *lock 175 ); 176 177 /* ----------------------------------------------------------------------- 178 ** FUNCTION: PR_UnlockOrderedLock() -- unlock and Ordered Lock 179 ** 180 ** DESCRIPTION: PR_UnlockOrderedLock() unlocks the lock referenced 181 ** by lock. 182 ** 183 ** INPUTS: lock: a pointer to a PROrderedLock 184 ** 185 ** OUTPUTS: the lock is unlocked 186 ** 187 ** RETURNS: 188 ** PR_SUCCESS 189 ** PR_FAILURE 190 ** 191 ** RESTRICTIONS: 192 ** 193 */ 194 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 195 #define PR_UNLOCK_ORDERED_LOCK(lock) PR_UnlockOrderedLock((lock)) 196 #else 197 #define PR_UNLOCK_ORDERED_LOCK(lock) PR_Unlock((lock)) 198 #endif 199 200 NSPR_API(PRStatus) 201 PR_UnlockOrderedLock( 202 PROrderedLock *lock 203 ); 204 205 PR_END_EXTERN_C 206 207 #endif /* prolock_h___ */ 208