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