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 _NSSILOCK_H_
102#define _NSSILOCK_H_
103
104#include "utilrename.h"
105#include "prtypes.h"
106#include "prmon.h"
107#include "prlock.h"
108#include "prcvar.h"
109
110#include "nssilckt.h"
111
112PR_BEGIN_EXTERN_C
113
114#if defined(NEED_NSS_ILOCK)
115
116#define PZ_NewLock(t) pz_NewLock((t), __FILE__, __LINE__)
117extern PZLock *
118pz_NewLock(
119 nssILockType ltype,
120 char *file,
121 PRIntn line);
122
123#define PZ_Lock(k) pz_Lock((k), __FILE__, __LINE__)
124extern void
125pz_Lock(
126 PZLock *lock,
127 char *file,
128 PRIntn line);
129
130#define PZ_Unlock(k) pz_Unlock((k), __FILE__, __LINE__)
131extern PRStatus
132pz_Unlock(
133 PZLock *lock,
134 char *file,
135 PRIntn line);
136
137#define PZ_DestroyLock(k) pz_DestroyLock((k), __FILE__, __LINE__)
138extern void
139pz_DestroyLock(
140 PZLock *lock,
141 char *file,
142 PRIntn line);
143
144#define PZ_NewCondVar(l) pz_NewCondVar((l), __FILE__, __LINE__)
145extern PZCondVar *
146pz_NewCondVar(
147 PZLock *lock,
148 char *file,
149 PRIntn line);
150
151#define PZ_DestroyCondVar(v) pz_DestroyCondVar((v), __FILE__, __LINE__)
152extern void
153pz_DestroyCondVar(
154 PZCondVar *cvar,
155 char *file,
156 PRIntn line);
157
158#define PZ_WaitCondVar(v, t) pz_WaitCondVar((v), (t), __FILE__, __LINE__)
159extern PRStatus
160pz_WaitCondVar(
161 PZCondVar *cvar,
162 PRIntervalTime timeout,
163 char *file,
164 PRIntn line);
165
166#define PZ_NotifyCondVar(v) pz_NotifyCondVar((v), __FILE__, __LINE__)
167extern PRStatus
168pz_NotifyCondVar(
169 PZCondVar *cvar,
170 char *file,
171 PRIntn line);
172
173#define PZ_NotifyAllCondVar(v) pz_NotifyAllCondVar((v), __FILE__, __LINE__)
174extern PRStatus
175pz_NotifyAllCondVar(
176 PZCondVar *cvar,
177 char *file,
178 PRIntn line);
179
180#define PZ_NewMonitor(t) pz_NewMonitor((t), __FILE__, __LINE__)
181extern PZMonitor *
182pz_NewMonitor(
183 nssILockType ltype,
184 char *file,
185 PRIntn line);
186
187#define PZ_DestroyMonitor(m) pz_DestroyMonitor((m), __FILE__, __LINE__)
188extern void
189pz_DestroyMonitor(
190 PZMonitor *mon,
191 char *file,
192 PRIntn line);
193
194#define PZ_EnterMonitor(m) pz_EnterMonitor((m), __FILE__, __LINE__)
195extern void
196pz_EnterMonitor(
197 PZMonitor *mon,
198 char *file,
199 PRIntn line);
200
201#define PZ_ExitMonitor(m) pz_ExitMonitor((m), __FILE__, __LINE__)
202extern PRStatus
203pz_ExitMonitor(
204 PZMonitor *mon,
205 char *file,
206 PRIntn line);
207
208#define PZ_InMonitor(m) (PZ_GetMonitorEntryCount(m) > 0)
209#define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m), __FILE__, __LINE__)
210extern PRIntn
211pz_GetMonitorEntryCount(
212 PZMonitor *mon,
213 char *file,
214 PRIntn line);
215
216#define PZ_Wait(m, i) pz_Wait((m), ((i)), __FILE__, __LINE__)
217extern PRStatus
218pz_Wait(
219 PZMonitor *mon,
220 PRIntervalTime ticks,
221 char *file,
222 PRIntn line);
223
224#define PZ_Notify(m) pz_Notify((m), __FILE__, __LINE__)
225extern PRStatus
226pz_Notify(
227 PZMonitor *mon,
228 char *file,
229 PRIntn line);
230
231#define PZ_NotifyAll(m) pz_NotifyAll((m), __FILE__, __LINE__)
232extern PRStatus
233pz_NotifyAll(
234 PZMonitor *mon,
235 char *file,
236 PRIntn line);
237
238#define PZ_TraceFlush() pz_TraceFlush()
239extern void pz_TraceFlush(void);
240
241#else /* NEED_NSS_ILOCK */
242
243#define PZ_NewLock(t) PR_NewLock()
244#define PZ_DestroyLock(k) PR_DestroyLock((k))
245#define PZ_Lock(k) PR_Lock((k))
246#define PZ_Unlock(k) PR_Unlock((k))
247
248#define PZ_NewCondVar(l) PR_NewCondVar((l))
249#define PZ_DestroyCondVar(v) PR_DestroyCondVar((v))
250#define PZ_WaitCondVar(v, t) PR_WaitCondVar((v), (t))
251#define PZ_NotifyCondVar(v) PR_NotifyCondVar((v))
252#define PZ_NotifyAllCondVar(v) PR_NotifyAllCondVar((v))
253
254#define PZ_NewMonitor(t) PR_NewMonitor()
255#define PZ_DestroyMonitor(m) PR_DestroyMonitor((m))
256#define PZ_EnterMonitor(m) PR_EnterMonitor((m))
257#define PZ_ExitMonitor(m) PR_ExitMonitor((m))
258#define PZ_InMonitor(m) PR_InMonitor((m))
259#define PZ_Wait(m, t) PR_Wait(((m)), ((t)))
260#define PZ_Notify(m) PR_Notify((m))
261#define PZ_NotifyAll(m) PR_Notify((m))
262#define PZ_TraceFlush() /* nothing */
263
264#endif /* NEED_NSS_ILOCK */
265
266PR_END_EXTERN_C
267#endif /* _NSSILOCK_H_ */
268

source code of include/nss/nssilock.h