summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/util/nssilock.h
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/lib/util/nssilock.h')
-rw-r--r--security/nss/lib/util/nssilock.h267
1 files changed, 267 insertions, 0 deletions
diff --git a/security/nss/lib/util/nssilock.h b/security/nss/lib/util/nssilock.h
new file mode 100644
index 000000000..01f666a79
--- /dev/null
+++ b/security/nss/lib/util/nssilock.h
@@ -0,0 +1,267 @@
+/* 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_ */