michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef prolock_h___
michael@0: #define prolock_h___
michael@0: 
michael@0: #include "prtypes.h"
michael@0: 
michael@0: PR_BEGIN_EXTERN_C
michael@0: 
michael@0: /*
michael@0: ** A locking mechanism, built on the existing PRLock definiion,
michael@0: ** is provided that will permit applications to define a Lock
michael@0: ** Hierarchy (or Lock Ordering) schema. An application designed
michael@0: ** using the Ordered Lock functions will terminate with a
michael@0: ** diagnostic message when a lock inversion condition is
michael@0: ** detected. 
michael@0: ** 
michael@0: ** The lock ordering detection is complile-time enabled only. in
michael@0: ** optimized builds of NSPR, the Ordered Lock functions map
michael@0: ** directly to PRLock functions, providing no lock order
michael@0: ** detection.
michael@0: ** 
michael@0: ** The Ordered Lock Facility is compiled in when DEBUG is defined at
michael@0: ** compile time. Ordered Lock can be forced on in optimized builds by
michael@0: ** defining FORCE_NSPR_ORDERED_LOCK at compile time. Both the
michael@0: ** application using Ordered Lock and NSPR must be compiled with the
michael@0: ** facility enabled to achieve the desired results.
michael@0: ** 
michael@0: ** Application designers should use the macro interfaces to the Ordered
michael@0: ** Lock facility to ensure that it is compiled out in optimized builds.
michael@0: **
michael@0: ** Application designers are responsible for defining their own
michael@0: ** lock hierarchy. 
michael@0: **
michael@0: ** Ordered Lock is thread-safe and SMP safe.
michael@0: **
michael@0: ** See Also: prlock.h
michael@0: **
michael@0: ** /lth. 10-Jun-1998.
michael@0: **
michael@0: */
michael@0: 
michael@0: /*
michael@0: ** Opaque type for ordered lock.
michael@0: ** ... Don't even think of looking in here.
michael@0: **
michael@0: */
michael@0: 
michael@0: #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
michael@0: typedef void * PROrderedLock;
michael@0: #else
michael@0: /*
michael@0: ** Map PROrderedLock and methods onto PRLock when ordered locking
michael@0: ** is not compiled in.
michael@0: **  
michael@0: */
michael@0: #include "prlock.h"
michael@0: 
michael@0: typedef PRLock PROrderedLock;
michael@0: #endif
michael@0: 
michael@0: /* -----------------------------------------------------------------------
michael@0: ** FUNCTION: PR_CreateOrderedLock() -- Create an Ordered Lock
michael@0: ** 
michael@0: ** DESCRIPTION: PR_CreateOrderedLock() creates an ordered lock.
michael@0: ** 
michael@0: ** INPUTS:
michael@0: **  order: user defined order of this lock.
michael@0: **  name: name of the lock. For debugging purposes.
michael@0: ** 
michael@0: ** OUTPUTS: returned
michael@0: ** 
michael@0: ** RETURNS: PR_OrderedLock pointer
michael@0: ** 
michael@0: ** RESTRICTIONS:
michael@0: ** 
michael@0: */
michael@0: #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
michael@0: #define PR_CREATE_ORDERED_LOCK(order,name)\
michael@0:     PR_CreateOrderedLock((order),(name))
michael@0: #else
michael@0: #define PR_CREATE_ORDERED_LOCK(order) PR_NewLock()
michael@0: #endif
michael@0: 
michael@0: NSPR_API(PROrderedLock *) 
michael@0:     PR_CreateOrderedLock( 
michael@0:         PRInt32 order,
michael@0:         const char *name
michael@0: );
michael@0: 
michael@0: /* -----------------------------------------------------------------------
michael@0: ** FUNCTION: PR_DestroyOrderedLock() -- Destroy an Ordered Lock
michael@0: ** 
michael@0: ** DESCRIPTION: PR_DestroyOrderedLock() destroys the ordered lock
michael@0: ** referenced by lock.
michael@0: ** 
michael@0: ** INPUTS: lock: pointer to a PROrderedLock
michael@0: ** 
michael@0: ** OUTPUTS: the lock is destroyed
michael@0: ** 
michael@0: ** RETURNS: void
michael@0: ** 
michael@0: ** RESTRICTIONS:
michael@0: ** 
michael@0: */
michael@0: #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
michael@0: #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyOrderedLock((lock))
michael@0: #else
michael@0: #define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyLock((lock))
michael@0: #endif
michael@0: 
michael@0: NSPR_API(void) 
michael@0:     PR_DestroyOrderedLock( 
michael@0:         PROrderedLock *lock 
michael@0: );
michael@0: 
michael@0: /* -----------------------------------------------------------------------
michael@0: ** FUNCTION: PR_LockOrderedLock() -- Lock an ordered lock
michael@0: ** 
michael@0: ** DESCRIPTION: PR_LockOrderedLock() locks the ordered lock
michael@0: ** referenced by lock. If the order of lock is less than or equal
michael@0: ** to the order of the highest lock held by the locking thread,
michael@0: ** the function asserts.
michael@0: ** 
michael@0: ** INPUTS: lock: a pointer to a PROrderedLock
michael@0: ** 
michael@0: ** OUTPUTS: The lock is held or the function asserts.
michael@0: ** 
michael@0: ** RETURNS: void
michael@0: ** 
michael@0: ** RESTRICTIONS:
michael@0: ** 
michael@0: */
michael@0: #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
michael@0: #define PR_LOCK_ORDERED_LOCK(lock) PR_LockOrderedLock((lock))
michael@0: #else
michael@0: #define PR_LOCK_ORDERED_LOCK(lock) PR_Lock((lock))
michael@0: #endif
michael@0: 
michael@0: NSPR_API(void) 
michael@0:     PR_LockOrderedLock( 
michael@0:         PROrderedLock *lock 
michael@0: );
michael@0: 
michael@0: /* -----------------------------------------------------------------------
michael@0: ** FUNCTION: PR_UnlockOrderedLock() -- unlock and Ordered Lock
michael@0: ** 
michael@0: ** DESCRIPTION: PR_UnlockOrderedLock() unlocks the lock referenced
michael@0: ** by lock.
michael@0: ** 
michael@0: ** INPUTS: lock: a pointer to a PROrderedLock
michael@0: ** 
michael@0: ** OUTPUTS: the lock is unlocked
michael@0: ** 
michael@0: ** RETURNS:
michael@0: **  PR_SUCCESS
michael@0: **  PR_FAILURE
michael@0: ** 
michael@0: ** RESTRICTIONS:
michael@0: ** 
michael@0: */
michael@0: #if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS)
michael@0: #define PR_UNLOCK_ORDERED_LOCK(lock) PR_UnlockOrderedLock((lock))
michael@0: #else
michael@0: #define PR_UNLOCK_ORDERED_LOCK(lock) PR_Unlock((lock))
michael@0: #endif
michael@0: 
michael@0: NSPR_API(PRStatus) 
michael@0:     PR_UnlockOrderedLock( 
michael@0:         PROrderedLock *lock 
michael@0: );
michael@0: 
michael@0: PR_END_EXTERN_C
michael@0: 
michael@0: #endif /* prolock_h___ */