/gecko_api/include/prolock.h

  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___ */