nssrwlk.h (5047B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 /* 6 ** File: nsrwlock.h 7 ** Description: API to basic reader-writer lock functions of NSS. 8 ** These locks allow re-entry from writers but not readers. That is, 9 ** If I hold the write lock, I can ask for it and get it again. 10 ** If I hold the write lock, I can also ask for and get a read lock. 11 ** I can then release the locks in any order (read or write). 12 ** If I hold a read lock, I must not ask for another read lock or 13 ** the write lock. 14 ** I must release each lock type as many times as I acquired it. 15 ** 16 ** For deadlock detection, locks should be ranked, and no lock may be aquired 17 ** while I hold a lock of higher rank number. 18 ** If you don't want that feature, always use NSS_RWLOCK_RANK_NONE. 19 ** Lock name is for debugging, and is optional (may be NULL) 20 **/ 21 22 #ifndef nssrwlk_h___ 23 #define nssrwlk_h___ 24 25 #include "utilrename.h" 26 #include "prtypes.h" 27 #include "nssrwlkt.h" 28 29 #define NSS_RWLOCK_RANK_NONE 0 30 31 /* SEC_BEGIN_PROTOS */ 32 PR_BEGIN_EXTERN_C 33 34 /*********************************************************************** 35 ** FUNCTION: NSSRWLock_New 36 ** DESCRIPTION: 37 ** Returns a pointer to a newly created reader-writer lock object. 38 ** INPUTS: Lock rank 39 ** Lock name 40 ** OUTPUTS: void 41 ** RETURN: NSSRWLock* 42 ** If the lock cannot be created because of resource constraints, NULL 43 ** is returned. 44 ** 45 ***********************************************************************/ 46 extern NSSRWLock *NSSRWLock_New(PRUint32 lock_rank, const char *lock_name); 47 48 /*********************************************************************** 49 ** FUNCTION: NSSRWLock_AtomicCreate 50 ** DESCRIPTION: 51 ** Given the address of a NULL pointer to a NSSRWLock, 52 ** atomically initializes that pointer to a newly created NSSRWLock. 53 ** Returns the value placed into that pointer, or NULL. 54 ** 55 ** INPUTS: address of NSRWLock pointer 56 ** Lock rank 57 ** Lock name 58 ** OUTPUTS: NSSRWLock* 59 ** RETURN: NSSRWLock* 60 ** If the lock cannot be created because of resource constraints, 61 ** the pointer will be left NULL. 62 ** 63 ***********************************************************************/ 64 extern NSSRWLock * 65 nssRWLock_AtomicCreate(NSSRWLock **prwlock, 66 PRUint32 lock_rank, 67 const char *lock_name); 68 69 /*********************************************************************** 70 ** FUNCTION: NSSRWLock_Destroy 71 ** DESCRIPTION: 72 ** Destroys a given RW lock object. 73 ** INPUTS: NSSRWLock *lock - Lock to be freed. 74 ** OUTPUTS: void 75 ** RETURN: None 76 ***********************************************************************/ 77 extern void NSSRWLock_Destroy(NSSRWLock *lock); 78 79 /*********************************************************************** 80 ** FUNCTION: NSSRWLock_LockRead 81 ** DESCRIPTION: 82 ** Apply a read lock (non-exclusive) on a RWLock 83 ** INPUTS: NSSRWLock *lock - Lock to be read-locked. 84 ** OUTPUTS: void 85 ** RETURN: None 86 ***********************************************************************/ 87 extern void NSSRWLock_LockRead(NSSRWLock *lock); 88 89 /*********************************************************************** 90 ** FUNCTION: NSSRWLock_LockWrite 91 ** DESCRIPTION: 92 ** Apply a write lock (exclusive) on a RWLock 93 ** INPUTS: NSSRWLock *lock - Lock to write-locked. 94 ** OUTPUTS: void 95 ** RETURN: None 96 ***********************************************************************/ 97 extern void NSSRWLock_LockWrite(NSSRWLock *lock); 98 99 /*********************************************************************** 100 ** FUNCTION: NSSRWLock_UnlockRead 101 ** DESCRIPTION: 102 ** Release a Read lock. Unlocking an unlocked lock has undefined results. 103 ** INPUTS: NSSRWLock *lock - Lock to unlocked. 104 ** OUTPUTS: void 105 ** RETURN: void 106 ***********************************************************************/ 107 extern void NSSRWLock_UnlockRead(NSSRWLock *lock); 108 109 /*********************************************************************** 110 ** FUNCTION: NSSRWLock_UnlockWrite 111 ** DESCRIPTION: 112 ** Release a Write lock. Unlocking an unlocked lock has undefined results. 113 ** INPUTS: NSSRWLock *lock - Lock to unlocked. 114 ** OUTPUTS: void 115 ** RETURN: void 116 ***********************************************************************/ 117 extern void NSSRWLock_UnlockWrite(NSSRWLock *lock); 118 119 /*********************************************************************** 120 ** FUNCTION: NSSRWLock_HaveWriteLock 121 ** DESCRIPTION: 122 ** Tells caller whether the current thread holds the write lock, or not. 123 ** INPUTS: NSSRWLock *lock - Lock to test. 124 ** OUTPUTS: void 125 ** RETURN: PRBool PR_TRUE IFF the current thread holds the write lock. 126 ***********************************************************************/ 127 128 extern PRBool NSSRWLock_HaveWriteLock(NSSRWLock *rwlock); 129 130 /* SEC_END_PROTOS */ 131 PR_END_EXTERN_C 132 133 #endif /* nsrwlock_h___ */