Back to index

lightning-sunbird  0.9+nobinonly
nssrwlk.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 /*
00038 ** File:             nsrwlock.h
00039 ** Description:      API to basic reader-writer lock functions of NSS.
00040 **     These are re-entrant reader writer locks; that is,
00041 **     If I hold the write lock, I can ask for it and get it again.
00042 **     If I hold the write lock, I can also ask for and get a read lock.
00043 **      I can then release the locks in any order (read or write).
00044 **     I must release each lock type as many times as I acquired it.
00045 **     Otherwise, these are normal reader/writer locks.
00046 **
00047 ** For deadlock detection, locks should be ranked, and no lock may be aquired
00048 ** while I hold a lock of higher rank number.
00049 ** If you don't want that feature, always use NSS_RWLOCK_RANK_NONE.
00050 ** Lock name is for debugging, and is optional (may be NULL)
00051 **/
00052 
00053 #ifndef nssrwlk_h___
00054 #define nssrwlk_h___
00055 
00056 #include "prtypes.h"
00057 #include "nssrwlkt.h"
00058 
00059 #define       NSS_RWLOCK_RANK_NONE 0
00060 
00061 /* SEC_BEGIN_PROTOS */
00062 PR_BEGIN_EXTERN_C
00063 
00064 /***********************************************************************
00065 ** FUNCTION:    NSSRWLock_New
00066 ** DESCRIPTION:
00067 **  Returns a pointer to a newly created reader-writer lock object.
00068 ** INPUTS:      Lock rank
00069 **            Lock name
00070 ** OUTPUTS:     void
00071 ** RETURN:      NSSRWLock*
00072 **   If the lock cannot be created because of resource constraints, NULL
00073 **   is returned.
00074 **  
00075 ***********************************************************************/
00076 PR_EXTERN(NSSRWLock*) NSSRWLock_New(PRUint32 lock_rank, const char *lock_name);
00077 
00078 /***********************************************************************
00079 ** FUNCTION:    NSSRWLock_AtomicCreate
00080 ** DESCRIPTION:
00081 **  Given the address of a NULL pointer to a NSSRWLock, 
00082 **  atomically initializes that pointer to a newly created NSSRWLock.
00083 **  Returns the value placed into that pointer, or NULL.
00084 **
00085 ** INPUTS:      address of NSRWLock pointer
00086 **              Lock rank
00087 **            Lock name
00088 ** OUTPUTS:     NSSRWLock*
00089 ** RETURN:      NSSRWLock*
00090 **   If the lock cannot be created because of resource constraints, 
00091 **   the pointer will be left NULL.
00092 **  
00093 ***********************************************************************/
00094 PR_EXTERN(NSSRWLock *)
00095 nssRWLock_AtomicCreate( NSSRWLock  ** prwlock, 
00096                      PRUint32      lock_rank, 
00097                      const char *  lock_name);
00098 
00099 /***********************************************************************
00100 ** FUNCTION:    NSSRWLock_Destroy
00101 ** DESCRIPTION:
00102 **  Destroys a given RW lock object.
00103 ** INPUTS:      NSSRWLock *lock - Lock to be freed.
00104 ** OUTPUTS:     void
00105 ** RETURN:      None
00106 ***********************************************************************/
00107 PR_EXTERN(void) NSSRWLock_Destroy(NSSRWLock *lock);
00108 
00109 /***********************************************************************
00110 ** FUNCTION:    NSSRWLock_LockRead
00111 ** DESCRIPTION:
00112 **  Apply a read lock (non-exclusive) on a RWLock
00113 ** INPUTS:      NSSRWLock *lock - Lock to be read-locked.
00114 ** OUTPUTS:     void
00115 ** RETURN:      None
00116 ***********************************************************************/
00117 PR_EXTERN(void) NSSRWLock_LockRead(NSSRWLock *lock);
00118 
00119 /***********************************************************************
00120 ** FUNCTION:    NSSRWLock_LockWrite
00121 ** DESCRIPTION:
00122 **  Apply a write lock (exclusive) on a RWLock
00123 ** INPUTS:      NSSRWLock *lock - Lock to write-locked.
00124 ** OUTPUTS:     void
00125 ** RETURN:      None
00126 ***********************************************************************/
00127 PR_EXTERN(void) NSSRWLock_LockWrite(NSSRWLock *lock);
00128 
00129 /***********************************************************************
00130 ** FUNCTION:    NSSRWLock_UnlockRead
00131 ** DESCRIPTION:
00132 **  Release a Read lock. Unlocking an unlocked lock has undefined results.
00133 ** INPUTS:      NSSRWLock *lock - Lock to unlocked.
00134 ** OUTPUTS:     void
00135 ** RETURN:      void
00136 ***********************************************************************/
00137 PR_EXTERN(void) NSSRWLock_UnlockRead(NSSRWLock *lock);
00138 
00139 /***********************************************************************
00140 ** FUNCTION:    NSSRWLock_UnlockWrite
00141 ** DESCRIPTION:
00142 **  Release a Write lock. Unlocking an unlocked lock has undefined results.
00143 ** INPUTS:      NSSRWLock *lock - Lock to unlocked.
00144 ** OUTPUTS:     void
00145 ** RETURN:      void
00146 ***********************************************************************/
00147 PR_EXTERN(void) NSSRWLock_UnlockWrite(NSSRWLock *lock);
00148 
00149 /***********************************************************************
00150 ** FUNCTION:    NSSRWLock_HaveWriteLock
00151 ** DESCRIPTION:
00152 **  Tells caller whether the current thread holds the write lock, or not.
00153 ** INPUTS:      NSSRWLock *lock - Lock to test.
00154 ** OUTPUTS:     void
00155 ** RETURN:      PRBool      PR_TRUE IFF the current thread holds the write lock.
00156 ***********************************************************************/
00157 
00158 PR_EXTERN(PRBool) NSSRWLock_HaveWriteLock(NSSRWLock *rwlock);
00159 
00160 /* SEC_END_PROTOS */
00161 PR_END_EXTERN_C
00162 
00163 #endif /* nsrwlock_h___ */