Back to index

lightning-sunbird  0.9+nobinonly
nssilckt.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 /*
00038 ** nssilock.h - Instrumented locking functions for NSS
00039 **
00040 ** Description:
00041 **    nssilock provides instrumentation for locks and monitors in
00042 **    the NSS libraries. The instrumentation, when enabled, causes
00043 **    each call to the instrumented function to record data about
00044 **    the call to an external file. The external file
00045 **    subsequently used to extract performance data and other
00046 **    statistical information about the operation of locks used in
00047 **    the nss library.
00048 **     
00049 **    To enable compilation with instrumentation, build NSS with 
00050 **    the compile time switch NEED_NSS_ILOCK defined.
00051 **
00052 **    say:  "gmake OS_CFLAGS+=-DNEED_NSS_ILOCK" at make time.
00053 **
00054 **    At runtime, to enable recording from nssilock, one or more
00055 **    environment variables must be set. For each nssILockType to
00056 **    be recorded, an environment variable of the form NSS_ILOCK_x
00057 **    must be set to 1. For example:
00058 **
00059 **       set NSS_ILOCK_Cert=1
00060 **
00061 **    nssilock uses PRLOG is used to record to trace data. The
00062 **    PRLogModule name associated with nssilock data is: "nssilock".
00063 **    To enable recording of nssilock data you will need to set the
00064 **    environment variable NSPR_LOG_MODULES to enable
00065 **    recording for the nssilock log module. Similarly, you will
00066 **    need to set the environment variable NSPR_LOG_FILE to specify
00067 **    the filename to receive the recorded data. See prlog.h for usage.
00068 **    Example:
00069 **
00070 **        export NSPR_LOG_MODULES=nssilock:6
00071 **        export NSPR_LOG_FILE=xxxLogfile
00072 **
00073 ** Operation:
00074 **    nssilock wraps calls to NSPR's PZLock and PZMonitor functions
00075 **    with similarly named functions: PZ_NewLock(), etc. When NSS is
00076 **    built with lock instrumentation enabled, the PZ* functions are
00077 **    compiled into NSS; when lock instrumentation is disabled,
00078 **    calls to PZ* functions are directly mapped to PR* functions
00079 **    and the instrumentation arguments to the PZ* functions are
00080 **    compiled away.
00081 **
00082 **
00083 ** File Format:
00084 **    The format of the external file is implementation
00085 **    dependent. Where NSPR's PR_LOG() function is used, the file
00086 **    contains data defined for PR_LOG() plus the data written by
00087 **    the wrapped function. On some platforms and under some
00088 **    circumstances, platform dependent logging or
00089 **    instrumentation probes may be used. In any case, the
00090 **    relevant data provided by the lock instrumentation is:
00091 **    
00092 **      lockType, func, address, duration, line, file [heldTime]
00093 ** 
00094 **    where:
00095 **    
00096 **       lockType: a character representation of nssILockType for the
00097 **       call. e.g. ... "cert"
00098 **    
00099 **       func: the function doing the tracing. e.g. "NewLock"
00100 **    
00101 **       address: address of the instrumented lock or monitor
00102 **    
00103 **       duration: is how long was spent in the instrumented function,
00104 **       in PRIntervalTime "ticks".
00105 **    
00106 **       line: the line number within the calling function
00107 **    
00108 **       file: the file from which the call was made
00109 **    
00110 **       heldTime: how long the lock/monitor was held. field
00111 **       present only for PZ_Unlock() and PZ_ExitMonitor().
00112 **    
00113 ** Design Notes:
00114 **    The design for lock instrumentation was influenced by the
00115 **    need to gather performance data on NSS 3.x. It is intended
00116 **    that the effort to modify NSS to use lock instrumentation
00117 **    be minimized. Existing calls to locking functions need only
00118 **    have their names changed to the instrumentation function
00119 **    names.
00120 **    
00121 ** Private NSS Interface:
00122 **    nssilock.h defines a private interface for use by NSS.
00123 **    nssilock.h is experimental in nature and is subject to
00124 **    change or revocation without notice. ... Don't mess with
00125 **    it.
00126 **    
00127 */
00128 
00129 /*
00130  * $Id:
00131  */
00132 
00133 #ifndef _NSSILCKT_H_
00134 #define _NSSILCKT_H_
00135 
00136 #include "prtypes.h"
00137 #include "prmon.h"
00138 #include "prlock.h"
00139 #include "prcvar.h"
00140 
00141 typedef enum {
00142     nssILockArena = 0,
00143     nssILockSession = 1,
00144     nssILockObject = 2,
00145     nssILockRefLock = 3,
00146     nssILockCert = 4,
00147     nssILockCertDB = 5,
00148     nssILockDBM = 6,
00149     nssILockCache = 7,
00150     nssILockSSL = 8,
00151     nssILockList = 9,
00152     nssILockSlot = 10,
00153     nssILockFreelist = 11,
00154     nssILockOID = 12,
00155     nssILockAttribute = 13,
00156     nssILockPK11cxt = 14,  /* pk11context */
00157     nssILockRWLock = 15,
00158     nssILockOther = 16,
00159     nssILockSelfServ = 17,
00160     nssILockKeyDB = 18,
00161     nssILockLast  /* don't use this one! */
00162 } nssILockType;
00163 
00164 /*
00165 ** Declare operation type enumerator
00166 ** enumerations identify the function being performed
00167 */
00168 typedef enum  {
00169     FlushTT = 0,
00170     NewLock = 1,
00171     Lock = 2,
00172     Unlock = 3,
00173     DestroyLock = 4,
00174     NewCondVar = 5,
00175     WaitCondVar = 6,
00176     NotifyCondVar = 7,
00177     NotifyAllCondVar = 8,
00178     DestroyCondVar = 9,
00179     NewMonitor = 10,
00180     EnterMonitor = 11,
00181     ExitMonitor = 12,
00182     Notify = 13,
00183     NotifyAll = 14,
00184     Wait = 15,
00185     DestroyMonitor = 16
00186 } nssILockOp;
00187 
00188 /*
00189 ** Declare the trace record
00190 */
00191 struct pzTrace_s {
00192     PRUint32        threadID; /* PR_GetThreadID() */
00193     nssILockOp      op;       /* operation being performed */
00194     nssILockType    ltype;    /* lock type identifier */
00195     PRIntervalTime  callTime; /* time spent in function */
00196     PRIntervalTime  heldTime; /* lock held time, or -1 */
00197     void            *lock;    /* address of lock structure */    
00198     PRIntn          line;     /* line number */
00199     char            file[24]; /* filename */
00200 };
00201 
00202 PR_BEGIN_EXTERN_C
00203 /*
00204 ** conditionally compile in nssilock features
00205 */
00206 #if defined(NEED_NSS_ILOCK)
00207 
00208 /*
00209 ** declare opaque types. See: nssilock.c
00210 */
00211 typedef struct pzlock_s PZLock;
00212 typedef struct pzcondvar_s PZCondVar;
00213 typedef struct pzmonitor_s PZMonitor;
00214 
00215 #else /* NEED_NSS_ILOCK */
00216 
00217 #define PZLock                  PRLock
00218 #define PZCondVar               PRCondVar
00219 #define PZMonitor               PRMonitor
00220     
00221 #endif /* NEED_NSS_ILOCK */
00222 
00223 PR_END_EXTERN_C
00224 #endif /* _NSSILCKT_H_ */