The Tor Browser: security/nss/lib/util/nssilckt.h@b8a032363ba2 (annotated)

security/nss/lib/util/nssilckt.h@b8a032363ba2 (annotated)

security/nss/lib/util/nssilckt.h

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* 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 _NSSILCKT_H_
 #define _NSSILCKT_H_
 #include "utilrename.h"
 #include "prtypes.h"
 #include "prmon.h"
 #include "prlock.h"
 #include "prcvar.h"
 typedef enum {
     nssILockArena = 0,
     nssILockSession = 1,
     nssILockObject = 2,
     nssILockRefLock = 3,
     nssILockCert = 4,
     nssILockCertDB = 5,
     nssILockDBM = 6,
     nssILockCache = 7,
     nssILockSSL = 8,
     nssILockList = 9,
     nssILockSlot = 10,
     nssILockFreelist = 11,
     nssILockOID = 12,
     nssILockAttribute = 13,
     nssILockPK11cxt = 14,  /* pk11context */
     nssILockRWLock = 15,
     nssILockOther = 16,
     nssILockSelfServ = 17,
     nssILockKeyDB = 18,
     nssILockLast  /* don't use this one! */
 } nssILockType;
 /*
 ** conditionally compile in nssilock features
 */
 #if defined(NEED_NSS_ILOCK)
 /*
 ** Declare operation type enumerator
 ** enumerations identify the function being performed
 */
 typedef enum  {
     FlushTT = 0,
     NewLock = 1,
     Lock = 2,
     Unlock = 3,
     DestroyLock = 4,
     NewCondVar = 5,
     WaitCondVar = 6,
     NotifyCondVar = 7,
     NotifyAllCondVar = 8,
     DestroyCondVar = 9,
     NewMonitor = 10,
     EnterMonitor = 11,
     ExitMonitor = 12,
     Notify = 13,
     NotifyAll = 14,
     Wait = 15,
     DestroyMonitor = 16
 } nssILockOp;
 /*
 ** Declare the trace record
 */
 struct pzTrace_s {
     PRUint32        threadID; /* PR_GetThreadID() */
     nssILockOp      op;       /* operation being performed */
     nssILockType    ltype;    /* lock type identifier */
     PRIntervalTime  callTime; /* time spent in function */
     PRIntervalTime  heldTime; /* lock held time, or -1 */
     void            *lock;    /* address of lock structure */
     PRIntn          line;     /* line number */
     char            file[24]; /* filename */
 };
 /*
 ** declare opaque types. See: nssilock.c
 */
 typedef struct pzlock_s PZLock;
 typedef struct pzcondvar_s PZCondVar;
 typedef struct pzmonitor_s PZMonitor;
 #else /* NEED_NSS_ILOCK */
 #define PZLock                  PRLock
 #define PZCondVar               PRCondVar
 #define PZMonitor               PRMonitor
 #endif /* NEED_NSS_ILOCK */
 #endif /* _NSSILCKT_H_ */

The Tor Browser / annotate

security/nss/lib/util/nssilckt.h@b8a032363ba2 (annotated)

security/nss/lib/util/nssilckt.h