1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prolock.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,178 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef prolock_h___
1.10 +#define prolock_h___
1.11 +
1.12 +#include "prtypes.h"
1.13 +
1.14 +PR_BEGIN_EXTERN_C
1.15 +
1.16 +/*
1.17 +** A locking mechanism, built on the existing PRLock definiion,
1.18 +** is provided that will permit applications to define a Lock
1.19 +** Hierarchy (or Lock Ordering) schema. An application designed
1.20 +** using the Ordered Lock functions will terminate with a
1.21 +** diagnostic message when a lock inversion condition is
1.22 +** detected.
1.23 +**
1.24 +** The lock ordering detection is complile-time enabled only. in
1.25 +** optimized builds of NSPR, the Ordered Lock functions map
1.26 +** directly to PRLock functions, providing no lock order
1.27 +** detection.
1.28 +**
1.29 +** The Ordered Lock Facility is compiled in when DEBUG is defined at
1.30 +** compile time. Ordered Lock can be forced on in optimized builds by
1.31 +** defining FORCE_NSPR_ORDERED_LOCK at compile time. Both the
1.32 +** application using Ordered Lock and NSPR must be compiled with the
1.33 +** facility enabled to achieve the desired results.
1.34 +**
1.35 +** Application designers should use the macro interfaces to the Ordered
1.36 +** Lock facility to ensure that it is compiled out in optimized builds.
1.37 +**
1.38 +** Application designers are responsible for defining their own
1.39 +** lock hierarchy.
1.40 +**
1.41 +** Ordered Lock is thread-safe and SMP safe.
1.42 +**
1.43 +** See Also: prlock.h
1.44 +**
1.45 +** /lth. 10-Jun-1998.
1.46 +**
1.47 +*/
1.48 +
1.49 +/*
1.50 +** Opaque type for ordered lock.
1.51 +** ... Don't even think of looking in here.
1.52 +**
1.53 +*/
1.54 +
1.55 +#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
1.56 +typedef void * PROrderedLock;
1.57 +#else
1.58 +/*
1.59 +** Map PROrderedLock and methods onto PRLock when ordered locking
1.60 +** is not compiled in.
1.61 +**
1.62 +*/
1.63 +#include "prlock.h"
1.64 +
1.65 +typedef PRLock PROrderedLock;
1.66 +#endif
1.67 +
1.68 +/* -----------------------------------------------------------------------
1.69 +** FUNCTION: PR_CreateOrderedLock() -- Create an Ordered Lock
1.70 +**
1.71 +** DESCRIPTION: PR_CreateOrderedLock() creates an ordered lock.
1.72 +**
1.73 +** INPUTS:
1.74 +** order: user defined order of this lock.
1.75 +** name: name of the lock. For debugging purposes.
1.76 +**
1.77 +** OUTPUTS: returned
1.78 +**
1.79 +** RETURNS: PR_OrderedLock pointer
1.80 +**
1.81 +** RESTRICTIONS:
1.82 +**
1.83 +*/
1.84 +#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
1.85 +#define PR_CREATE_ORDERED_LOCK(order,name)\
1.86 + PR_CreateOrderedLock((order),(name))
1.87 +#else
1.88 +#define PR_CREATE_ORDERED_LOCK(order) PR_NewLock()
1.89 +#endif
1.90 +
1.91 +NSPR_API(PROrderedLock *)
1.92 + PR_CreateOrderedLock(
1.93 + PRInt32 order,
1.94 + const char *name
1.95 +);
1.96 +
1.97 +/* -----------------------------------------------------------------------
1.98 +** FUNCTION: PR_DestroyOrderedLock() -- Destroy an Ordered Lock
1.99 +**
1.100 +** DESCRIPTION: PR_DestroyOrderedLock() destroys the ordered lock
1.101 +** referenced by lock.
1.102 +**
1.103 +** INPUTS: lock: pointer to a PROrderedLock
1.104 +**
1.105 +** OUTPUTS: the lock is destroyed
1.106 +**
1.107 +** RETURNS: void
1.108 +**
1.109 +** RESTRICTIONS:
1.110 +**
1.111 +*/
1.112 +#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
1.113 +#define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyOrderedLock((lock))
1.114 +#else
1.115 +#define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyLock((lock))
1.116 +#endif
1.117 +
1.118 +NSPR_API(void)
1.119 + PR_DestroyOrderedLock(
1.120 + PROrderedLock *lock
1.121 +);
1.122 +
1.123 +/* -----------------------------------------------------------------------
1.124 +** FUNCTION: PR_LockOrderedLock() -- Lock an ordered lock
1.125 +**
1.126 +** DESCRIPTION: PR_LockOrderedLock() locks the ordered lock
1.127 +** referenced by lock. If the order of lock is less than or equal
1.128 +** to the order of the highest lock held by the locking thread,
1.129 +** the function asserts.
1.130 +**
1.131 +** INPUTS: lock: a pointer to a PROrderedLock
1.132 +**
1.133 +** OUTPUTS: The lock is held or the function asserts.
1.134 +**
1.135 +** RETURNS: void
1.136 +**
1.137 +** RESTRICTIONS:
1.138 +**
1.139 +*/
1.140 +#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
1.141 +#define PR_LOCK_ORDERED_LOCK(lock) PR_LockOrderedLock((lock))
1.142 +#else
1.143 +#define PR_LOCK_ORDERED_LOCK(lock) PR_Lock((lock))
1.144 +#endif
1.145 +
1.146 +NSPR_API(void)
1.147 + PR_LockOrderedLock(
1.148 + PROrderedLock *lock
1.149 +);
1.150 +
1.151 +/* -----------------------------------------------------------------------
1.152 +** FUNCTION: PR_UnlockOrderedLock() -- unlock and Ordered Lock
1.153 +**
1.154 +** DESCRIPTION: PR_UnlockOrderedLock() unlocks the lock referenced
1.155 +** by lock.
1.156 +**
1.157 +** INPUTS: lock: a pointer to a PROrderedLock
1.158 +**
1.159 +** OUTPUTS: the lock is unlocked
1.160 +**
1.161 +** RETURNS:
1.162 +** PR_SUCCESS
1.163 +** PR_FAILURE
1.164 +**
1.165 +** RESTRICTIONS:
1.166 +**
1.167 +*/
1.168 +#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
1.169 +#define PR_UNLOCK_ORDERED_LOCK(lock) PR_UnlockOrderedLock((lock))
1.170 +#else
1.171 +#define PR_UNLOCK_ORDERED_LOCK(lock) PR_Unlock((lock))
1.172 +#endif
1.173 +
1.174 +NSPR_API(PRStatus)
1.175 + PR_UnlockOrderedLock(
1.176 + PROrderedLock *lock
1.177 +);
1.178 +
1.179 +PR_END_EXTERN_C
1.180 +
1.181 +#endif /* prolock_h___ */
