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 _NSSILCKT_H_ 131#define _NSSILCKT_H_ 132 133#include "prtypes.h" 134#include "prmon.h" 135#include "prlock.h" 136#include "prcvar.h" 137 138typedef enum { 139 nssILockArena = 0, 140 nssILockSession = 1, 141 nssILockObject = 2, 142 nssILockRefLock = 3, 143 nssILockCert = 4, 144 nssILockCertDB = 5, 145 nssILockDBM = 6, 146 nssILockCache = 7, 147 nssILockSSL = 8, 148 nssILockList = 9, 149 nssILockSlot = 10, 150 nssILockFreelist = 11, 151 nssILockOID = 12, 152 nssILockAttribute = 13, 153 nssILockPK11cxt = 14, /* pk11context */ 154 nssILockRWLock = 15, 155 nssILockOther = 16, 156 nssILockSelfServ = 17, 157 nssILockLast /* don't use this one! */ 158} nssILockType; 159 160/* 161** Declare operation type enumerator 162** enumerations identify the function being performed 163*/ 164typedef enum { 165 FlushTT = 0, 166 NewLock = 1, 167 Lock = 2, 168 Unlock = 3, 169 DestroyLock = 4, 170 NewCondVar = 5, 171 WaitCondVar = 6, 172 NotifyCondVar = 7, 173 NotifyAllCondVar = 8, 174 DestroyCondVar = 9, 175 NewMonitor = 10, 176 EnterMonitor = 11, 177 ExitMonitor = 12, 178 Notify = 13, 179 NotifyAll = 14, 180 Wait = 15, 181 DestroyMonitor = 16 182} nssILockOp; 183 184/* 185** Declare the trace record 186*/ 187struct pzTrace_s { 188 PRUint32 threadID; /* PR_GetThreadID() */ 189 nssILockOp op; /* operation being performed */ 190 nssILockType ltype; /* lock type identifier */ 191 PRIntervalTime callTime; /* time spent in function */ 192 PRIntervalTime heldTime; /* lock held time, or -1 */ 193 void *lock; /* address of lock structure */ 194 PRIntn line; /* line number */ 195 char file[24]; /* filename */ 196}; 197 198PR_BEGIN_EXTERN_C 199/* 200** conditionally compile in nssilock features 201*/ 202#if defined(NEED_NSS_ILOCK) 203 204/* 205** declare opaque types. See: nssilock.c 206*/ 207typedef struct pzlock_s PZLock; 208typedef struct pzcondvar_s PZCondVar; 209typedef struct pzmonitor_s PZMonitor; 210 211#else /* NEED_NSS_ILOCK */ 212 213#define PZLock PRLock 214#define PZCondVar PRCondVar 215#define PZMonitor PRMonitor 216 217#endif /* NEED_NSS_ILOCK */ 218 219PR_END_EXTERN_C 220#endif /* _NSSILCKT_H_ */ 221