PageRenderTime 124ms CodeModel.GetById 71ms app.highlight 9ms RepoModel.GetById 41ms app.codeStats 0ms

/gecko_api/include/nssilock.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 320 lines | 156 code | 35 blank | 129 comment | 0 complexity | 1ab891868aeb69c030b7d7f3c9df571c MD5 | raw file
  1/* ***** BEGIN LICENSE BLOCK *****
  2 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3 *
  4 * The contents of this file are subject to the Mozilla Public License Version
  5 * 1.1 (the "License"); you may not use this file except in compliance with
  6 * the License. You may obtain a copy of the License at
  7 * http://www.mozilla.org/MPL/
  8 *
  9 * Software distributed under the License is distributed on an "AS IS" basis,
 10 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 11 * for the specific language governing rights and limitations under the
 12 * License.
 13 *
 14 * The Original Code is the Netscape security libraries.
 15 *
 16 * The Initial Developer of the Original Code is
 17 * Netscape Communications Corporation.
 18 * Portions created by the Initial Developer are Copyright (C) 1994-2000
 19 * the Initial Developer. All Rights Reserved.
 20 *
 21 * Contributor(s):
 22 *
 23 * Alternatively, the contents of this file may be used under the terms of
 24 * either the GNU General Public License Version 2 or later (the "GPL"), or
 25 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 26 * in which case the provisions of the GPL or the LGPL are applicable instead
 27 * of those above. If you wish to allow use of your version of this file only
 28 * under the terms of either the GPL or the LGPL, and not to allow others to
 29 * use your version of this file under the terms of the MPL, indicate your
 30 * decision by deleting the provisions above and replace them with the notice
 31 * and other provisions required by the GPL or the LGPL. If you do not delete
 32 * the provisions above, a recipient may use your version of this file under
 33 * the terms of any one of the MPL, the GPL or the LGPL.
 34 *
 35 * ***** END LICENSE BLOCK ***** */
 36
 37/*
 38** nssilock.h - Instrumented locking functions for NSS
 39**
 40** Description:
 41**    nssilock provides instrumentation for locks and monitors in
 42**    the NSS libraries. The instrumentation, when enabled, causes
 43**    each call to the instrumented function to record data about
 44**    the call to an external file. The external file
 45**    subsequently used to extract performance data and other
 46**    statistical information about the operation of locks used in
 47**    the nss library.
 48**     
 49**    To enable compilation with instrumentation, build NSS with 
 50**    the compile time switch NEED_NSS_ILOCK defined.
 51**
 52**    say:  "gmake OS_CFLAGS+=-DNEED_NSS_ILOCK" at make time.
 53**
 54**    At runtime, to enable recording from nssilock, one or more
 55**    environment variables must be set. For each nssILockType to
 56**    be recorded, an environment variable of the form NSS_ILOCK_x
 57**    must be set to 1. For example:
 58**
 59**       set NSS_ILOCK_Cert=1
 60**
 61**    nssilock uses PRLOG is used to record to trace data. The
 62**    PRLogModule name associated with nssilock data is: "nssilock".
 63**    To enable recording of nssilock data you will need to set the
 64**    environment variable NSPR_LOG_MODULES to enable
 65**    recording for the nssilock log module. Similarly, you will
 66**    need to set the environment variable NSPR_LOG_FILE to specify
 67**    the filename to receive the recorded data. See prlog.h for usage.
 68**    Example:
 69**
 70**        export NSPR_LOG_MODULES=nssilock:6
 71**        export NSPR_LOG_FILE=xxxLogfile
 72**
 73** Operation:
 74**    nssilock wraps calls to NSPR's PZLock and PZMonitor functions
 75**    with similarly named functions: PZ_NewLock(), etc. When NSS is
 76**    built with lock instrumentation enabled, the PZ* functions are
 77**    compiled into NSS; when lock instrumentation is disabled,
 78**    calls to PZ* functions are directly mapped to PR* functions
 79**    and the instrumentation arguments to the PZ* functions are
 80**    compiled away.
 81**
 82**
 83** File Format:
 84**    The format of the external file is implementation
 85**    dependent. Where NSPR's PR_LOG() function is used, the file
 86**    contains data defined for PR_LOG() plus the data written by
 87**    the wrapped function. On some platforms and under some
 88**    circumstances, platform dependent logging or
 89**    instrumentation probes may be used. In any case, the
 90**    relevant data provided by the lock instrumentation is:
 91**    
 92**      lockType, func, address, duration, line, file [heldTime]
 93** 
 94**    where:
 95**    
 96**       lockType: a character representation of nssILockType for the
 97**       call. e.g. ... "cert"
 98**    
 99**       func: the function doing the tracing. e.g. "NewLock"
100**    
101**       address: address of the instrumented lock or monitor
102**    
103**       duration: is how long was spent in the instrumented function,
104**       in PRIntervalTime "ticks".
105**    
106**       line: the line number within the calling function
107**    
108**       file: the file from which the call was made
109**    
110**       heldTime: how long the lock/monitor was held. field
111**       present only for PZ_Unlock() and PZ_ExitMonitor().
112**    
113** Design Notes:
114**    The design for lock instrumentation was influenced by the
115**    need to gather performance data on NSS 3.x. It is intended
116**    that the effort to modify NSS to use lock instrumentation
117**    be minimized. Existing calls to locking functions need only
118**    have their names changed to the instrumentation function
119**    names.
120**    
121** Private NSS Interface:
122**    nssilock.h defines a private interface for use by NSS.
123**    nssilock.h is experimental in nature and is subject to
124**    change or revocation without notice. ... Don't mess with
125**    it.
126**    
127*/
128
129/*
130 * $Id:
131 */
132
133#ifndef _NSSILOCK_H_
134#define _NSSILOCK_H_
135
136#include "utilrename.h"
137#include "prtypes.h"
138#include "prmon.h"
139#include "prlock.h"
140#include "prcvar.h"
141
142#include "nssilckt.h"
143
144PR_BEGIN_EXTERN_C
145
146#if defined(NEED_NSS_ILOCK)
147
148#define PZ_NewLock(t) pz_NewLock((t),__FILE__,__LINE__)
149extern PZLock * 
150    pz_NewLock(
151        nssILockType ltype,
152        char *file,
153        PRIntn  line
154    );
155
156#define PZ_Lock(k)  pz_Lock((k),__FILE__,__LINE__)
157extern void
158    pz_Lock(
159        PZLock *lock,
160        char *file,
161        PRIntn line
162    );
163
164#define PZ_Unlock(k) pz_Unlock((k),__FILE__,__LINE__)
165extern PRStatus
166    pz_Unlock(
167        PZLock *lock,
168        char *file,
169        PRIntn line
170    );
171
172#define PZ_DestroyLock(k) pz_DestroyLock((k),__FILE__,__LINE__)
173extern void
174    pz_DestroyLock(
175        PZLock *lock,
176        char *file,
177        PRIntn line
178    );
179
180
181#define PZ_NewCondVar(l)        pz_NewCondVar((l),__FILE__,__LINE__)
182extern PZCondVar *
183    pz_NewCondVar(
184        PZLock *lock,
185        char *file,
186        PRIntn line
187    );
188
189#define PZ_DestroyCondVar(v)    pz_DestroyCondVar((v),__FILE__,__LINE__)
190extern void
191    pz_DestroyCondVar(
192        PZCondVar *cvar,
193        char *file,
194        PRIntn line
195    );
196
197#define PZ_WaitCondVar(v,t)       pz_WaitCondVar((v),(t),__FILE__,__LINE__)
198extern PRStatus
199    pz_WaitCondVar(
200        PZCondVar *cvar,
201        PRIntervalTime timeout,
202        char *file,
203        PRIntn line
204    );
205
206#define PZ_NotifyCondVar(v)     pz_NotifyCondVar((v),__FILE__,__LINE__)
207extern PRStatus
208    pz_NotifyCondVar(
209        PZCondVar *cvar,
210        char *file,
211        PRIntn line
212    );
213
214#define PZ_NotifyAllCondVar(v)  pz_NotifyAllCondVar((v),__FILE__,__LINE__)
215extern PRStatus
216    pz_NotifyAllCondVar(
217        PZCondVar *cvar,
218        char *file,
219        PRIntn line
220    );
221
222
223#define PZ_NewMonitor(t) pz_NewMonitor((t),__FILE__,__LINE__)
224extern PZMonitor *
225    pz_NewMonitor( 
226        nssILockType ltype,
227        char *file,
228        PRIntn line
229    );
230
231#define PZ_DestroyMonitor(m) pz_DestroyMonitor((m),__FILE__,__LINE__)
232extern void
233    pz_DestroyMonitor(
234        PZMonitor *mon,
235        char *file,
236        PRIntn line
237    );
238
239#define PZ_EnterMonitor(m) pz_EnterMonitor((m),__FILE__,__LINE__)
240extern void
241    pz_EnterMonitor(
242        PZMonitor *mon,
243        char *file,
244        PRIntn line
245    );
246
247
248#define PZ_ExitMonitor(m) pz_ExitMonitor((m),__FILE__,__LINE__)
249extern PRStatus
250    pz_ExitMonitor(
251        PZMonitor *mon,
252        char *file,
253        PRIntn line
254    );
255
256#define PZ_InMonitor(m)  (PZ_GetMonitorEntryCount(m) > 0 )
257#define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m),__FILE__,__LINE__)
258extern PRIntn
259    pz_GetMonitorEntryCount(
260        PZMonitor *mon,
261        char *file,
262        PRIntn line
263    );
264
265#define PZ_Wait(m,i) pz_Wait((m),((i)),__FILE__,__LINE__)
266extern PRStatus
267    pz_Wait(
268        PZMonitor *mon,
269        PRIntervalTime ticks,
270        char *file,
271        PRIntn line
272    );
273
274#define PZ_Notify(m) pz_Notify((m),__FILE__,__LINE__)
275extern PRStatus
276    pz_Notify(
277        PZMonitor *mon,
278        char *file,
279        PRIntn line
280    );
281
282#define PZ_NotifyAll(m) pz_NotifyAll((m),__FILE__,__LINE__)
283extern PRStatus
284    pz_NotifyAll(
285        PZMonitor *mon,
286        char *file,
287        PRIntn line
288    );
289
290#define PZ_TraceFlush() pz_TraceFlush()
291extern void pz_TraceFlush( void );
292
293#else /* NEED_NSS_ILOCK */
294
295#define PZ_NewLock(t)           PR_NewLock()
296#define PZ_DestroyLock(k)       PR_DestroyLock((k))
297#define PZ_Lock(k)              PR_Lock((k))
298#define PZ_Unlock(k)            PR_Unlock((k))
299
300#define PZ_NewCondVar(l)        PR_NewCondVar((l))
301#define PZ_DestroyCondVar(v)    PR_DestroyCondVar((v))
302#define PZ_WaitCondVar(v,t)     PR_WaitCondVar((v),(t))
303#define PZ_NotifyCondVar(v)     PR_NotifyCondVar((v))
304#define PZ_NotifyAllCondVar(v)  PR_NotifyAllCondVar((v))
305
306#define PZ_NewMonitor(t)        PR_NewMonitor()
307#define PZ_DestroyMonitor(m)    PR_DestroyMonitor((m))
308#define PZ_EnterMonitor(m)      PR_EnterMonitor((m))
309#define PZ_ExitMonitor(m)       PR_ExitMonitor((m))
310#define PZ_InMonitor(m)         PR_InMonitor((m))
311#define PZ_Wait(m,t)            PR_Wait(((m)),((t)))
312#define PZ_Notify(m)            PR_Notify((m))
313#define PZ_NotifyAll(m)         PR_Notify((m))
314#define PZ_TraceFlush()         /* nothing */
315
316    
317#endif /* NEED_NSS_ILOCK */
318
319PR_END_EXTERN_C
320#endif /* _NSSILOCK_H_ */