1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/util/nssrwlk.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,132 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +/*
1.9 +** File: nsrwlock.h
1.10 +** Description: API to basic reader-writer lock functions of NSS.
1.11 +** These are re-entrant reader writer locks; that is,
1.12 +** If I hold the write lock, I can ask for it and get it again.
1.13 +** If I hold the write lock, I can also ask for and get a read lock.
1.14 +** I can then release the locks in any order (read or write).
1.15 +** I must release each lock type as many times as I acquired it.
1.16 +** Otherwise, these are normal reader/writer locks.
1.17 +**
1.18 +** For deadlock detection, locks should be ranked, and no lock may be aquired
1.19 +** while I hold a lock of higher rank number.
1.20 +** If you don't want that feature, always use NSS_RWLOCK_RANK_NONE.
1.21 +** Lock name is for debugging, and is optional (may be NULL)
1.22 +**/
1.23 +
1.24 +#ifndef nssrwlk_h___
1.25 +#define nssrwlk_h___
1.26 +
1.27 +#include "utilrename.h"
1.28 +#include "prtypes.h"
1.29 +#include "nssrwlkt.h"
1.30 +
1.31 +#define NSS_RWLOCK_RANK_NONE 0
1.32 +
1.33 +/* SEC_BEGIN_PROTOS */
1.34 +PR_BEGIN_EXTERN_C
1.35 +
1.36 +/***********************************************************************
1.37 +** FUNCTION: NSSRWLock_New
1.38 +** DESCRIPTION:
1.39 +** Returns a pointer to a newly created reader-writer lock object.
1.40 +** INPUTS: Lock rank
1.41 +** Lock name
1.42 +** OUTPUTS: void
1.43 +** RETURN: NSSRWLock*
1.44 +** If the lock cannot be created because of resource constraints, NULL
1.45 +** is returned.
1.46 +**
1.47 +***********************************************************************/
1.48 +extern NSSRWLock* NSSRWLock_New(PRUint32 lock_rank, const char *lock_name);
1.49 +
1.50 +/***********************************************************************
1.51 +** FUNCTION: NSSRWLock_AtomicCreate
1.52 +** DESCRIPTION:
1.53 +** Given the address of a NULL pointer to a NSSRWLock,
1.54 +** atomically initializes that pointer to a newly created NSSRWLock.
1.55 +** Returns the value placed into that pointer, or NULL.
1.56 +**
1.57 +** INPUTS: address of NSRWLock pointer
1.58 +** Lock rank
1.59 +** Lock name
1.60 +** OUTPUTS: NSSRWLock*
1.61 +** RETURN: NSSRWLock*
1.62 +** If the lock cannot be created because of resource constraints,
1.63 +** the pointer will be left NULL.
1.64 +**
1.65 +***********************************************************************/
1.66 +extern NSSRWLock *
1.67 +nssRWLock_AtomicCreate( NSSRWLock ** prwlock,
1.68 + PRUint32 lock_rank,
1.69 + const char * lock_name);
1.70 +
1.71 +/***********************************************************************
1.72 +** FUNCTION: NSSRWLock_Destroy
1.73 +** DESCRIPTION:
1.74 +** Destroys a given RW lock object.
1.75 +** INPUTS: NSSRWLock *lock - Lock to be freed.
1.76 +** OUTPUTS: void
1.77 +** RETURN: None
1.78 +***********************************************************************/
1.79 +extern void NSSRWLock_Destroy(NSSRWLock *lock);
1.80 +
1.81 +/***********************************************************************
1.82 +** FUNCTION: NSSRWLock_LockRead
1.83 +** DESCRIPTION:
1.84 +** Apply a read lock (non-exclusive) on a RWLock
1.85 +** INPUTS: NSSRWLock *lock - Lock to be read-locked.
1.86 +** OUTPUTS: void
1.87 +** RETURN: None
1.88 +***********************************************************************/
1.89 +extern void NSSRWLock_LockRead(NSSRWLock *lock);
1.90 +
1.91 +/***********************************************************************
1.92 +** FUNCTION: NSSRWLock_LockWrite
1.93 +** DESCRIPTION:
1.94 +** Apply a write lock (exclusive) on a RWLock
1.95 +** INPUTS: NSSRWLock *lock - Lock to write-locked.
1.96 +** OUTPUTS: void
1.97 +** RETURN: None
1.98 +***********************************************************************/
1.99 +extern void NSSRWLock_LockWrite(NSSRWLock *lock);
1.100 +
1.101 +/***********************************************************************
1.102 +** FUNCTION: NSSRWLock_UnlockRead
1.103 +** DESCRIPTION:
1.104 +** Release a Read lock. Unlocking an unlocked lock has undefined results.
1.105 +** INPUTS: NSSRWLock *lock - Lock to unlocked.
1.106 +** OUTPUTS: void
1.107 +** RETURN: void
1.108 +***********************************************************************/
1.109 +extern void NSSRWLock_UnlockRead(NSSRWLock *lock);
1.110 +
1.111 +/***********************************************************************
1.112 +** FUNCTION: NSSRWLock_UnlockWrite
1.113 +** DESCRIPTION:
1.114 +** Release a Write lock. Unlocking an unlocked lock has undefined results.
1.115 +** INPUTS: NSSRWLock *lock - Lock to unlocked.
1.116 +** OUTPUTS: void
1.117 +** RETURN: void
1.118 +***********************************************************************/
1.119 +extern void NSSRWLock_UnlockWrite(NSSRWLock *lock);
1.120 +
1.121 +/***********************************************************************
1.122 +** FUNCTION: NSSRWLock_HaveWriteLock
1.123 +** DESCRIPTION:
1.124 +** Tells caller whether the current thread holds the write lock, or not.
1.125 +** INPUTS: NSSRWLock *lock - Lock to test.
1.126 +** OUTPUTS: void
1.127 +** RETURN: PRBool PR_TRUE IFF the current thread holds the write lock.
1.128 +***********************************************************************/
1.129 +
1.130 +extern PRBool NSSRWLock_HaveWriteLock(NSSRWLock *rwlock);
1.131 +
1.132 +/* SEC_END_PROTOS */
1.133 +PR_END_EXTERN_C
1.134 +
1.135 +#endif /* nsrwlock_h___ */
