Back to index

lightning-sunbird  0.9+nobinonly
nssilock.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 ** nssilock.h - Instrumented locking functions for NSS
00039 **
00040 ** Description:
00041 **    nssilock provides instrumentation for locks and monitors in
00042 **    the NSS libraries. The instrumentation, when enabled, causes
00043 **    each call to the instrumented function to record data about
00044 **    the call to an external file. The external file
00045 **    subsequently used to extract performance data and other
00046 **    statistical information about the operation of locks used in
00047 **    the nss library.
00048 **     
00049 **    To enable compilation with instrumentation, build NSS with 
00050 **    the compile time switch NEED_NSS_ILOCK defined.
00051 **
00052 **    say:  "gmake OS_CFLAGS+=-DNEED_NSS_ILOCK" at make time.
00053 **
00054 **    At runtime, to enable recording from nssilock, one or more
00055 **    environment variables must be set. For each nssILockType to
00056 **    be recorded, an environment variable of the form NSS_ILOCK_x
00057 **    must be set to 1. For example:
00058 **
00059 **       set NSS_ILOCK_Cert=1
00060 **
00061 **    nssilock uses PRLOG is used to record to trace data. The
00062 **    PRLogModule name associated with nssilock data is: "nssilock".
00063 **    To enable recording of nssilock data you will need to set the
00064 **    environment variable NSPR_LOG_MODULES to enable
00065 **    recording for the nssilock log module. Similarly, you will
00066 **    need to set the environment variable NSPR_LOG_FILE to specify
00067 **    the filename to receive the recorded data. See prlog.h for usage.
00068 **    Example:
00069 **
00070 **        export NSPR_LOG_MODULES=nssilock:6
00071 **        export NSPR_LOG_FILE=xxxLogfile
00072 **
00073 ** Operation:
00074 **    nssilock wraps calls to NSPR's PZLock and PZMonitor functions
00075 **    with similarly named functions: PZ_NewLock(), etc. When NSS is
00076 **    built with lock instrumentation enabled, the PZ* functions are
00077 **    compiled into NSS; when lock instrumentation is disabled,
00078 **    calls to PZ* functions are directly mapped to PR* functions
00079 **    and the instrumentation arguments to the PZ* functions are
00080 **    compiled away.
00081 **
00082 **
00083 ** File Format:
00084 **    The format of the external file is implementation
00085 **    dependent. Where NSPR's PR_LOG() function is used, the file
00086 **    contains data defined for PR_LOG() plus the data written by
00087 **    the wrapped function. On some platforms and under some
00088 **    circumstances, platform dependent logging or
00089 **    instrumentation probes may be used. In any case, the
00090 **    relevant data provided by the lock instrumentation is:
00091 **    
00092 **      lockType, func, address, duration, line, file [heldTime]
00093 ** 
00094 **    where:
00095 **    
00096 **       lockType: a character representation of nssILockType for the
00097 **       call. e.g. ... "cert"
00098 **    
00099 **       func: the function doing the tracing. e.g. "NewLock"
00100 **    
00101 **       address: address of the instrumented lock or monitor
00102 **    
00103 **       duration: is how long was spent in the instrumented function,
00104 **       in PRIntervalTime "ticks".
00105 **    
00106 **       line: the line number within the calling function
00107 **    
00108 **       file: the file from which the call was made
00109 **    
00110 **       heldTime: how long the lock/monitor was held. field
00111 **       present only for PZ_Unlock() and PZ_ExitMonitor().
00112 **    
00113 ** Design Notes:
00114 **    The design for lock instrumentation was influenced by the
00115 **    need to gather performance data on NSS 3.x. It is intended
00116 **    that the effort to modify NSS to use lock instrumentation
00117 **    be minimized. Existing calls to locking functions need only
00118 **    have their names changed to the instrumentation function
00119 **    names.
00120 **    
00121 ** Private NSS Interface:
00122 **    nssilock.h defines a private interface for use by NSS.
00123 **    nssilock.h is experimental in nature and is subject to
00124 **    change or revocation without notice. ... Don't mess with
00125 **    it.
00126 **    
00127 */
00128 
00129 /*
00130  * $Id:
00131  */
00132 
00133 #ifndef _NSSILOCK_H_
00134 #define _NSSILOCK_H_
00135 
00136 #include "prtypes.h"
00137 #include "prmon.h"
00138 #include "prlock.h"
00139 #include "prcvar.h"
00140 
00141 #include "nssilckt.h"
00142 
00143 PR_BEGIN_EXTERN_C
00144 
00145 #if defined(NEED_NSS_ILOCK)
00146 
00147 #define PZ_NewLock(t) pz_NewLock((t),__FILE__,__LINE__)
00148 extern PZLock * 
00149     pz_NewLock(
00150         nssILockType ltype,
00151         char *file,
00152         PRIntn  line
00153     );
00154 
00155 #define PZ_Lock(k)  pz_Lock((k),__FILE__,__LINE__)
00156 extern void
00157     pz_Lock(
00158         PZLock *lock,
00159         char *file,
00160         PRIntn line
00161     );
00162 
00163 #define PZ_Unlock(k) pz_Unlock((k),__FILE__,__LINE__)
00164 extern PRStatus
00165     pz_Unlock(
00166         PZLock *lock,
00167         char *file,
00168         PRIntn line
00169     );
00170 
00171 #define PZ_DestroyLock(k) pz_DestroyLock((k),__FILE__,__LINE__)
00172 extern void
00173     pz_DestroyLock(
00174         PZLock *lock,
00175         char *file,
00176         PRIntn line
00177     );
00178 
00179 
00180 #define PZ_NewCondVar(l)        pz_NewCondVar((l),__FILE__,__LINE__)
00181 extern PZCondVar *
00182     pz_NewCondVar(
00183         PZLock *lock,
00184         char *file,
00185         PRIntn line
00186     );
00187 
00188 #define PZ_DestroyCondVar(v)    pz_DestroyCondVar((v),__FILE__,__LINE__)
00189 extern void
00190     pz_DestroyCondVar(
00191         PZCondVar *cvar,
00192         char *file,
00193         PRIntn line
00194     );
00195 
00196 #define PZ_WaitCondVar(v,t)       pz_WaitCondVar((v),(t),__FILE__,__LINE__)
00197 extern PRStatus
00198     pz_WaitCondVar(
00199         PZCondVar *cvar,
00200         PRIntervalTime timeout,
00201         char *file,
00202         PRIntn line
00203     );
00204 
00205 #define PZ_NotifyCondVar(v)     pz_NotifyCondVar((v),__FILE__,__LINE__)
00206 extern PRStatus
00207     pz_NotifyCondVar(
00208         PZCondVar *cvar,
00209         char *file,
00210         PRIntn line
00211     );
00212 
00213 #define PZ_NotifyAllCondVar(v)  pz_NotifyAllCondVar((v),__FILE__,__LINE__)
00214 extern PRStatus
00215     pz_NotifyAllCondVar(
00216         PZCondVar *cvar,
00217         char *file,
00218         PRIntn line
00219     );
00220 
00221 
00222 #define PZ_NewMonitor(t) pz_NewMonitor((t),__FILE__,__LINE__)
00223 extern PZMonitor *
00224     pz_NewMonitor( 
00225         nssILockType ltype,
00226         char *file,
00227         PRIntn line
00228     );
00229 
00230 #define PZ_DestroyMonitor(m) pz_DestroyMonitor((m),__FILE__,__LINE__)
00231 extern void
00232     pz_DestroyMonitor(
00233         PZMonitor *mon,
00234         char *file,
00235         PRIntn line
00236     );
00237 
00238 #define PZ_EnterMonitor(m) pz_EnterMonitor((m),__FILE__,__LINE__)
00239 extern void
00240     pz_EnterMonitor(
00241         PZMonitor *mon,
00242         char *file,
00243         PRIntn line
00244     );
00245 
00246 
00247 #define PZ_ExitMonitor(m) pz_ExitMonitor((m),__FILE__,__LINE__)
00248 extern PRStatus
00249     pz_ExitMonitor(
00250         PZMonitor *mon,
00251         char *file,
00252         PRIntn line
00253     );
00254 
00255 #define PZ_InMonitor(m)  (PZ_GetMonitorEntryCount(m) > 0 )
00256 #define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m),__FILE__,__LINE__)
00257 extern PRIntn
00258     pz_GetMonitorEntryCount(
00259         PZMonitor *mon,
00260         char *file,
00261         PRIntn line
00262     );
00263 
00264 #define PZ_Wait(m,i) pz_Wait((m),((i)),__FILE__,__LINE__)
00265 extern PRStatus
00266     pz_Wait(
00267         PZMonitor *mon,
00268         PRIntervalTime ticks,
00269         char *file,
00270         PRIntn line
00271     );
00272 
00273 #define PZ_Notify(m) pz_Notify((m),__FILE__,__LINE__)
00274 extern PRStatus
00275     pz_Notify(
00276         PZMonitor *mon,
00277         char *file,
00278         PRIntn line
00279     );
00280 
00281 #define PZ_NotifyAll(m) pz_NotifyAll((m),__FILE__,__LINE__)
00282 extern PRStatus
00283     pz_NotifyAll(
00284         PZMonitor *mon,
00285         char *file,
00286         PRIntn line
00287     );
00288 
00289 #define PZ_TraceFlush() pz_TraceFlush()
00290 extern void pz_TraceFlush( void );
00291 
00292 #else /* NEED_NSS_ILOCK */
00293 
00294 #define PZ_NewLock(t)           PR_NewLock()
00295 #define PZ_DestroyLock(k)       PR_DestroyLock((k))
00296 #define PZ_Lock(k)              PR_Lock((k))
00297 #define PZ_Unlock(k)            PR_Unlock((k))
00298 
00299 #define PZ_NewCondVar(l)        PR_NewCondVar((l))
00300 #define PZ_DestroyCondVar(v)    PR_DestroyCondVar((v))
00301 #define PZ_WaitCondVar(v,t)     PR_WaitCondVar((v),(t))
00302 #define PZ_NotifyCondVar(v)     PR_NotifyCondVar((v))
00303 #define PZ_NotifyAllCondVar(v)  PR_NotifyAllCondVar((v))
00304 
00305 #define PZ_NewMonitor(t)        PR_NewMonitor()
00306 #define PZ_DestroyMonitor(m)    PR_DestroyMonitor((m))
00307 #define PZ_EnterMonitor(m)      PR_EnterMonitor((m))
00308 #define PZ_ExitMonitor(m)       PR_ExitMonitor((m))
00309 #define PZ_InMonitor(m)         PR_InMonitor((m))
00310 #define PZ_Wait(m,t)            PR_Wait(((m)),((t)))
00311 #define PZ_Notify(m)            PR_Notify((m))
00312 #define PZ_NotifyAll(m)         PR_Notify((m))
00313 #define PZ_TraceFlush()         /* nothing */
00314 
00315     
00316 #endif /* NEED_NSS_ILOCK */
00317 
00318 PR_END_EXTERN_C
00319 #endif /* _NSSILOCK_H_ */