The Tor Browser / annotate

security/nss/lib/util/nssilock.h@b8a032363ba2 (annotated)

security/nss/lib/util/nssilock.h

Thu, 22 Jan 2015 13:21:57 +0100

author
Michael Schloh von Bennewitz <michael@schloh.com>
date
Thu, 22 Jan 2015 13:21:57 +0100
branch
TOR_BUG_9701
changeset 15
b8a032363ba2
permissions
-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

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

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial