Back to index

lightning-sunbird  0.9+nobinonly
prolock.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef prolock_h___
00039 #define prolock_h___
00040 
00041 #include "prtypes.h"
00042 
00043 PR_BEGIN_EXTERN_C
00044 
00045 /*
00046 ** A locking mechanism, built on the existing PRLock definiion,
00047 ** is provided that will permit applications to define a Lock
00048 ** Hierarchy (or Lock Ordering) schema. An application designed
00049 ** using the Ordered Lock functions will terminate with a
00050 ** diagnostic message when a lock inversion condition is
00051 ** detected. 
00052 ** 
00053 ** The lock ordering detection is complile-time enabled only. in
00054 ** optimized builds of NSPR, the Ordered Lock functions map
00055 ** directly to PRLock functions, providing no lock order
00056 ** detection.
00057 ** 
00058 ** The Ordered Lock Facility is compiled in when DEBUG is defined at
00059 ** compile time. Ordered Lock can be forced on in optimized builds by
00060 ** defining FORCE_NSPR_ORDERED_LOCK at compile time. Both the
00061 ** application using Ordered Lock and NSPR must be compiled with the
00062 ** facility enabled to achieve the desired results.
00063 ** 
00064 ** Application designers should use the macro interfaces to the Ordered
00065 ** Lock facility to ensure that it is compiled out in optimized builds.
00066 **
00067 ** Application designers are responsible for defining their own
00068 ** lock hierarchy. 
00069 **
00070 ** Ordered Lock is thread-safe and SMP safe.
00071 **
00072 ** See Also: prlock.h
00073 **
00074 ** /lth. 10-Jun-1998.
00075 **
00076 */
00077 
00078 /*
00079 ** Opaque type for ordered lock.
00080 ** ... Don't even think of looking in here.
00081 **
00082 */
00083 
00084 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
00085 typedef void * PROrderedLock;
00086 #else
00087 /*
00088 ** Map PROrderedLock and methods onto PRLock when ordered locking
00089 ** is not compiled in.
00090 **  
00091 */
00092 #include "prlock.h"
00093 
00094 typedef PRLock PROrderedLock;
00095 #endif
00096 
00097 /* -----------------------------------------------------------------------
00098 ** FUNCTION: PR_CreateOrderedLock() -- Create an Ordered Lock
00099 ** 
00100 ** DESCRIPTION: PR_CreateOrderedLock() creates an ordered lock.
00101 ** 
00102 ** INPUTS:
00103 **  order: user defined order of this lock.
00104 **  name: name of the lock. For debugging purposes.
00105 ** 
00106 ** OUTPUTS: returned
00107 ** 
00108 ** RETURNS: PR_OrderedLock pointer
00109 ** 
00110 ** RESTRICTIONS:
00111 ** 
00112 */
00113 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
00114 #define PR_CREATE_ORDERED_LOCK(order,name)\
00115     PR_CreateOrderedLock((order),(name))
00116 #else
00117 #define PR_CREATE_ORDERED_LOCK(order) PR_NewLock()
00118 #endif
00119 
00120 NSPR_API(PROrderedLock *) 
00121     PR_CreateOrderedLock( 
00122         PRInt32 order,
00123         const char *name
00124 );
00125 
00126 /* -----------------------------------------------------------------------
00127 ** FUNCTION: PR_DestroyOrderedLock() -- Destroy an Ordered Lock
00128 ** 
00129 ** DESCRIPTION: PR_DestroyOrderedLock() destroys the ordered lock
00130 ** referenced by lock.
00131 ** 
00132 ** INPUTS: lock: pointer to a PROrderedLock
00133 ** 
00134 ** OUTPUTS: the lock is destroyed
00135 ** 
00136 ** RETURNS: void
00137 ** 
00138 ** RESTRICTIONS:
00139 ** 
00140 */
00141 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
00142 #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyOrderedLock((lock))
00143 #else
00144 #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyLock((lock))
00145 #endif
00146 
00147 NSPR_API(void) 
00148     PR_DestroyOrderedLock( 
00149         PROrderedLock *lock 
00150 );
00151 
00152 /* -----------------------------------------------------------------------
00153 ** FUNCTION: PR_LockOrderedLock() -- Lock an ordered lock
00154 ** 
00155 ** DESCRIPTION: PR_LockOrderedLock() locks the ordered lock
00156 ** referenced by lock. If the order of lock is less than or equal
00157 ** to the order of the highest lock held by the locking thread,
00158 ** the function asserts.
00159 ** 
00160 ** INPUTS: lock: a pointer to a PROrderedLock
00161 ** 
00162 ** OUTPUTS: The lock is held or the function asserts.
00163 ** 
00164 ** RETURNS: void
00165 ** 
00166 ** RESTRICTIONS:
00167 ** 
00168 */
00169 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
00170 #define PR_LOCK_ORDERED_LOCK(lock) PR_LockOrderedLock((lock))
00171 #else
00172 #define PR_LOCK_ORDERED_LOCK(lock) PR_Lock((lock))
00173 #endif
00174 
00175 NSPR_API(void) 
00176     PR_LockOrderedLock( 
00177         PROrderedLock *lock 
00178 );
00179 
00180 /* -----------------------------------------------------------------------
00181 ** FUNCTION: PR_UnlockOrderedLock() -- unlock and Ordered Lock
00182 ** 
00183 ** DESCRIPTION: PR_UnlockOrderedLock() unlocks the lock referenced
00184 ** by lock.
00185 ** 
00186 ** INPUTS: lock: a pointer to a PROrderedLock
00187 ** 
00188 ** OUTPUTS: the lock is unlocked
00189 ** 
00190 ** RETURNS:
00191 **  PR_SUCCESS
00192 **  PR_FAILURE
00193 ** 
00194 ** RESTRICTIONS:
00195 ** 
00196 */
00197 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
00198 #define PR_UNLOCK_ORDERED_LOCK(lock) PR_UnlockOrderedLock((lock))
00199 #else
00200 #define PR_UNLOCK_ORDERED_LOCK(lock) PR_Unlock((lock))
00201 #endif
00202 
00203 NSPR_API(PRStatus) 
00204     PR_UnlockOrderedLock( 
00205         PROrderedLock *lock 
00206 );
00207 
00208 PR_END_EXTERN_C
00209 
00210 #endif /* prolock_h___ */