nsprpub/pr/include/prolock.h@925c144e1f1f
nsprpub/pr/include/prolock.h
Fri, 16 Jan 2015 18:13:44 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Fri, 16 Jan 2015 18:13:44 +0100
- branch
- TOR_BUG_9701
- changeset 14
- 925c144e1f1f
- permissions
- -rw-r--r--
Integrate suggestion from review to improve consistency with existing 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/. */
6 #ifndef prolock_h___
7 #define prolock_h___
9 #include "prtypes.h"
11 PR_BEGIN_EXTERN_C
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 */
46 /*
47 ** Opaque type for ordered lock.
48 ** ... Don't even think of looking in here.
49 **
50 */
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"
62 typedef PRLock PROrderedLock;
63 #endif
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
88 NSPR_API(PROrderedLock *)
89 PR_CreateOrderedLock(
90 PRInt32 order,
91 const char *name
92 );
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
115 NSPR_API(void)
116 PR_DestroyOrderedLock(
117 PROrderedLock *lock
118 );
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
143 NSPR_API(void)
144 PR_LockOrderedLock(
145 PROrderedLock *lock
146 );
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
171 NSPR_API(PRStatus)
172 PR_UnlockOrderedLock(
173 PROrderedLock *lock
174 );
176 PR_END_EXTERN_C
178 #endif /* prolock_h___ */
