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