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 _NSSILOCK_H_
131#define _NSSILOCK_H_
132
133#include "prtypes.h"
134#include "prmon.h"
135#include "prlock.h"
136#include "prcvar.h"
137
138#include "nssilckt.h"
139
140PR_BEGIN_EXTERN_C
141
142#if defined(NEED_NSS_ILOCK)
143
144#define PZ_NewLock(t) pz_NewLock((t),__FILE__,__LINE__)
145extern PZLock *
146    pz_NewLock(
147        nssILockType ltype,
148        char *file,
149        PRIntn  line
150    );
151
152#define PZ_Lock(k)  pz_Lock((k),__FILE__,__LINE__)
153extern void
154    pz_Lock(
155        PZLock *lock,
156        char *file,
157        PRIntn line
158    );
159
160#define PZ_Unlock(k) pz_Unlock((k),__FILE__,__LINE__)
161extern PRStatus
162    pz_Unlock(
163        PZLock *lock,
164        char *file,
165        PRIntn line
166    );
167
168#define PZ_DestroyLock(k) pz_DestroyLock((k),__FILE__,__LINE__)
169extern void
170    pz_DestroyLock(
171        PZLock *lock,
172        char *file,
173        PRIntn line
174    );
175
176
177#define PZ_NewCondVar(l)        pz_NewCondVar((l),__FILE__,__LINE__)
178extern PZCondVar *
179    pz_NewCondVar(
180        PZLock *lock,
181        char *file,
182        PRIntn line
183    );
184
185#define PZ_DestroyCondVar(v)    pz_DestroyCondVar((v),__FILE__,__LINE__)
186extern void
187    pz_DestroyCondVar(
188        PZCondVar *cvar,
189        char *file,
190        PRIntn line
191    );
192
193#define PZ_WaitCondVar(v,t)       pz_WaitCondVar((v),(t),__FILE__,__LINE__)
194extern PRStatus
195    pz_WaitCondVar(
196        PZCondVar *cvar,
197        PRIntervalTime timeout,
198        char *file,
199        PRIntn line
200    );
201
202#define PZ_NotifyCondVar(v)     pz_NotifyCondVar((v),__FILE__,__LINE__)
203extern PRStatus
204    pz_NotifyCondVar(
205        PZCondVar *cvar,
206        char *file,
207        PRIntn line
208    );
209
210#define PZ_NotifyAllCondVar(v)  pz_NotifyAllCondVar((v),__FILE__,__LINE__)
211extern PRStatus
212    pz_NotifyAllCondVar(
213        PZCondVar *cvar,
214        char *file,
215        PRIntn line
216    );
217
218
219#define PZ_NewMonitor(t) pz_NewMonitor((t),__FILE__,__LINE__)
220extern PZMonitor *
221    pz_NewMonitor(
222        nssILockType ltype,
223        char *file,
224        PRIntn line
225    );
226
227#define PZ_DestroyMonitor(m) pz_DestroyMonitor((m),__FILE__,__LINE__)
228extern void
229    pz_DestroyMonitor(
230        PZMonitor *mon,
231        char *file,
232        PRIntn line
233    );
234
235#define PZ_EnterMonitor(m) pz_EnterMonitor((m),__FILE__,__LINE__)
236extern void
237    pz_EnterMonitor(
238        PZMonitor *mon,
239        char *file,
240        PRIntn line
241    );
242
243
244#define PZ_ExitMonitor(m) pz_ExitMonitor((m),__FILE__,__LINE__)
245extern PRStatus
246    pz_ExitMonitor(
247        PZMonitor *mon,
248        char *file,
249        PRIntn line
250    );
251
252#define PZ_InMonitor(m)  (PZ_GetMonitorEntryCount(m) > 0 )
253#define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m),__FILE__,__LINE__)
254extern PRIntn
255    pz_GetMonitorEntryCount(
256        PZMonitor *mon,
257        char *file,
258        PRIntn line
259    );
260
261#define PZ_Wait(m,i) pz_Wait((m),((i)),__FILE__,__LINE__)
262extern PRStatus
263    pz_Wait(
264        PZMonitor *mon,
265        PRIntervalTime ticks,
266        char *file,
267        PRIntn line
268    );
269
270#define PZ_Notify(m) pz_Notify((m),__FILE__,__LINE__)
271extern PRStatus
272    pz_Notify(
273        PZMonitor *mon,
274        char *file,
275        PRIntn line
276    );
277
278#define PZ_NotifyAll(m) pz_NotifyAll((m),__FILE__,__LINE__)
279extern PRStatus
280    pz_NotifyAll(
281        PZMonitor *mon,
282        char *file,
283        PRIntn line
284    );
285
286#define PZ_TraceFlush() pz_TraceFlush()
287extern void pz_TraceFlush( void );
288
289#else /* NEED_NSS_ILOCK */
290
291#define PZ_NewLock(t)           PR_NewLock()
292#define PZ_DestroyLock(k)       PR_DestroyLock((k))
293#define PZ_Lock(k)              PR_Lock((k))
294#define PZ_Unlock(k)            PR_Unlock((k))
295
296#define PZ_NewCondVar(l)        PR_NewCondVar((l))
297#define PZ_DestroyCondVar(v)    PR_DestroyCondVar((v))
298#define PZ_WaitCondVar(v,t)     PR_WaitCondVar((v),(t))
299#define PZ_NotifyCondVar(v)     PR_NotifyCondVar((v))
300#define PZ_NotifyAllCondVar(v)  PR_NotifyAllCondVar((v))
301
302#define PZ_NewMonitor(t)        PR_NewMonitor()
303#define PZ_DestroyMonitor(m)    PR_DestroyMonitor((m))
304#define PZ_EnterMonitor(m)      PR_EnterMonitor((m))
305#define PZ_ExitMonitor(m)       PR_ExitMonitor((m))
306#define PZ_InMonitor(m)         PR_InMonitor((m))
307#define PZ_Wait(m,t)            PR_Wait(((m)),((t)))
308#define PZ_Notify(m)            PR_Notify((m))
309#define PZ_NotifyAll(m)         PR_Notify((m))
310#define PZ_TraceFlush()         /* nothing */
311
312
313#endif /* NEED_NSS_ILOCK */
314
315PR_END_EXTERN_C
316#endif /* _NSSILOCK_H_ */
317