1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/util/nssilock.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,288 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +/*
1.9 +** nssilock.h - Instrumented locking functions for NSS
1.10 +**
1.11 +** Description:
1.12 +** nssilock provides instrumentation for locks and monitors in
1.13 +** the NSS libraries. The instrumentation, when enabled, causes
1.14 +** each call to the instrumented function to record data about
1.15 +** the call to an external file. The external file
1.16 +** subsequently used to extract performance data and other
1.17 +** statistical information about the operation of locks used in
1.18 +** the nss library.
1.19 +**
1.20 +** To enable compilation with instrumentation, build NSS with
1.21 +** the compile time switch NEED_NSS_ILOCK defined.
1.22 +**
1.23 +** say: "gmake OS_CFLAGS+=-DNEED_NSS_ILOCK" at make time.
1.24 +**
1.25 +** At runtime, to enable recording from nssilock, one or more
1.26 +** environment variables must be set. For each nssILockType to
1.27 +** be recorded, an environment variable of the form NSS_ILOCK_x
1.28 +** must be set to 1. For example:
1.29 +**
1.30 +** set NSS_ILOCK_Cert=1
1.31 +**
1.32 +** nssilock uses PRLOG is used to record to trace data. The
1.33 +** PRLogModule name associated with nssilock data is: "nssilock".
1.34 +** To enable recording of nssilock data you will need to set the
1.35 +** environment variable NSPR_LOG_MODULES to enable
1.36 +** recording for the nssilock log module. Similarly, you will
1.37 +** need to set the environment variable NSPR_LOG_FILE to specify
1.38 +** the filename to receive the recorded data. See prlog.h for usage.
1.39 +** Example:
1.40 +**
1.41 +** export NSPR_LOG_MODULES=nssilock:6
1.42 +** export NSPR_LOG_FILE=xxxLogfile
1.43 +**
1.44 +** Operation:
1.45 +** nssilock wraps calls to NSPR's PZLock and PZMonitor functions
1.46 +** with similarly named functions: PZ_NewLock(), etc. When NSS is
1.47 +** built with lock instrumentation enabled, the PZ* functions are
1.48 +** compiled into NSS; when lock instrumentation is disabled,
1.49 +** calls to PZ* functions are directly mapped to PR* functions
1.50 +** and the instrumentation arguments to the PZ* functions are
1.51 +** compiled away.
1.52 +**
1.53 +**
1.54 +** File Format:
1.55 +** The format of the external file is implementation
1.56 +** dependent. Where NSPR's PR_LOG() function is used, the file
1.57 +** contains data defined for PR_LOG() plus the data written by
1.58 +** the wrapped function. On some platforms and under some
1.59 +** circumstances, platform dependent logging or
1.60 +** instrumentation probes may be used. In any case, the
1.61 +** relevant data provided by the lock instrumentation is:
1.62 +**
1.63 +** lockType, func, address, duration, line, file [heldTime]
1.64 +**
1.65 +** where:
1.66 +**
1.67 +** lockType: a character representation of nssILockType for the
1.68 +** call. e.g. ... "cert"
1.69 +**
1.70 +** func: the function doing the tracing. e.g. "NewLock"
1.71 +**
1.72 +** address: address of the instrumented lock or monitor
1.73 +**
1.74 +** duration: is how long was spent in the instrumented function,
1.75 +** in PRIntervalTime "ticks".
1.76 +**
1.77 +** line: the line number within the calling function
1.78 +**
1.79 +** file: the file from which the call was made
1.80 +**
1.81 +** heldTime: how long the lock/monitor was held. field
1.82 +** present only for PZ_Unlock() and PZ_ExitMonitor().
1.83 +**
1.84 +** Design Notes:
1.85 +** The design for lock instrumentation was influenced by the
1.86 +** need to gather performance data on NSS 3.x. It is intended
1.87 +** that the effort to modify NSS to use lock instrumentation
1.88 +** be minimized. Existing calls to locking functions need only
1.89 +** have their names changed to the instrumentation function
1.90 +** names.
1.91 +**
1.92 +** Private NSS Interface:
1.93 +** nssilock.h defines a private interface for use by NSS.
1.94 +** nssilock.h is experimental in nature and is subject to
1.95 +** change or revocation without notice. ... Don't mess with
1.96 +** it.
1.97 +**
1.98 +*/
1.99 +
1.100 +/*
1.101 + * $Id:
1.102 + */
1.103 +
1.104 +#ifndef _NSSILOCK_H_
1.105 +#define _NSSILOCK_H_
1.106 +
1.107 +#include "utilrename.h"
1.108 +#include "prtypes.h"
1.109 +#include "prmon.h"
1.110 +#include "prlock.h"
1.111 +#include "prcvar.h"
1.112 +
1.113 +#include "nssilckt.h"
1.114 +
1.115 +PR_BEGIN_EXTERN_C
1.116 +
1.117 +#if defined(NEED_NSS_ILOCK)
1.118 +
1.119 +#define PZ_NewLock(t) pz_NewLock((t),__FILE__,__LINE__)
1.120 +extern PZLock *
1.121 + pz_NewLock(
1.122 + nssILockType ltype,
1.123 + char *file,
1.124 + PRIntn line
1.125 + );
1.126 +
1.127 +#define PZ_Lock(k) pz_Lock((k),__FILE__,__LINE__)
1.128 +extern void
1.129 + pz_Lock(
1.130 + PZLock *lock,
1.131 + char *file,
1.132 + PRIntn line
1.133 + );
1.134 +
1.135 +#define PZ_Unlock(k) pz_Unlock((k),__FILE__,__LINE__)
1.136 +extern PRStatus
1.137 + pz_Unlock(
1.138 + PZLock *lock,
1.139 + char *file,
1.140 + PRIntn line
1.141 + );
1.142 +
1.143 +#define PZ_DestroyLock(k) pz_DestroyLock((k),__FILE__,__LINE__)
1.144 +extern void
1.145 + pz_DestroyLock(
1.146 + PZLock *lock,
1.147 + char *file,
1.148 + PRIntn line
1.149 + );
1.150 +
1.151 +
1.152 +#define PZ_NewCondVar(l) pz_NewCondVar((l),__FILE__,__LINE__)
1.153 +extern PZCondVar *
1.154 + pz_NewCondVar(
1.155 + PZLock *lock,
1.156 + char *file,
1.157 + PRIntn line
1.158 + );
1.159 +
1.160 +#define PZ_DestroyCondVar(v) pz_DestroyCondVar((v),__FILE__,__LINE__)
1.161 +extern void
1.162 + pz_DestroyCondVar(
1.163 + PZCondVar *cvar,
1.164 + char *file,
1.165 + PRIntn line
1.166 + );
1.167 +
1.168 +#define PZ_WaitCondVar(v,t) pz_WaitCondVar((v),(t),__FILE__,__LINE__)
1.169 +extern PRStatus
1.170 + pz_WaitCondVar(
1.171 + PZCondVar *cvar,
1.172 + PRIntervalTime timeout,
1.173 + char *file,
1.174 + PRIntn line
1.175 + );
1.176 +
1.177 +#define PZ_NotifyCondVar(v) pz_NotifyCondVar((v),__FILE__,__LINE__)
1.178 +extern PRStatus
1.179 + pz_NotifyCondVar(
1.180 + PZCondVar *cvar,
1.181 + char *file,
1.182 + PRIntn line
1.183 + );
1.184 +
1.185 +#define PZ_NotifyAllCondVar(v) pz_NotifyAllCondVar((v),__FILE__,__LINE__)
1.186 +extern PRStatus
1.187 + pz_NotifyAllCondVar(
1.188 + PZCondVar *cvar,
1.189 + char *file,
1.190 + PRIntn line
1.191 + );
1.192 +
1.193 +
1.194 +#define PZ_NewMonitor(t) pz_NewMonitor((t),__FILE__,__LINE__)
1.195 +extern PZMonitor *
1.196 + pz_NewMonitor(
1.197 + nssILockType ltype,
1.198 + char *file,
1.199 + PRIntn line
1.200 + );
1.201 +
1.202 +#define PZ_DestroyMonitor(m) pz_DestroyMonitor((m),__FILE__,__LINE__)
1.203 +extern void
1.204 + pz_DestroyMonitor(
1.205 + PZMonitor *mon,
1.206 + char *file,
1.207 + PRIntn line
1.208 + );
1.209 +
1.210 +#define PZ_EnterMonitor(m) pz_EnterMonitor((m),__FILE__,__LINE__)
1.211 +extern void
1.212 + pz_EnterMonitor(
1.213 + PZMonitor *mon,
1.214 + char *file,
1.215 + PRIntn line
1.216 + );
1.217 +
1.218 +
1.219 +#define PZ_ExitMonitor(m) pz_ExitMonitor((m),__FILE__,__LINE__)
1.220 +extern PRStatus
1.221 + pz_ExitMonitor(
1.222 + PZMonitor *mon,
1.223 + char *file,
1.224 + PRIntn line
1.225 + );
1.226 +
1.227 +#define PZ_InMonitor(m) (PZ_GetMonitorEntryCount(m) > 0 )
1.228 +#define PZ_GetMonitorEntryCount(m) pz_GetMonitorEntryCount((m),__FILE__,__LINE__)
1.229 +extern PRIntn
1.230 + pz_GetMonitorEntryCount(
1.231 + PZMonitor *mon,
1.232 + char *file,
1.233 + PRIntn line
1.234 + );
1.235 +
1.236 +#define PZ_Wait(m,i) pz_Wait((m),((i)),__FILE__,__LINE__)
1.237 +extern PRStatus
1.238 + pz_Wait(
1.239 + PZMonitor *mon,
1.240 + PRIntervalTime ticks,
1.241 + char *file,
1.242 + PRIntn line
1.243 + );
1.244 +
1.245 +#define PZ_Notify(m) pz_Notify((m),__FILE__,__LINE__)
1.246 +extern PRStatus
1.247 + pz_Notify(
1.248 + PZMonitor *mon,
1.249 + char *file,
1.250 + PRIntn line
1.251 + );
1.252 +
1.253 +#define PZ_NotifyAll(m) pz_NotifyAll((m),__FILE__,__LINE__)
1.254 +extern PRStatus
1.255 + pz_NotifyAll(
1.256 + PZMonitor *mon,
1.257 + char *file,
1.258 + PRIntn line
1.259 + );
1.260 +
1.261 +#define PZ_TraceFlush() pz_TraceFlush()
1.262 +extern void pz_TraceFlush( void );
1.263 +
1.264 +#else /* NEED_NSS_ILOCK */
1.265 +
1.266 +#define PZ_NewLock(t) PR_NewLock()
1.267 +#define PZ_DestroyLock(k) PR_DestroyLock((k))
1.268 +#define PZ_Lock(k) PR_Lock((k))
1.269 +#define PZ_Unlock(k) PR_Unlock((k))
1.270 +
1.271 +#define PZ_NewCondVar(l) PR_NewCondVar((l))
1.272 +#define PZ_DestroyCondVar(v) PR_DestroyCondVar((v))
1.273 +#define PZ_WaitCondVar(v,t) PR_WaitCondVar((v),(t))
1.274 +#define PZ_NotifyCondVar(v) PR_NotifyCondVar((v))
1.275 +#define PZ_NotifyAllCondVar(v) PR_NotifyAllCondVar((v))
1.276 +
1.277 +#define PZ_NewMonitor(t) PR_NewMonitor()
1.278 +#define PZ_DestroyMonitor(m) PR_DestroyMonitor((m))
1.279 +#define PZ_EnterMonitor(m) PR_EnterMonitor((m))
1.280 +#define PZ_ExitMonitor(m) PR_ExitMonitor((m))
1.281 +#define PZ_InMonitor(m) PR_InMonitor((m))
1.282 +#define PZ_Wait(m,t) PR_Wait(((m)),((t)))
1.283 +#define PZ_Notify(m) PR_Notify((m))
1.284 +#define PZ_NotifyAll(m) PR_Notify((m))
1.285 +#define PZ_TraceFlush() /* nothing */
1.286 +
1.287 +
1.288 +#endif /* NEED_NSS_ILOCK */
1.289 +
1.290 +PR_END_EXTERN_C
1.291 +#endif /* _NSSILOCK_H_ */
