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
110typedef 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*/
142typedef 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*/
165struct 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*/
179typedef struct pzlock_s PZLock;
180typedef struct pzcondvar_s PZCondVar;
181typedef 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_ */
192

source code of include/nss/nssilckt.h