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
40PR_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)
82typedef 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
91typedef 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
117NSPR_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
144NSPR_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
172NSPR_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
200NSPR_API(PRStatus)
201    PR_UnlockOrderedLock(
202        PROrderedLock *lock
203);
204
205PR_END_EXTERN_C
206
207#endif /* prolock_h___ */
208