security/nss/lib/util/nssilock.h@6474c204b198
security/nss/lib/util/nssilock.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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/. */
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 */
97 /*
98 * $Id:
99 */
101 #ifndef _NSSILOCK_H_
102 #define _NSSILOCK_H_
104 #include "utilrename.h"
105 #include "prtypes.h"
106 #include "prmon.h"
107 #include "prlock.h"
108 #include "prcvar.h"
110 #include "nssilckt.h"
112 PR_BEGIN_EXTERN_C
114 #if defined(NEED_NSS_ILOCK)
116 #define PZ_NewLock(t) pz_NewLock((t),__FILE__,__LINE__)
117 extern PZLock *
118 pz_NewLock(
119 nssILockType ltype,
120 char *file,
121 PRIntn line
122 );
124 #define PZ_Lock(k) pz_Lock((k),__FILE__,__LINE__)
125 extern void
126 pz_Lock(
127 PZLock *lock,
128 char *file,
129 PRIntn line
130 );
132 #define PZ_Unlock(k) pz_Unlock((k),__FILE__,__LINE__)
133 extern PRStatus
134 pz_Unlock(
135 PZLock *lock,
136 char *file,
137 PRIntn line
138 );
140 #define PZ_DestroyLock(k) pz_DestroyLock((k),__FILE__,__LINE__)
141 extern void
142 pz_DestroyLock(
143 PZLock *lock,
144 char *file,
145 PRIntn line
146 );
149 #define PZ_NewCondVar(l) pz_NewCondVar((l),__FILE__,__LINE__)
150 extern PZCondVar *
151 pz_NewCondVar(
152 PZLock *lock,
153 char *file,
154 PRIntn line
155 );
157 #define PZ_DestroyCondVar(v) pz_DestroyCondVar((v),__FILE__,__LINE__)
158 extern void
159 pz_DestroyCondVar(
160 PZCondVar *cvar,
161 char *file,
162 PRIntn line
163 );
165 #define PZ_WaitCondVar(v,t) pz_WaitCondVar((v),(t),__FILE__,__LINE__)
166 extern PRStatus
167 pz_WaitCondVar(
168 PZCondVar *cvar,
169 PRIntervalTime timeout,
170 char *file,
171 PRIntn line
172 );
174 #define PZ_NotifyCondVar(v) pz_NotifyCondVar((v),__FILE__,__LINE__)
175 extern PRStatus
176 pz_NotifyCondVar(
177 PZCondVar *cvar,
178 char *file,
179 PRIntn line
180 );
182 #define PZ_NotifyAllCondVar(v) pz_NotifyAllCondVar((v),__FILE__,__LINE__)
183 extern PRStatus
184 pz_NotifyAllCondVar(
185 PZCondVar *cvar,
186 char *file,
187 PRIntn line
188 );
191 #define PZ_NewMonitor(t) pz_NewMonitor((t),__FILE__,__LINE__)
192 extern PZMonitor *
193 pz_NewMonitor(
194 nssILockType ltype,
195 char *file,
196 PRIntn line
197 );
199 #define PZ_DestroyMonitor(m) pz_DestroyMonitor((m),__FILE__,__LINE__)
200 extern void
201 pz_DestroyMonitor(
202 PZMonitor *mon,
203 char *file,
204 PRIntn line
205 );
207 #define PZ_EnterMonitor(m) pz_EnterMonitor((m),__FILE__,__LINE__)
208 extern void
209 pz_EnterMonitor(
210 PZMonitor *mon,
211 char *file,
212 PRIntn line
213 );
216 #define PZ_ExitMonitor(m) pz_ExitMonitor((m),__FILE__,__LINE__)
217 extern PRStatus
218 pz_ExitMonitor(
219 PZMonitor *mon,
220 char *file,
221 PRIntn line
222 );
224 #define PZ_InMonitor(m) (PZ_GetMonitorEntryCount(m) > 0 )
225 #define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m),__FILE__,__LINE__)
226 extern PRIntn
227 pz_GetMonitorEntryCount(
228 PZMonitor *mon,
229 char *file,
230 PRIntn line
231 );
233 #define PZ_Wait(m,i) pz_Wait((m),((i)),__FILE__,__LINE__)
234 extern PRStatus
235 pz_Wait(
236 PZMonitor *mon,
237 PRIntervalTime ticks,
238 char *file,
239 PRIntn line
240 );
242 #define PZ_Notify(m) pz_Notify((m),__FILE__,__LINE__)
243 extern PRStatus
244 pz_Notify(
245 PZMonitor *mon,
246 char *file,
247 PRIntn line
248 );
250 #define PZ_NotifyAll(m) pz_NotifyAll((m),__FILE__,__LINE__)
251 extern PRStatus
252 pz_NotifyAll(
253 PZMonitor *mon,
254 char *file,
255 PRIntn line
256 );
258 #define PZ_TraceFlush() pz_TraceFlush()
259 extern void pz_TraceFlush( void );
261 #else /* NEED_NSS_ILOCK */
263 #define PZ_NewLock(t) PR_NewLock()
264 #define PZ_DestroyLock(k) PR_DestroyLock((k))
265 #define PZ_Lock(k) PR_Lock((k))
266 #define PZ_Unlock(k) PR_Unlock((k))
268 #define PZ_NewCondVar(l) PR_NewCondVar((l))
269 #define PZ_DestroyCondVar(v) PR_DestroyCondVar((v))
270 #define PZ_WaitCondVar(v,t) PR_WaitCondVar((v),(t))
271 #define PZ_NotifyCondVar(v) PR_NotifyCondVar((v))
272 #define PZ_NotifyAllCondVar(v) PR_NotifyAllCondVar((v))
274 #define PZ_NewMonitor(t) PR_NewMonitor()
275 #define PZ_DestroyMonitor(m) PR_DestroyMonitor((m))
276 #define PZ_EnterMonitor(m) PR_EnterMonitor((m))
277 #define PZ_ExitMonitor(m) PR_ExitMonitor((m))
278 #define PZ_InMonitor(m) PR_InMonitor((m))
279 #define PZ_Wait(m,t) PR_Wait(((m)),((t)))
280 #define PZ_Notify(m) PR_Notify((m))
281 #define PZ_NotifyAll(m) PR_Notify((m))
282 #define PZ_TraceFlush() /* nothing */
285 #endif /* NEED_NSS_ILOCK */
287 PR_END_EXTERN_C
288 #endif /* _NSSILOCK_H_ */
