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 40PR_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) 82typedef 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 91typedef 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 117NSPR_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 144NSPR_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 172NSPR_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 200NSPR_API(PRStatus) 201 PR_UnlockOrderedLock( 202 PROrderedLock *lock 203); 204 205PR_END_EXTERN_C 206 207#endif /* prolock_h___ */ 208