OSX/libsecurity_asn1/lib/nssilock.h

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