15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The contents of this file are subject to the Mozilla Public 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * License Version 1.1 (the "License"); you may not use this file 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * except in compliance with the License. You may obtain a copy of 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the License at http://www.mozilla.org/MPL/ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Software distributed under the License is distributed on an "AS 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * implied. See the License for the specific language governing 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * rights and limitations under the License. 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The Original Code is the Netscape Portable Runtime (NSPR). 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The Initial Developer of the Original Code is Netscape 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Communications Corporation. Portions created by Netscape are 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Copyright (C) 1998-2000 Netscape Communications Corporation. All 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Rights Reserved. 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Contributor(s): 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Alternatively, the contents of this file may be used under the 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * terms of the GNU General Public License Version 2 or later (the 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * "GPL"), in which case the provisions of the GPL are applicable 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * instead of those above. If you wish to allow use of your 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * version of this file only under the terms of the GPL and not to 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * allow others to use your version of this file under the MPL, 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * indicate your decision by deleting the provisions above and 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * replace them with the notice and other provisions requiored by 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the GPL. If you do not delete the provisions above, a recipient 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * may use your version of this file under either the MPL or the 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * GPL. 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef prolock_h___ 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define prolock_h___ 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "prtypes.h" 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)PR_BEGIN_EXTERN_C 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** A locking mechanism, built on the existing PRLock definiion, 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** is provided that will permit applications to define a Lock 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Hierarchy (or Lock Ordering) schema. An application designed 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** using the Ordered Lock functions will terminate with a 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** diagnostic message when a lock inversion condition is 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** detected. 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** The lock ordering detection is complile-time enabled only. in 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** optimized builds of NSPR, the Ordered Lock functions map 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** directly to PRLock functions, providing no lock order 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** detection. 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** The Ordered Lock Facility is compiled in when DEBUG is defined at 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** compile time. Ordered Lock can be forced on in optimized builds by 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** defining FORCE_NSPR_ORDERED_LOCK at compile time. Both the 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** application using Ordered Lock and NSPR must be compiled with the 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** facility enabled to achieve the desired results. 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Application designers should use the macro interfaces to the Ordered 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Lock facility to ensure that it is compiled out in optimized builds. 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Application designers are responsible for defining their own 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** lock hierarchy. 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Ordered Lock is thread-safe and SMP safe. 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** See Also: prlock.h 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** /lth. 10-Jun-1998. 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Opaque type for ordered lock. 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** ... Don't even think of looking in here. 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef void * PROrderedLock; 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Map PROrderedLock and methods onto PRLock when ordered locking 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** is not compiled in. 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "prlock.h" 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef PRLock PROrderedLock; 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_CreateOrderedLock() -- Create an Ordered Lock 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: PR_CreateOrderedLock() creates an ordered lock. 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** order: user defined order of this lock. 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** name: name of the lock. For debugging purposes. 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: returned 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: PR_OrderedLock pointer 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_CREATE_ORDERED_LOCK(order,name)\ 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_CreateOrderedLock((order),(name)) 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_CREATE_ORDERED_LOCK(order) PR_NewLock() 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(PROrderedLock *) 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_CreateOrderedLock( 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRInt32 order, 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char *name 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_DestroyOrderedLock() -- Destroy an Ordered Lock 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: PR_DestroyOrderedLock() destroys the ordered lock 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** referenced by lock. 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: lock: pointer to a PROrderedLock 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: the lock is destroyed 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: void 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyOrderedLock((lock)) 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_DESTROY_ORDERED_LOCK(lock) PR_DestroyLock((lock)) 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(void) 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_DestroyOrderedLock( 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PROrderedLock *lock 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_LockOrderedLock() -- Lock an ordered lock 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: PR_LockOrderedLock() locks the ordered lock 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** referenced by lock. If the order of lock is less than or equal 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** to the order of the highest lock held by the locking thread, 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** the function asserts. 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: lock: a pointer to a PROrderedLock 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: The lock is held or the fucntion asserts. 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: void 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_LOCK_ORDERED_LOCK(lock) PR_LockOrderedLock((lock)) 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_LOCK_ORDERED_LOCK(lock) PR_Lock((lock)) 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(void) 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_LockOrderedLock( 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PROrderedLock *lock 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_UnlockOrderedLock() -- unlock and Ordered Lock 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: PR_UnlockOrderedLock() unlocks the lock referenced 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** by lock. 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: lock: a pointer to a PROrderedLock 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: the lock is unlocked 1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: 1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_SUCCESS 1895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_FAILURE 1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(DEBUG) || defined(FORCE_NSPR_ORDERED_LOCKS) 1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_UNLOCK_ORDERED_LOCK(lock) PR_UnlockOrderedLock((lock)) 1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_UNLOCK_ORDERED_LOCK(lock) PR_Unlock((lock)) 1985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 1995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(PRStatus) 2015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_UnlockOrderedLock( 2025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PROrderedLock *lock 2035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 2045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)PR_END_EXTERN_C 2065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif /* prolock_h___ */ 208