nssilock.h

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/*
** nssilock.h - Instrumented locking functions for NSS
**
** Description:
**    nssilock provides instrumentation for locks and monitors in
**    the NSS libraries. The instrumentation, when enabled, causes
**    each call to the instrumented function to record data about
**    the call to an external file. The external file
**    subsequently used to extract performance data and other
**    statistical information about the operation of locks used in
**    the nss library.
**
**    To enable compilation with instrumentation, build NSS with
**    the compile time switch NEED_NSS_ILOCK defined.
**
**    say:  "gmake OS_CFLAGS+=-DNEED_NSS_ILOCK" at make time.
**
**    At runtime, to enable recording from nssilock, one or more
**    environment variables must be set. For each nssILockType to
**    be recorded, an environment variable of the form NSS_ILOCK_x
**    must be set to 1. For example:
**
**       set NSS_ILOCK_Cert=1
**
**    nssilock uses PRLOG is used to record to trace data. The
**    PRLogModule name associated with nssilock data is: "nssilock".
**    To enable recording of nssilock data you will need to set the
**    environment variable NSPR_LOG_MODULES to enable
**    recording for the nssilock log module. Similarly, you will
**    need to set the environment variable NSPR_LOG_FILE to specify
**    the filename to receive the recorded data. See prlog.h for usage.
**    Example:
**
**        export NSPR_LOG_MODULES=nssilock:6
**        export NSPR_LOG_FILE=xxxLogfile
**
** Operation:
**    nssilock wraps calls to NSPR's PZLock and PZMonitor functions
**    with similarly named functions: PZ_NewLock(), etc. When NSS is
**    built with lock instrumentation enabled, the PZ* functions are
**    compiled into NSS; when lock instrumentation is disabled,
**    calls to PZ* functions are directly mapped to PR* functions
**    and the instrumentation arguments to the PZ* functions are
**    compiled away.
**
**
** File Format:
**    The format of the external file is implementation
**    dependent. Where NSPR's PR_LOG() function is used, the file
**    contains data defined for PR_LOG() plus the data written by
**    the wrapped function. On some platforms and under some
**    circumstances, platform dependent logging or
**    instrumentation probes may be used. In any case, the
**    relevant data provided by the lock instrumentation is:
**
**      lockType, func, address, duration, line, file [heldTime]
**
**    where:
**
**       lockType: a character representation of nssILockType for the
**       call. e.g. ... "cert"
**
**       func: the function doing the tracing. e.g. "NewLock"
**
**       address: address of the instrumented lock or monitor
**
**       duration: is how long was spent in the instrumented function,
**       in PRIntervalTime "ticks".
**
**       line: the line number within the calling function
**
**       file: the file from which the call was made
**
**       heldTime: how long the lock/monitor was held. field
**       present only for PZ_Unlock() and PZ_ExitMonitor().
**
** Design Notes:
**    The design for lock instrumentation was influenced by the
**    need to gather performance data on NSS 3.x. It is intended
**    that the effort to modify NSS to use lock instrumentation
**    be minimized. Existing calls to locking functions need only
**    have their names changed to the instrumentation function
**    names.
**
** Private NSS Interface:
**    nssilock.h defines a private interface for use by NSS.
**    nssilock.h is experimental in nature and is subject to
**    change or revocation without notice. ... Don't mess with
**    it.
**
*/

/*
 * $Id:
 */

#ifndef _NSSILOCK_H_
#define _NSSILOCK_H_

#include "utilrename.h"
#include "prtypes.h"
#include "prmon.h"
#include "prlock.h"
#include "prcvar.h"

#include "nssilckt.h"

PR_BEGIN_EXTERN_C

#if defined(NEED_NSS_ILOCK)

#define PZ_NewLock(t) pz_NewLock((t), __FILE__, __LINE__)
extern PZLock *
pz_NewLock(
    nssILockType ltype,
    char *file,
    PRIntn line);

#define PZ_Lock(k) pz_Lock((k), __FILE__, __LINE__)
extern void
pz_Lock(
    PZLock *lock,
    char *file,
    PRIntn line);

#define PZ_Unlock(k) pz_Unlock((k), __FILE__, __LINE__)
extern PRStatus
pz_Unlock(
    PZLock *lock,
    char *file,
    PRIntn line);

#define PZ_DestroyLock(k) pz_DestroyLock((k), __FILE__, __LINE__)
extern void
pz_DestroyLock(
    PZLock *lock,
    char *file,
    PRIntn line);

#define PZ_NewCondVar(l) pz_NewCondVar((l), __FILE__, __LINE__)
extern PZCondVar *
pz_NewCondVar(
    PZLock *lock,
    char *file,
    PRIntn line);

#define PZ_DestroyCondVar(v) pz_DestroyCondVar((v), __FILE__, __LINE__)
extern void
pz_DestroyCondVar(
    PZCondVar *cvar,
    char *file,
    PRIntn line);

#define PZ_WaitCondVar(v, t) pz_WaitCondVar((v), (t), __FILE__, __LINE__)
extern PRStatus
pz_WaitCondVar(
    PZCondVar *cvar,
    PRIntervalTime timeout,
    char *file,
    PRIntn line);

#define PZ_NotifyCondVar(v) pz_NotifyCondVar((v), __FILE__, __LINE__)
extern PRStatus
pz_NotifyCondVar(
    PZCondVar *cvar,
    char *file,
    PRIntn line);

#define PZ_NotifyAllCondVar(v) pz_NotifyAllCondVar((v), __FILE__, __LINE__)
extern PRStatus
pz_NotifyAllCondVar(
    PZCondVar *cvar,
    char *file,
    PRIntn line);

#define PZ_NewMonitor(t) pz_NewMonitor((t), __FILE__, __LINE__)
extern PZMonitor *
pz_NewMonitor(
    nssILockType ltype,
    char *file,
    PRIntn line);

#define PZ_DestroyMonitor(m) pz_DestroyMonitor((m), __FILE__, __LINE__)
extern void
pz_DestroyMonitor(
    PZMonitor *mon,
    char *file,
    PRIntn line);

#define PZ_EnterMonitor(m) pz_EnterMonitor((m), __FILE__, __LINE__)
extern void
pz_EnterMonitor(
    PZMonitor *mon,
    char *file,
    PRIntn line);

#define PZ_ExitMonitor(m) pz_ExitMonitor((m), __FILE__, __LINE__)
extern PRStatus
pz_ExitMonitor(
    PZMonitor *mon,
    char *file,
    PRIntn line);

#define PZ_InMonitor(m) (PZ_GetMonitorEntryCount(m) > 0)
#define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m), __FILE__, __LINE__)
extern PRIntn
pz_GetMonitorEntryCount(
    PZMonitor *mon,
    char *file,
    PRIntn line);

#define PZ_Wait(m, i) pz_Wait((m), ((i)), __FILE__, __LINE__)
extern PRStatus
pz_Wait(
    PZMonitor *mon,
    PRIntervalTime ticks,
    char *file,
    PRIntn line);

#define PZ_Notify(m) pz_Notify((m), __FILE__, __LINE__)
extern PRStatus
pz_Notify(
    PZMonitor *mon,
    char *file,
    PRIntn line);

#define PZ_NotifyAll(m) pz_NotifyAll((m), __FILE__, __LINE__)
extern PRStatus
pz_NotifyAll(
    PZMonitor *mon,
    char *file,
    PRIntn line);

#define PZ_TraceFlush() pz_TraceFlush()
extern void pz_TraceFlush(void);

#else /* NEED_NSS_ILOCK */

#define PZ_NewLock(t) PR_NewLock()
#define PZ_DestroyLock(k) PR_DestroyLock((k))
#define PZ_Lock(k) PR_Lock((k))
#define PZ_Unlock(k) PR_Unlock((k))

#define PZ_NewCondVar(l) PR_NewCondVar((l))
#define PZ_DestroyCondVar(v) PR_DestroyCondVar((v))
#define PZ_WaitCondVar(v, t) PR_WaitCondVar((v), (t))
#define PZ_NotifyCondVar(v) PR_NotifyCondVar((v))
#define PZ_NotifyAllCondVar(v) PR_NotifyAllCondVar((v))

#define PZ_NewMonitor(t) PR_NewMonitor()
#define PZ_DestroyMonitor(m) PR_DestroyMonitor((m))
#define PZ_EnterMonitor(m) PR_EnterMonitor((m))
#define PZ_ExitMonitor(m) PR_ExitMonitor((m))
#define PZ_InMonitor(m) PR_InMonitor((m))
#define PZ_Wait(m, t) PR_Wait(((m)), ((t)))
#define PZ_Notify(m) PR_Notify((m))
#define PZ_NotifyAll(m) PR_Notify((m))
#define PZ_TraceFlush() /* nothing */

#endif /* NEED_NSS_ILOCK */

PR_END_EXTERN_C
#endif /* _NSSILOCK_H_ */

docroot: /var/www/469ed2f6-4d4b-4a8a-9f5e-ee4ef04d3bc8/public_html

curdir: /usr/include/nss

	.	4096
	..	16384
X	base64.h	1154
X	blapit.h	14939
X	cert.h	61401
X	certdb.h	3202
X	certt.h	48444
X	ciferfam.h	2467
X	cmmf.h	43207
X	cmmft.h	2303
X	cms.h	39764
X	cmsreclist.h	908
X	cmst.h	17273
X	crmf.h	64432
X	crmft.h	5457
X	cryptohi.h	18297
X	cryptoht.h	426
X	eccutil.h	425
X	ecl-exp.h	6923
X	hasht.h	1907
X	jar-ds.h	1964
X	jar.h	10128
X	jarfile.h	1704
X	key.h	425
X	keyhi.h	8602
X	keyt.h	431
X	keythi.h	7284
X	kyber.h	965
X	lowkeyi.h	2308
X	lowkeyti.h	2895
X	nss.h	15411
X	nssb64.h	3248
X	nssb64t.h	466
X	nssbase.h	6672
X	nssbaset.h	2670
X	nssck.api	42205
X	nssckbi.h	2504
X	nssckepv.h	320
X	nssckft.h	327
X	nssckfw.h	7235
X	nssckfwc.h	17113
X	nssckfwt.h	2034
X	nssckg.h	314
X	nssckmdt.h	64748
X	nssckt.h	366
X	nssilckt.h	5923
X	nssilock.h	7743
X	nsslocks.h	380
X	nsslowhash.h	1297
X	nssrwlk.h	5047
X	nssrwlkt.h	535
X	nssutil.h	966
X	ocsp.h	28871
X	ocspt.h	12511
X	p12.h	9464
X	p12plcy.h	755
X	p12t.h	4570
X	pk11func.h	494
X	pk11hpke.h	1862
X	pk11pqg.h	6584
X	pk11priv.h	10386
X	pk11pub.h	60589
X	pk11sdr.h	731
X	pkcs11.h	8022
X	pkcs11f.h	31818
X	pkcs11n.h	28367
X	pkcs11p.h	869
X	pkcs11t.h	88681
X	pkcs11u.h	709
X	pkcs11uri.h	3065
X	pkcs12.h	1408
X	pkcs12t.h	11213
X	pkcs1sig.h	1202
X	pkcs7t.h	9209
X	portreg.h	3083
X	preenc.h	3839
X	secasn1.h	13214
X	secasn1t.h	10916
X	seccomon.h	2163
X	secder.h	6057
X	secdert.h	3969
X	secdig.h	3369
X	secdigt.h	622
X	secerr.h	11680
X	sechash.h	1787
X	secitem.h	4772
X	secmime.h	7163
X	secmod.h	8191
X	secmodt.h	16563
X	secoid.h	5043
X	secoidt.h	19825
X	secpkcs5.h	2099
X	secpkcs7.h	25439
X	secport.h	15027
X	shsign.h	816
X	smime.h	5695
X	ssl.h	75458
X	sslerr.h	16411
X	sslexp.h	56188
X	sslproto.h	14472
X	sslt.h	21078
X	utilmodt.h	1618
X	utilpars.h	3527
X	utilparst.h	3424
X	utilrename.h	8776