1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/util/nssilckt.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,191 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +/*
1.9 +** nssilock.h - Instrumented locking functions for NSS
1.10 +**
1.11 +** Description:
1.12 +** nssilock provides instrumentation for locks and monitors in
1.13 +** the NSS libraries. The instrumentation, when enabled, causes
1.14 +** each call to the instrumented function to record data about
1.15 +** the call to an external file. The external file
1.16 +** subsequently used to extract performance data and other
1.17 +** statistical information about the operation of locks used in
1.18 +** the nss library.
1.19 +**
1.20 +** To enable compilation with instrumentation, build NSS with
1.21 +** the compile time switch NEED_NSS_ILOCK defined.
1.22 +**
1.23 +** say: "gmake OS_CFLAGS+=-DNEED_NSS_ILOCK" at make time.
1.24 +**
1.25 +** At runtime, to enable recording from nssilock, one or more
1.26 +** environment variables must be set. For each nssILockType to
1.27 +** be recorded, an environment variable of the form NSS_ILOCK_x
1.28 +** must be set to 1. For example:
1.29 +**
1.30 +** set NSS_ILOCK_Cert=1
1.31 +**
1.32 +** nssilock uses PRLOG is used to record to trace data. The
1.33 +** PRLogModule name associated with nssilock data is: "nssilock".
1.34 +** To enable recording of nssilock data you will need to set the
1.35 +** environment variable NSPR_LOG_MODULES to enable
1.36 +** recording for the nssilock log module. Similarly, you will
1.37 +** need to set the environment variable NSPR_LOG_FILE to specify
1.38 +** the filename to receive the recorded data. See prlog.h for usage.
1.39 +** Example:
1.40 +**
1.41 +** export NSPR_LOG_MODULES=nssilock:6
1.42 +** export NSPR_LOG_FILE=xxxLogfile
1.43 +**
1.44 +** Operation:
1.45 +** nssilock wraps calls to NSPR's PZLock and PZMonitor functions
1.46 +** with similarly named functions: PZ_NewLock(), etc. When NSS is
1.47 +** built with lock instrumentation enabled, the PZ* functions are
1.48 +** compiled into NSS; when lock instrumentation is disabled,
1.49 +** calls to PZ* functions are directly mapped to PR* functions
1.50 +** and the instrumentation arguments to the PZ* functions are
1.51 +** compiled away.
1.52 +**
1.53 +**
1.54 +** File Format:
1.55 +** The format of the external file is implementation
1.56 +** dependent. Where NSPR's PR_LOG() function is used, the file
1.57 +** contains data defined for PR_LOG() plus the data written by
1.58 +** the wrapped function. On some platforms and under some
1.59 +** circumstances, platform dependent logging or
1.60 +** instrumentation probes may be used. In any case, the
1.61 +** relevant data provided by the lock instrumentation is:
1.62 +**
1.63 +** lockType, func, address, duration, line, file [heldTime]
1.64 +**
1.65 +** where:
1.66 +**
1.67 +** lockType: a character representation of nssILockType for the
1.68 +** call. e.g. ... "cert"
1.69 +**
1.70 +** func: the function doing the tracing. e.g. "NewLock"
1.71 +**
1.72 +** address: address of the instrumented lock or monitor
1.73 +**
1.74 +** duration: is how long was spent in the instrumented function,
1.75 +** in PRIntervalTime "ticks".
1.76 +**
1.77 +** line: the line number within the calling function
1.78 +**
1.79 +** file: the file from which the call was made
1.80 +**
1.81 +** heldTime: how long the lock/monitor was held. field
1.82 +** present only for PZ_Unlock() and PZ_ExitMonitor().
1.83 +**
1.84 +** Design Notes:
1.85 +** The design for lock instrumentation was influenced by the
1.86 +** need to gather performance data on NSS 3.x. It is intended
1.87 +** that the effort to modify NSS to use lock instrumentation
1.88 +** be minimized. Existing calls to locking functions need only
1.89 +** have their names changed to the instrumentation function
1.90 +** names.
1.91 +**
1.92 +** Private NSS Interface:
1.93 +** nssilock.h defines a private interface for use by NSS.
1.94 +** nssilock.h is experimental in nature and is subject to
1.95 +** change or revocation without notice. ... Don't mess with
1.96 +** it.
1.97 +**
1.98 +*/
1.99 +
1.100 +/*
1.101 + * $Id:
1.102 + */
1.103 +
1.104 +#ifndef _NSSILCKT_H_
1.105 +#define _NSSILCKT_H_
1.106 +
1.107 +#include "utilrename.h"
1.108 +#include "prtypes.h"
1.109 +#include "prmon.h"
1.110 +#include "prlock.h"
1.111 +#include "prcvar.h"
1.112 +
1.113 +typedef enum {
1.114 + nssILockArena = 0,
1.115 + nssILockSession = 1,
1.116 + nssILockObject = 2,
1.117 + nssILockRefLock = 3,
1.118 + nssILockCert = 4,
1.119 + nssILockCertDB = 5,
1.120 + nssILockDBM = 6,
1.121 + nssILockCache = 7,
1.122 + nssILockSSL = 8,
1.123 + nssILockList = 9,
1.124 + nssILockSlot = 10,
1.125 + nssILockFreelist = 11,
1.126 + nssILockOID = 12,
1.127 + nssILockAttribute = 13,
1.128 + nssILockPK11cxt = 14, /* pk11context */
1.129 + nssILockRWLock = 15,
1.130 + nssILockOther = 16,
1.131 + nssILockSelfServ = 17,
1.132 + nssILockKeyDB = 18,
1.133 + nssILockLast /* don't use this one! */
1.134 +} nssILockType;
1.135 +
1.136 +/*
1.137 +** conditionally compile in nssilock features
1.138 +*/
1.139 +#if defined(NEED_NSS_ILOCK)
1.140 +
1.141 +/*
1.142 +** Declare operation type enumerator
1.143 +** enumerations identify the function being performed
1.144 +*/
1.145 +typedef enum {
1.146 + FlushTT = 0,
1.147 + NewLock = 1,
1.148 + Lock = 2,
1.149 + Unlock = 3,
1.150 + DestroyLock = 4,
1.151 + NewCondVar = 5,
1.152 + WaitCondVar = 6,
1.153 + NotifyCondVar = 7,
1.154 + NotifyAllCondVar = 8,
1.155 + DestroyCondVar = 9,
1.156 + NewMonitor = 10,
1.157 + EnterMonitor = 11,
1.158 + ExitMonitor = 12,
1.159 + Notify = 13,
1.160 + NotifyAll = 14,
1.161 + Wait = 15,
1.162 + DestroyMonitor = 16
1.163 +} nssILockOp;
1.164 +
1.165 +/*
1.166 +** Declare the trace record
1.167 +*/
1.168 +struct pzTrace_s {
1.169 + PRUint32 threadID; /* PR_GetThreadID() */
1.170 + nssILockOp op; /* operation being performed */
1.171 + nssILockType ltype; /* lock type identifier */
1.172 + PRIntervalTime callTime; /* time spent in function */
1.173 + PRIntervalTime heldTime; /* lock held time, or -1 */
1.174 + void *lock; /* address of lock structure */
1.175 + PRIntn line; /* line number */
1.176 + char file[24]; /* filename */
1.177 +};
1.178 +
1.179 +/*
1.180 +** declare opaque types. See: nssilock.c
1.181 +*/
1.182 +typedef struct pzlock_s PZLock;
1.183 +typedef struct pzcondvar_s PZCondVar;
1.184 +typedef struct pzmonitor_s PZMonitor;
1.185 +
1.186 +#else /* NEED_NSS_ILOCK */
1.187 +
1.188 +#define PZLock PRLock
1.189 +#define PZCondVar PRCondVar
1.190 +#define PZMonitor PRMonitor
1.191 +
1.192 +#endif /* NEED_NSS_ILOCK */
1.193 +
1.194 +#endif /* _NSSILCKT_H_ */
