third_party/npapi/npspy/extern/nspr/prolock.h

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