prlock.h (3816B)
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/. */ 5 6 /* 7 ** File: prlock.h 8 ** Description: API to basic locking functions of NSPR. 9 ** 10 ** 11 ** NSPR provides basic locking mechanisms for thread synchronization. Locks 12 ** are lightweight resource contention controls that prevent multiple threads 13 ** from accessing something (code/data) simultaneously. 14 **/ 15 16 #ifndef prlock_h___ 17 #define prlock_h___ 18 19 #include "prtypes.h" 20 21 PR_BEGIN_EXTERN_C 22 23 /**********************************************************************/ 24 /************************* TYPES AND CONSTANTS ************************/ 25 /**********************************************************************/ 26 27 /* 28 * PRLock -- 29 * 30 * NSPR represents the lock as an opaque entity to the client of the 31 * API. All routines operate on a pointer to this opaque entity. 32 */ 33 34 typedef struct PRLock PRLock; 35 36 /**********************************************************************/ 37 /****************************** FUNCTIONS *****************************/ 38 /**********************************************************************/ 39 40 /*********************************************************************** 41 ** FUNCTION: PR_NewLock 42 ** DESCRIPTION: 43 ** Returns a pointer to a newly created opaque lock object. 44 ** INPUTS: void 45 ** OUTPUTS: void 46 ** RETURN: PRLock* 47 ** If the lock can not be created because of resource constraints, NULL 48 ** is returned. 49 ** 50 ***********************************************************************/ 51 NSPR_API(PRLock*) PR_NewLock(void); 52 53 /*********************************************************************** 54 ** FUNCTION: PR_DestroyLock 55 ** DESCRIPTION: 56 ** Destroys a given opaque lock object. 57 ** INPUTS: PRLock *lock 58 ** Lock to be freed. 59 ** OUTPUTS: void 60 ** RETURN: None 61 ***********************************************************************/ 62 NSPR_API(void) PR_DestroyLock(PRLock *lock); 63 64 /*********************************************************************** 65 ** FUNCTION: PR_Lock 66 ** DESCRIPTION: 67 ** Lock a lock. 68 ** INPUTS: PRLock *lock 69 ** Lock to locked. 70 ** OUTPUTS: void 71 ** RETURN: None 72 ***********************************************************************/ 73 NSPR_API(void) PR_Lock(PRLock *lock); 74 75 /*********************************************************************** 76 ** FUNCTION: PR_Unlock 77 ** DESCRIPTION: 78 ** Unlock a lock. Unlocking an unlocked lock has undefined results. 79 ** INPUTS: PRLock *lock 80 ** Lock to unlocked. 81 ** OUTPUTS: void 82 ** RETURN: PR_STATUS 83 ** Returns PR_FAILURE if the caller does not own the lock. 84 ***********************************************************************/ 85 NSPR_API(PRStatus) PR_Unlock(PRLock *lock); 86 87 /*********************************************************************** 88 ** MACRO: PR_ASSERT_CURRENT_THREAD_OWNS_LOCK 89 ** DESCRIPTION: 90 ** If the current thread owns |lock|, this assertion is guaranteed to 91 ** succeed. Otherwise, the behavior of this function is undefined. 92 ** INPUTS: PRLock *lock 93 ** Lock to assert ownership of. 94 ** OUTPUTS: void 95 ** RETURN: None 96 ***********************************************************************/ 97 #if defined(DEBUG) || defined(FORCE_PR_ASSERT) 98 #define PR_ASSERT_CURRENT_THREAD_OWNS_LOCK(/* PrLock* */ lock) \ 99 PR_AssertCurrentThreadOwnsLock(lock) 100 #else 101 #define PR_ASSERT_CURRENT_THREAD_OWNS_LOCK(/* PrLock* */ lock) 102 #endif 103 104 /* Don't call this function directly. */ 105 NSPR_API(void) PR_AssertCurrentThreadOwnsLock(PRLock *lock); 106 107 PR_END_EXTERN_C 108 109 #endif /* prlock_h___ */