/* * The contents of this file are subject to the Mozilla Public * License Version 1.1 (the "License"); you may not use this file * except in compliance with the License. You may obtain a copy of * the License at http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or * implied. See the License for the specific language governing * rights and limitations under the License. * * The Original Code is the Netscape security libraries. * * The Initial Developer of the Original Code is Netscape * Communications Corporation. Portions created by Netscape are * Copyright (C) 1994-2000 Netscape Communications Corporation. All * Rights Reserved. * * Contributor(s): * * Alternatively, the contents of this file may be used under the * terms of the GNU General Public License Version 2 or later (the * "GPL"), in which case the provisions of the GPL are applicable * instead of those above. If you wish to allow use of your * version of this file only under the terms of the GPL and not to * allow others to use your version of this file under the MPL, * indicate your decision by deleting the provisions above and * replace them with the notice and other provisions required by * the GPL. If you do not delete the provisions above, a recipient * may use your version of this file under either the MPL or the * GPL. */ /* ** nssilock.h - Instrumented locking functions for NSS ** ** Description: ** nssilock provides instrumentation for locks and monitors in ** the NSS libraries. The instrumentation, when enabled, causes ** each call to the instrumented function to record data about ** the call to an external file. The external file ** subsequently used to extract performance data and other ** statistical information about the operation of locks used in ** the nss library. ** ** To enable compilation with instrumentation, build NSS with ** the compile time switch NEED_NSS_ILOCK defined. ** ** say: "gmake OS_CFLAGS+=-DNEED_NSS_ILOCK" at make time. ** ** At runtime, to enable recording from nssilock, one or more ** environment variables must be set. For each nssILockType to ** be recorded, an environment variable of the form NSS_ILOCK_x ** must be set to 1. For example: ** ** set NSS_ILOCK_Cert=1 ** ** nssilock uses PRLOG is used to record to trace data. The ** PRLogModule name associated with nssilock data is: "nssilock". ** To enable recording of nssilock data you will need to set the ** environment variable NSPR_LOG_MODULES to enable ** recording for the nssilock log module. Similarly, you will ** need to set the environment variable NSPR_LOG_FILE to specify ** the filename to receive the recorded data. See prlog.h for usage. ** Example: ** ** export NSPR_LOG_MODULES=nssilock:6 ** export NSPR_LOG_FILE=xxxLogfile ** ** Operation: ** nssilock wraps calls to NSPR's PZLock and PZMonitor functions ** with similarly named functions: PZ_NewLock(), etc. When NSS is ** built with lock instrumentation enabled, the PZ* functions are ** compiled into NSS; when lock instrumentation is disabled, ** calls to PZ* functions are directly mapped to PR* functions ** and the instrumentation arguments to the PZ* functions are ** compiled away. ** ** ** File Format: ** The format of the external file is implementation ** dependent. Where NSPR's PR_LOG() function is used, the file ** contains data defined for PR_LOG() plus the data written by ** the wrapped function. On some platforms and under some ** circumstances, platform dependent logging or ** instrumentation probes may be used. In any case, the ** relevant data provided by the lock instrumentation is: ** ** lockType, func, address, duration, line, file [heldTime] ** ** where: ** ** lockType: a character representation of nssILockType for the ** call. e.g. ... "cert" ** ** func: the function doing the tracing. e.g. "NewLock" ** ** address: address of the instrumented lock or monitor ** ** duration: is how long was spent in the instrumented function, ** in PRIntervalTime "ticks". ** ** line: the line number within the calling function ** ** file: the file from which the call was made ** ** heldTime: how long the lock/monitor was held. field ** present only for PZ_Unlock() and PZ_ExitMonitor(). ** ** Design Notes: ** The design for lock instrumentation was influenced by the ** need to gather performance data on NSS 3.x. It is intended ** that the effort to modify NSS to use lock instrumentation ** be minimized. Existing calls to locking functions need only ** have their names changed to the instrumentation function ** names. ** ** Private NSS Interface: ** nssilock.h defines a private interface for use by NSS. ** nssilock.h is experimental in nature and is subject to ** change or revocation without notice. ... Don't mess with ** it. ** */ /* * $Id: */ #ifndef _NSSILOCK_H_ #define _NSSILOCK_H_ #include "prtypes.h" #include "prmon.h" #include "prlock.h" #include "prcvar.h" #include "nssilckt.h" PR_BEGIN_EXTERN_C #if defined(NEED_NSS_ILOCK) #define PZ_NewLock(t) pz_NewLock((t),__FILE__,__LINE__) extern PZLock * pz_NewLock( nssILockType ltype, char *file, PRIntn line ); #define PZ_Lock(k) pz_Lock((k),__FILE__,__LINE__) extern void pz_Lock( PZLock *lock, char *file, PRIntn line ); #define PZ_Unlock(k) pz_Unlock((k),__FILE__,__LINE__) extern PRStatus pz_Unlock( PZLock *lock, char *file, PRIntn line ); #define PZ_DestroyLock(k) pz_DestroyLock((k),__FILE__,__LINE__) extern void pz_DestroyLock( PZLock *lock, char *file, PRIntn line ); #define PZ_NewCondVar(l) pz_NewCondVar((l),__FILE__,__LINE__) extern PZCondVar * pz_NewCondVar( PZLock *lock, char *file, PRIntn line ); #define PZ_DestroyCondVar(v) pz_DestroyCondVar((v),__FILE__,__LINE__) extern void pz_DestroyCondVar( PZCondVar *cvar, char *file, PRIntn line ); #define PZ_WaitCondVar(v,t) pz_WaitCondVar((v),(t),__FILE__,__LINE__) extern PRStatus pz_WaitCondVar( PZCondVar *cvar, PRIntervalTime timeout, char *file, PRIntn line ); #define PZ_NotifyCondVar(v) pz_NotifyCondVar((v),__FILE__,__LINE__) extern PRStatus pz_NotifyCondVar( PZCondVar *cvar, char *file, PRIntn line ); #define PZ_NotifyAllCondVar(v) pz_NotifyAllCondVar((v),__FILE__,__LINE__) extern PRStatus pz_NotifyAllCondVar( PZCondVar *cvar, char *file, PRIntn line ); #define PZ_NewMonitor(t) pz_NewMonitor((t),__FILE__,__LINE__) extern PZMonitor * pz_NewMonitor( nssILockType ltype, char *file, PRIntn line ); #define PZ_DestroyMonitor(m) pz_DestroyMonitor((m),__FILE__,__LINE__) extern void pz_DestroyMonitor( PZMonitor *mon, char *file, PRIntn line ); #define PZ_EnterMonitor(m) pz_EnterMonitor((m),__FILE__,__LINE__) extern void pz_EnterMonitor( PZMonitor *mon, char *file, PRIntn line ); #define PZ_ExitMonitor(m) pz_ExitMonitor((m),__FILE__,__LINE__) extern PRStatus pz_ExitMonitor( PZMonitor *mon, char *file, PRIntn line ); #define PZ_InMonitor(m) (PZ_GetMonitorEntryCount(m) > 0 ) #define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m),__FILE__,__LINE__) extern PRIntn pz_GetMonitorEntryCount( PZMonitor *mon, char *file, PRIntn line ); #define PZ_Wait(m,i) pz_Wait((m),((i)),__FILE__,__LINE__) extern PRStatus pz_Wait( PZMonitor *mon, PRIntervalTime ticks, char *file, PRIntn line ); #define PZ_Notify(m) pz_Notify((m),__FILE__,__LINE__) extern PRStatus pz_Notify( PZMonitor *mon, char *file, PRIntn line ); #define PZ_NotifyAll(m) pz_NotifyAll((m),__FILE__,__LINE__) extern PRStatus pz_NotifyAll( PZMonitor *mon, char *file, PRIntn line ); #define PZ_TraceFlush() pz_TraceFlush() extern void pz_TraceFlush( void ); #else /* NEED_NSS_ILOCK */ #define PZ_NewLock(t) PR_NewLock() #define PZ_DestroyLock(k) PR_DestroyLock((k)) #define PZ_Lock(k) PR_Lock((k)) #define PZ_Unlock(k) PR_Unlock((k)) #define PZ_NewCondVar(l) PR_NewCondVar((l)) #define PZ_DestroyCondVar(v) PR_DestroyCondVar((v)) #define PZ_WaitCondVar(v,t) PR_WaitCondVar((v),(t)) #define PZ_NotifyCondVar(v) PR_NotifyCondVar((v)) #define PZ_NotifyAllCondVar(v) PR_NotifyAllCondVar((v)) #define PZ_NewMonitor(t) PR_NewMonitor() #define PZ_DestroyMonitor(m) PR_DestroyMonitor((m)) #define PZ_EnterMonitor(m) PR_EnterMonitor((m)) #define PZ_ExitMonitor(m) PR_ExitMonitor((m)) #define PZ_InMonitor(m) PR_InMonitor((m)) #define PZ_Wait(m,t) PR_Wait(((m)),((t))) #define PZ_Notify(m) PR_Notify((m)) #define PZ_NotifyAll(m) PR_Notify((m)) #define PZ_TraceFlush() /* nothing */ #endif /* NEED_NSS_ILOCK */ PR_END_EXTERN_C #endif /* _NSSILOCK_H_ */