nssilckt.h (5923B)
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 _NSSILCKT_H_ 102 #define _NSSILCKT_H_ 103 104 #include "utilrename.h" 105 #include "prtypes.h" 106 #include "prmon.h" 107 #include "prlock.h" 108 #include "prcvar.h" 109 110 typedef enum { 111 nssILockArena = 0, 112 nssILockSession = 1, 113 nssILockObject = 2, 114 nssILockRefLock = 3, 115 nssILockCert = 4, 116 nssILockCertDB = 5, 117 nssILockDBM = 6, 118 nssILockCache = 7, 119 nssILockSSL = 8, 120 nssILockList = 9, 121 nssILockSlot = 10, 122 nssILockFreelist = 11, 123 nssILockOID = 12, 124 nssILockAttribute = 13, 125 nssILockPK11cxt = 14, /* pk11context */ 126 nssILockRWLock = 15, 127 nssILockOther = 16, 128 nssILockSelfServ = 17, 129 nssILockKeyDB = 18, 130 nssILockLast /* don't use this one! */ 131 } nssILockType; 132 133 /* 134 ** conditionally compile in nssilock features 135 */ 136 #if defined(NEED_NSS_ILOCK) 137 138 /* 139 ** Declare operation type enumerator 140 ** enumerations identify the function being performed 141 */ 142 typedef enum { 143 FlushTT = 0, 144 NewLock = 1, 145 Lock = 2, 146 Unlock = 3, 147 DestroyLock = 4, 148 NewCondVar = 5, 149 WaitCondVar = 6, 150 NotifyCondVar = 7, 151 NotifyAllCondVar = 8, 152 DestroyCondVar = 9, 153 NewMonitor = 10, 154 EnterMonitor = 11, 155 ExitMonitor = 12, 156 Notify = 13, 157 NotifyAll = 14, 158 Wait = 15, 159 DestroyMonitor = 16 160 } nssILockOp; 161 162 /* 163 ** Declare the trace record 164 */ 165 struct pzTrace_s { 166 PRUint32 threadID; /* PR_GetThreadID() */ 167 nssILockOp op; /* operation being performed */ 168 nssILockType ltype; /* lock type identifier */ 169 PRIntervalTime callTime; /* time spent in function */ 170 PRIntervalTime heldTime; /* lock held time, or -1 */ 171 void *lock; /* address of lock structure */ 172 PRIntn line; /* line number */ 173 char file[24]; /* filename */ 174 }; 175 176 /* 177 ** declare opaque types. See: nssilock.c 178 */ 179 typedef struct pzlock_s PZLock; 180 typedef struct pzcondvar_s PZCondVar; 181 typedef struct pzmonitor_s PZMonitor; 182 183 #else /* NEED_NSS_ILOCK */ 184 185 #define PZLock PRLock 186 #define PZCondVar PRCondVar 187 #define PZMonitor PRMonitor 188 189 #endif /* NEED_NSS_ILOCK */ 190 191 #endif /* _NSSILCKT_H_ */