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 ** nssilock.h - Instrumented locking functions for NSS 7 ** 8 ** Description: 9 ** nssilock provides instrumentation for locks and monitors in 10 ** the NSS libraries. The instrumentation, when enabled, causes 11 ** each call to the instrumented function to record data about 12 ** the call to an external file. The external file 13 ** subsequently used to extract performance data and other 14 ** statistical information about the operation of locks used in 15 ** the nss library. 16 ** 17 ** To enable compilation with instrumentation, build NSS with 18 ** the compile time switch NEED_NSS_ILOCK defined. 19 ** 20 ** say: "gmake OS_CFLAGS+=-DNEED_NSS_ILOCK" at make time. 21 ** 22 ** At runtime, to enable recording from nssilock, one or more 23 ** environment variables must be set. For each nssILockType to 24 ** be recorded, an environment variable of the form NSS_ILOCK_x 25 ** must be set to 1. For example: 26 ** 27 ** set NSS_ILOCK_Cert=1 28 ** 29 ** nssilock uses PRLOG is used to record to trace data. The 30 ** PRLogModule name associated with nssilock data is: "nssilock". 31 ** To enable recording of nssilock data you will need to set the 32 ** environment variable NSPR_LOG_MODULES to enable 33 ** recording for the nssilock log module. Similarly, you will 34 ** need to set the environment variable NSPR_LOG_FILE to specify 35 ** the filename to receive the recorded data. See prlog.h for usage. 36 ** Example: 37 ** 38 ** export NSPR_LOG_MODULES=nssilock:6 39 ** export NSPR_LOG_FILE=xxxLogfile 40 ** 41 ** Operation: 42 ** nssilock wraps calls to NSPR's PZLock and PZMonitor functions 43 ** with similarly named functions: PZ_NewLock(), etc. When NSS is 44 ** built with lock instrumentation enabled, the PZ* functions are 45 ** compiled into NSS; when lock instrumentation is disabled, 46 ** calls to PZ* functions are directly mapped to PR* functions 47 ** and the instrumentation arguments to the PZ* functions are 48 ** compiled away. 49 ** 50 ** 51 ** File Format: 52 ** The format of the external file is implementation 53 ** dependent. Where NSPR's PR_LOG() function is used, the file 54 ** contains data defined for PR_LOG() plus the data written by 55 ** the wrapped function. On some platforms and under some 56 ** circumstances, platform dependent logging or 57 ** instrumentation probes may be used. In any case, the 58 ** relevant data provided by the lock instrumentation is: 59 ** 60 ** lockType, func, address, duration, line, file [heldTime] 61 ** 62 ** where: 63 ** 64 ** lockType: a character representation of nssILockType for the 65 ** call. e.g. ... "cert" 66 ** 67 ** func: the function doing the tracing. e.g. "NewLock" 68 ** 69 ** address: address of the instrumented lock or monitor 70 ** 71 ** duration: is how long was spent in the instrumented function, 72 ** in PRIntervalTime "ticks". 73 ** 74 ** line: the line number within the calling function 75 ** 76 ** file: the file from which the call was made 77 ** 78 ** heldTime: how long the lock/monitor was held. field 79 ** present only for PZ_Unlock() and PZ_ExitMonitor(). 80 ** 81 ** Design Notes: 82 ** The design for lock instrumentation was influenced by the 83 ** need to gather performance data on NSS 3.x. It is intended 84 ** that the effort to modify NSS to use lock instrumentation 85 ** be minimized. Existing calls to locking functions need only 86 ** have their names changed to the instrumentation function 87 ** names. 88 ** 89 ** Private NSS Interface: 90 ** nssilock.h defines a private interface for use by NSS. 91 ** nssilock.h is experimental in nature and is subject to 92 ** change or revocation without notice. ... Don't mess with 93 ** it. 94 ** 95 */ 96 97 /* 98 * $Id: 99 */ 100 101 #ifndef _NSSILOCK_H_ 102 #define _NSSILOCK_H_ 103 104 #include "utilrename.h" 105 #include "prtypes.h" 106 #include "prmon.h" 107 #include "prlock.h" 108 #include "prcvar.h" 109 110 #include "nssilckt.h" 111 112 PR_BEGIN_EXTERN_C 113 114 #if defined(NEED_NSS_ILOCK) 115 116 #define PZ_NewLock(t) pz_NewLock((t), __FILE__, __LINE__) 117 extern PZLock * 118 pz_NewLock( 119 nssILockType ltype, 120 char *file, 121 PRIntn line); 122 123 #define PZ_Lock(k) pz_Lock((k), __FILE__, __LINE__) 124 extern void 125 pz_Lock( 126 PZLock *lock, 127 char *file, 128 PRIntn line); 129 130 #define PZ_Unlock(k) pz_Unlock((k), __FILE__, __LINE__) 131 extern PRStatus 132 pz_Unlock( 133 PZLock *lock, 134 char *file, 135 PRIntn line); 136 137 #define PZ_DestroyLock(k) pz_DestroyLock((k), __FILE__, __LINE__) 138 extern void 139 pz_DestroyLock( 140 PZLock *lock, 141 char *file, 142 PRIntn line); 143 144 #define PZ_NewCondVar(l) pz_NewCondVar((l), __FILE__, __LINE__) 145 extern PZCondVar * 146 pz_NewCondVar( 147 PZLock *lock, 148 char *file, 149 PRIntn line); 150 151 #define PZ_DestroyCondVar(v) pz_DestroyCondVar((v), __FILE__, __LINE__) 152 extern void 153 pz_DestroyCondVar( 154 PZCondVar *cvar, 155 char *file, 156 PRIntn line); 157 158 #define PZ_WaitCondVar(v, t) pz_WaitCondVar((v), (t), __FILE__, __LINE__) 159 extern PRStatus 160 pz_WaitCondVar( 161 PZCondVar *cvar, 162 PRIntervalTime timeout, 163 char *file, 164 PRIntn line); 165 166 #define PZ_NotifyCondVar(v) pz_NotifyCondVar((v), __FILE__, __LINE__) 167 extern PRStatus 168 pz_NotifyCondVar( 169 PZCondVar *cvar, 170 char *file, 171 PRIntn line); 172 173 #define PZ_NotifyAllCondVar(v) pz_NotifyAllCondVar((v), __FILE__, __LINE__) 174 extern PRStatus 175 pz_NotifyAllCondVar( 176 PZCondVar *cvar, 177 char *file, 178 PRIntn line); 179 180 #define PZ_NewMonitor(t) pz_NewMonitor((t), __FILE__, __LINE__) 181 extern PZMonitor * 182 pz_NewMonitor( 183 nssILockType ltype, 184 char *file, 185 PRIntn line); 186 187 #define PZ_DestroyMonitor(m) pz_DestroyMonitor((m), __FILE__, __LINE__) 188 extern void 189 pz_DestroyMonitor( 190 PZMonitor *mon, 191 char *file, 192 PRIntn line); 193 194 #define PZ_EnterMonitor(m) pz_EnterMonitor((m), __FILE__, __LINE__) 195 extern void 196 pz_EnterMonitor( 197 PZMonitor *mon, 198 char *file, 199 PRIntn line); 200 201 #define PZ_ExitMonitor(m) pz_ExitMonitor((m), __FILE__, __LINE__) 202 extern PRStatus 203 pz_ExitMonitor( 204 PZMonitor *mon, 205 char *file, 206 PRIntn line); 207 208 #define PZ_InMonitor(m) (PZ_GetMonitorEntryCount(m) > 0) 209 #define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m), __FILE__, __LINE__) 210 extern PRIntn 211 pz_GetMonitorEntryCount( 212 PZMonitor *mon, 213 char *file, 214 PRIntn line); 215 216 #define PZ_Wait(m, i) pz_Wait((m), ((i)), __FILE__, __LINE__) 217 extern PRStatus 218 pz_Wait( 219 PZMonitor *mon, 220 PRIntervalTime ticks, 221 char *file, 222 PRIntn line); 223 224 #define PZ_Notify(m) pz_Notify((m), __FILE__, __LINE__) 225 extern PRStatus 226 pz_Notify( 227 PZMonitor *mon, 228 char *file, 229 PRIntn line); 230 231 #define PZ_NotifyAll(m) pz_NotifyAll((m), __FILE__, __LINE__) 232 extern PRStatus 233 pz_NotifyAll( 234 PZMonitor *mon, 235 char *file, 236 PRIntn line); 237 238 #define PZ_TraceFlush() pz_TraceFlush() 239 extern void pz_TraceFlush(void); 240 241 #else /* NEED_NSS_ILOCK */ 242 243 #define PZ_NewLock(t) PR_NewLock() 244 #define PZ_DestroyLock(k) PR_DestroyLock((k)) 245 #define PZ_Lock(k) PR_Lock((k)) 246 #define PZ_Unlock(k) PR_Unlock((k)) 247 248 #define PZ_NewCondVar(l) PR_NewCondVar((l)) 249 #define PZ_DestroyCondVar(v) PR_DestroyCondVar((v)) 250 #define PZ_WaitCondVar(v, t) PR_WaitCondVar((v), (t)) 251 #define PZ_NotifyCondVar(v) PR_NotifyCondVar((v)) 252 #define PZ_NotifyAllCondVar(v) PR_NotifyAllCondVar((v)) 253 254 #define PZ_NewMonitor(t) PR_NewMonitor() 255 #define PZ_DestroyMonitor(m) PR_DestroyMonitor((m)) 256 #define PZ_EnterMonitor(m) PR_EnterMonitor((m)) 257 #define PZ_ExitMonitor(m) PR_ExitMonitor((m)) 258 #define PZ_InMonitor(m) PR_InMonitor((m)) 259 #define PZ_Wait(m, t) PR_Wait(((m)), ((t))) 260 #define PZ_Notify(m) PR_Notify((m)) 261 #define PZ_NotifyAll(m) PR_Notify((m)) 262 #define PZ_TraceFlush() /* nothing */ 263 264 #endif /* NEED_NSS_ILOCK */ 265 266 PR_END_EXTERN_C 267 #endif /* _NSSILOCK_H_ */ 268