Line data Source code
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 definition,
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 compile-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 0 : 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 0 : 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 0 : 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 0 : PR_UnlockOrderedLock(
173 : PROrderedLock *lock
174 : );
175 :
176 : PR_END_EXTERN_C
177 :
178 : #endif /* prolock_h___ */
|
