nsprpub/pr/include/prolock.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef prolock_h___
   7 #define prolock_h___
   8
   9 #include "prtypes.h"
  10
  11 PR_BEGIN_EXTERN_C
  12
  13 /*
  14 ** A locking mechanism, built on the existing PRLock definiion,
  15 ** is provided that will permit applications to define a Lock
  16 ** Hierarchy (or Lock Ordering) schema. An application designed
  17 ** using the Ordered Lock functions will terminate with a
  18 ** diagnostic message when a lock inversion condition is
  19 ** detected.
  20 **
  21 ** The lock ordering detection is complile-time enabled only. in
  22 ** optimized builds of NSPR, the Ordered Lock functions map
  23 ** directly to PRLock functions, providing no lock order
  24 ** detection.
  25 **
  26 ** The Ordered Lock Facility is compiled in when DEBUG is defined at
  27 ** compile time. Ordered Lock can be forced on in optimized builds by
  28 ** defining FORCE_NSPR_ORDERED_LOCK at compile time. Both the
  29 ** application using Ordered Lock and NSPR must be compiled with the
  30 ** facility enabled to achieve the desired results.
  31 **
  32 ** Application designers should use the macro interfaces to the Ordered
  33 ** Lock facility to ensure that it is compiled out in optimized builds.
  34 **
  35 ** Application designers are responsible for defining their own
  36 ** lock hierarchy.
  37 **
  38 ** Ordered Lock is thread-safe and SMP safe.
  39 **
  40 ** See Also: prlock.h
  41 **
  42 ** /lth. 10-Jun-1998.
  43 **
  44 */
  45
  46 /*
  47 ** Opaque type for ordered lock.
  48 ** ... Don't even think of looking in here.
  49 **
  50 */
  51
  52 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
  53 typedef void * PROrderedLock;
  54 #else
  55 /*
  56 ** Map PROrderedLock and methods onto PRLock when ordered locking
  57 ** is not compiled in.
  58 **
  59 */
  60 #include "prlock.h"
  61
  62 typedef PRLock PROrderedLock;
  63 #endif
  64
  65 /* -----------------------------------------------------------------------
  66 ** FUNCTION: PR_CreateOrderedLock() -- Create an Ordered Lock
  67 **
  68 ** DESCRIPTION: PR_CreateOrderedLock() creates an ordered lock.
  69 **
  70 ** INPUTS:
  71 **  order: user defined order of this lock.
  72 **  name: name of the lock. For debugging purposes.
  73 **
  74 ** OUTPUTS: returned
  75 **
  76 ** RETURNS: PR_OrderedLock pointer
  77 **
  78 ** RESTRICTIONS:
  79 **
  80 */
  81 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
  82 #define PR_CREATE_ORDERED_LOCK(order,name)\
  83     PR_CreateOrderedLock((order),(name))
  84 #else
  85 #define PR_CREATE_ORDERED_LOCK(order) PR_NewLock()
  86 #endif
  87
  88 NSPR_API(PROrderedLock *)
  89     PR_CreateOrderedLock(
  90         PRInt32 order,
  91         const char *name
  92 );
  93
  94 /* -----------------------------------------------------------------------
  95 ** FUNCTION: PR_DestroyOrderedLock() -- Destroy an Ordered Lock
  96 **
  97 ** DESCRIPTION: PR_DestroyOrderedLock() destroys the ordered lock
  98 ** referenced by lock.
  99 **
 100 ** INPUTS: lock: pointer to a PROrderedLock
 101 **
 102 ** OUTPUTS: the lock is destroyed
 103 **
 104 ** RETURNS: void
 105 **
 106 ** RESTRICTIONS:
 107 **
 108 */
 109 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
 110 #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyOrderedLock((lock))
 111 #else
 112 #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyLock((lock))
 113 #endif
 114
 115 NSPR_API(void)
 116     PR_DestroyOrderedLock(
 117         PROrderedLock *lock
 118 );
 119
 120 /* -----------------------------------------------------------------------
 121 ** FUNCTION: PR_LockOrderedLock() -- Lock an ordered lock
 122 **
 123 ** DESCRIPTION: PR_LockOrderedLock() locks the ordered lock
 124 ** referenced by lock. If the order of lock is less than or equal
 125 ** to the order of the highest lock held by the locking thread,
 126 ** the function asserts.
 127 **
 128 ** INPUTS: lock: a pointer to a PROrderedLock
 129 **
 130 ** OUTPUTS: The lock is held or the function asserts.
 131 **
 132 ** RETURNS: void
 133 **
 134 ** RESTRICTIONS:
 135 **
 136 */
 137 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
 138 #define PR_LOCK_ORDERED_LOCK(lock) PR_LockOrderedLock((lock))
 139 #else
 140 #define PR_LOCK_ORDERED_LOCK(lock) PR_Lock((lock))
 141 #endif
 142
 143 NSPR_API(void)
 144     PR_LockOrderedLock(
 145         PROrderedLock *lock
 146 );
 147
 148 /* -----------------------------------------------------------------------
 149 ** FUNCTION: PR_UnlockOrderedLock() -- unlock and Ordered Lock
 150 **
 151 ** DESCRIPTION: PR_UnlockOrderedLock() unlocks the lock referenced
 152 ** by lock.
 153 **
 154 ** INPUTS: lock: a pointer to a PROrderedLock
 155 **
 156 ** OUTPUTS: the lock is unlocked
 157 **
 158 ** RETURNS:
 159 **  PR_SUCCESS
 160 **  PR_FAILURE
 161 **
 162 ** RESTRICTIONS:
 163 **
 164 */
 165 #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
 166 #define PR_UNLOCK_ORDERED_LOCK(lock) PR_UnlockOrderedLock((lock))
 167 #else
 168 #define PR_UNLOCK_ORDERED_LOCK(lock) PR_Unlock((lock))
 169 #endif
 170
 171 NSPR_API(PRStatus)
 172     PR_UnlockOrderedLock(
 173         PROrderedLock *lock
 174 );
 175
 176 PR_END_EXTERN_C
 177
 178 #endif /* prolock_h___ */