security/nss/lib/util/nssilock.h

   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
 144 PR_BEGIN_EXTERN_C
 145
 146 #if defined(NEED_NSS_ILOCK)
 147
 148 #define PZ_NewLock(t) pz_NewLock((t),__FILE__,__LINE__)
 149 extern 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__)
 157 extern 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__)
 165 extern 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__)
 173 extern 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__)
 182 extern 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__)
 190 extern 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__)
 198 extern 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__)
 207 extern 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__)
 215 extern 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__)
 224 extern 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__)
 232 extern 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__)
 240 extern 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__)
 249 extern 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__)
 258 extern 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__)
 266 extern 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__)
 275 extern 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__)
 283 extern PRStatus
 284     pz_NotifyAll(
 285         PZMonitor *mon,
 286         char *file,
 287         PRIntn line
 288     );
 289
 290 #define PZ_TraceFlush() pz_TraceFlush()
 291 extern 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
 319 PR_END_EXTERN_C
 320 #endif /* _NSSILOCK_H_ */