The Tor Browser / file comparison
comparison: security/nss/lib/util/nssilock.h
security/nss/lib/util/nssilock.h
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:f06c66d9326b |
|---|---|
| 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 | |
| 124 #define PZ_Lock(k) pz_Lock((k),__FILE__,__LINE__) | |
| 125 extern void | |
| 126 pz_Lock( | |
| 127 PZLock *lock, | |
| 128 char *file, | |
| 129 PRIntn line | |
| 130 ); | |
| 131 | |
| 132 #define PZ_Unlock(k) pz_Unlock((k),__FILE__,__LINE__) | |
| 133 extern PRStatus | |
| 134 pz_Unlock( | |
| 135 PZLock *lock, | |
| 136 char *file, | |
| 137 PRIntn line | |
| 138 ); | |
| 139 | |
| 140 #define PZ_DestroyLock(k) pz_DestroyLock((k),__FILE__,__LINE__) | |
| 141 extern void | |
| 142 pz_DestroyLock( | |
| 143 PZLock *lock, | |
| 144 char *file, | |
| 145 PRIntn line | |
| 146 ); | |
| 147 | |
| 148 | |
| 149 #define PZ_NewCondVar(l) pz_NewCondVar((l),__FILE__,__LINE__) | |
| 150 extern PZCondVar * | |
| 151 pz_NewCondVar( | |
| 152 PZLock *lock, | |
| 153 char *file, | |
| 154 PRIntn line | |
| 155 ); | |
| 156 | |
| 157 #define PZ_DestroyCondVar(v) pz_DestroyCondVar((v),__FILE__,__LINE__) | |
| 158 extern void | |
| 159 pz_DestroyCondVar( | |
| 160 PZCondVar *cvar, | |
| 161 char *file, | |
| 162 PRIntn line | |
| 163 ); | |
| 164 | |
| 165 #define PZ_WaitCondVar(v,t) pz_WaitCondVar((v),(t),__FILE__,__LINE__) | |
| 166 extern PRStatus | |
| 167 pz_WaitCondVar( | |
| 168 PZCondVar *cvar, | |
| 169 PRIntervalTime timeout, | |
| 170 char *file, | |
| 171 PRIntn line | |
| 172 ); | |
| 173 | |
| 174 #define PZ_NotifyCondVar(v) pz_NotifyCondVar((v),__FILE__,__LINE__) | |
| 175 extern PRStatus | |
| 176 pz_NotifyCondVar( | |
| 177 PZCondVar *cvar, | |
| 178 char *file, | |
| 179 PRIntn line | |
| 180 ); | |
| 181 | |
| 182 #define PZ_NotifyAllCondVar(v) pz_NotifyAllCondVar((v),__FILE__,__LINE__) | |
| 183 extern PRStatus | |
| 184 pz_NotifyAllCondVar( | |
| 185 PZCondVar *cvar, | |
| 186 char *file, | |
| 187 PRIntn line | |
| 188 ); | |
| 189 | |
| 190 | |
| 191 #define PZ_NewMonitor(t) pz_NewMonitor((t),__FILE__,__LINE__) | |
| 192 extern PZMonitor * | |
| 193 pz_NewMonitor( | |
| 194 nssILockType ltype, | |
| 195 char *file, | |
| 196 PRIntn line | |
| 197 ); | |
| 198 | |
| 199 #define PZ_DestroyMonitor(m) pz_DestroyMonitor((m),__FILE__,__LINE__) | |
| 200 extern void | |
| 201 pz_DestroyMonitor( | |
| 202 PZMonitor *mon, | |
| 203 char *file, | |
| 204 PRIntn line | |
| 205 ); | |
| 206 | |
| 207 #define PZ_EnterMonitor(m) pz_EnterMonitor((m),__FILE__,__LINE__) | |
| 208 extern void | |
| 209 pz_EnterMonitor( | |
| 210 PZMonitor *mon, | |
| 211 char *file, | |
| 212 PRIntn line | |
| 213 ); | |
| 214 | |
| 215 | |
| 216 #define PZ_ExitMonitor(m) pz_ExitMonitor((m),__FILE__,__LINE__) | |
| 217 extern PRStatus | |
| 218 pz_ExitMonitor( | |
| 219 PZMonitor *mon, | |
| 220 char *file, | |
| 221 PRIntn line | |
| 222 ); | |
| 223 | |
| 224 #define PZ_InMonitor(m) (PZ_GetMonitorEntryCount(m) > 0 ) | |
| 225 #define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m),__FILE__,__LINE__) | |
| 226 extern PRIntn | |
| 227 pz_GetMonitorEntryCount( | |
| 228 PZMonitor *mon, | |
| 229 char *file, | |
| 230 PRIntn line | |
| 231 ); | |
| 232 | |
| 233 #define PZ_Wait(m,i) pz_Wait((m),((i)),__FILE__,__LINE__) | |
| 234 extern PRStatus | |
| 235 pz_Wait( | |
| 236 PZMonitor *mon, | |
| 237 PRIntervalTime ticks, | |
| 238 char *file, | |
| 239 PRIntn line | |
| 240 ); | |
| 241 | |
| 242 #define PZ_Notify(m) pz_Notify((m),__FILE__,__LINE__) | |
| 243 extern PRStatus | |
| 244 pz_Notify( | |
| 245 PZMonitor *mon, | |
| 246 char *file, | |
| 247 PRIntn line | |
| 248 ); | |
| 249 | |
| 250 #define PZ_NotifyAll(m) pz_NotifyAll((m),__FILE__,__LINE__) | |
| 251 extern PRStatus | |
| 252 pz_NotifyAll( | |
| 253 PZMonitor *mon, | |
| 254 char *file, | |
| 255 PRIntn line | |
| 256 ); | |
| 257 | |
| 258 #define PZ_TraceFlush() pz_TraceFlush() | |
| 259 extern void pz_TraceFlush( void ); | |
| 260 | |
| 261 #else /* NEED_NSS_ILOCK */ | |
| 262 | |
| 263 #define PZ_NewLock(t) PR_NewLock() | |
| 264 #define PZ_DestroyLock(k) PR_DestroyLock((k)) | |
| 265 #define PZ_Lock(k) PR_Lock((k)) | |
| 266 #define PZ_Unlock(k) PR_Unlock((k)) | |
| 267 | |
| 268 #define PZ_NewCondVar(l) PR_NewCondVar((l)) | |
| 269 #define PZ_DestroyCondVar(v) PR_DestroyCondVar((v)) | |
| 270 #define PZ_WaitCondVar(v,t) PR_WaitCondVar((v),(t)) | |
| 271 #define PZ_NotifyCondVar(v) PR_NotifyCondVar((v)) | |
| 272 #define PZ_NotifyAllCondVar(v) PR_NotifyAllCondVar((v)) | |
| 273 | |
| 274 #define PZ_NewMonitor(t) PR_NewMonitor() | |
| 275 #define PZ_DestroyMonitor(m) PR_DestroyMonitor((m)) | |
| 276 #define PZ_EnterMonitor(m) PR_EnterMonitor((m)) | |
| 277 #define PZ_ExitMonitor(m) PR_ExitMonitor((m)) | |
| 278 #define PZ_InMonitor(m) PR_InMonitor((m)) | |
| 279 #define PZ_Wait(m,t) PR_Wait(((m)),((t))) | |
| 280 #define PZ_Notify(m) PR_Notify((m)) | |
| 281 #define PZ_NotifyAll(m) PR_Notify((m)) | |
| 282 #define PZ_TraceFlush() /* nothing */ | |
| 283 | |
| 284 | |
| 285 #endif /* NEED_NSS_ILOCK */ | |
| 286 | |
| 287 PR_END_EXTERN_C | |
| 288 #endif /* _NSSILOCK_H_ */ |
