prtrace.h

Netscape NSPR库源码

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is the Netscape Portable Runtime (NSPR).
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are 
 * Copyright (C) 1998-2000 Netscape Communications Corporation.  All
 * Rights Reserved.
 * 
 * Contributor(s):
 * 
 * Alternatively, the contents of this file may be used under the
 * terms of the GNU General Public License Version 2 or later (the
 * "GPL"), in which case the provisions of the GPL are applicable 
 * instead of those above.  If you wish to allow use of your 
 * version of this file only under the terms of the GPL and not to
 * allow others to use your version of this file under the MPL,
 * indicate your decision by deleting the provisions above and
 * replace them with the notice and other provisions required by
 * the GPL.  If you do not delete the provisions above, a recipient
 * may use your version of this file under either the MPL or the
 * GPL.
 */

#ifndef prtrace_h___
#define prtrace_h___
/*
** prtrace.h -- NSPR's Trace Facility.  		           
**                                                               		           
** The Trace Facility provides a means to trace application				           
** program events within a process. When implementing an         		           
** application program an engineer may insert a "Trace" function 		           
** call, passing arguments to be traced. The "Trace" function     		           
** combines the user trace data with identifying data and        		           
** writes this data in time ordered sequence into a circular     		           
** in-memory buffer; when the buffer fills, it wraps.
**                                                               		           
** Functions are provided to set and/or re-configure the size of		           
** the trace buffer, control what events are recorded in the			           
** buffer, enable and disable tracing based on specific user			           
** supplied data and other control functions. Methods are provided		           
** to record the trace entries in the in-memory trace buffer to
** a file.
**                                                               		           
** Tracing may cause a performance degredation to the application		           
** depending on the number and placement of calls to the tracing		           
** facility. When tracing is compiled in and all tracing is				           
** disabled via the runtime controls, the overhead should be			           
** minimal. ... Famous last words, eh?									           
** 																                   
** When DEBUG is defined at compile time, the Trace Facility is                    
** compiled as part of NSPR and any application using NSPR's                       
** header files will have tracing compiled in. When DEBUG is not                   
** defined, the Trace Facility is not compiled into NSPR nor                       
** exported in its header files.  If the Trace Facility is                         
** desired in a non-debug build, then FORCE_NSPR_TRACE may be                      
** defined at compile time for both the optimized build of NSPR                    
** and the application. NSPR and any application using  NSPR's                     
** Trace Facility must be compiled with the same level of trace                    
** conditioning or unresolved references may be realized at link                   
** time.                                                                           
**                                                                                 
** For any of the Trace Facility methods that requires a trace                     
** handle as an input argument, the caller must ensure that the                    
** trace handle argument is valid. An invalid trace handle                         
** argument may cause unpredictable results.                                       
**                                                                                 
** Trace Facility methods are thread-safe and SMP safe.                            
**                                                                                 
** Users of the Trace Facility should use the defined macros to                     
** invoke trace methods, not the function calls directly. e.g.                      
** PR_TRACE( h1,0,1,2, ...); not PR_Trace(h1,0,1,2, ...);
**                                                                                  
** Application designers should be aware of the effects of
** debug and optimized build differences when using result of the
** Trace Facility macros in expressions.
** 
** See Also: prcountr.h                                                                                 
**                                                                                  
** /lth. 08-Jun-1998.                                                                                  
*/

#include "prtypes.h"
#include "prthread.h"
#include "prtime.h"

PR_BEGIN_EXTERN_C

/*
** Opaque type for the trace handle 
** ... Don't even think about looking in here.
**
*/
typedef void *  PRTraceHandle;

#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
/*
** PRTraceEntry -- A trace entry in the in-memory trace buffer
** looks like this.
**
*/
typedef struct PRTraceEntry
{
    PRThread        *thread;        /* The thread creating the trace entry */
    PRTraceHandle   handle;         /* PRTraceHandle creating the trace entry */
    PRTime          time;           /* Value of PR_Now() at time of trace entry */
    PRUint32        userData[8];    /* user supplied trace data */
} PRTraceEntry;

/*
** PRTraceOption -- command operands to
** PR_[Set|Get]TraceOption(). See descriptive meanings there.
**
*/
typedef enum PRTraceOption
{
    PRTraceBufSize,
    PRTraceEnable,              
    PRTraceDisable,
    PRTraceSuspend,
    PRTraceResume,
    PRTraceSuspendRecording,
    PRTraceResumeRecording,
    PRTraceLockHandles,
    PRTraceUnLockHandles,
    PRTraceStopRecording
} PRTraceOption;

/* -----------------------------------------------------------------------
** FUNCTION: PR_DEFINE_TRACE() -- Define a PRTraceHandle
** 
** DESCRIPTION: PR_DEFINE_TRACE() is used to define a trace
** handle.
** 
*/
#define PR_DEFINE_TRACE(name) PRTraceHandle name

/* -----------------------------------------------------------------------
** FUNCTION: PR_INIT_TRACE_HANDLE() -- Set the value of a PRTraceHandle
** 
** DESCRIPTION: 
** PR_INIT_TRACE_HANDLE() sets the value of a PRTraceHandle
** to value. e.g. PR_INIT_TRACE_HANDLE( myHandle, NULL );
** 
*/
#define PR_INIT_TRACE_HANDLE(handle,value)\
    (handle) = (PRCounterHandle)(value)


/* -----------------------------------------------------------------------
** FUNCTION: PR_CreateTrace() -- Create a trace handle
** 
** DESCRIPTION:
**  PR_CreateTrace() creates a new trace handle. Tracing is
**  enabled for this handle when it is created. The trace handle
**  is intended for use in other Trace Facility calls.
**  
**  PR_CreateTrace() registers the QName, RName and description
**  data so that this data can be retrieved later.
** 
** INPUTS: 
**  qName: pointer to string. QName for this trace handle. 
** 
**  rName: pointer to string. RName for this trace handle. 
** 
**  description: pointer to string. Descriptive data about this
**  trace handle.
**
** OUTPUTS:
**  Creates the trace handle. 
**  Registers the QName and RName with the trace facility.
** 
** RETURNS: 
**  PRTraceHandle
** 
** RESTRICTIONS:
**  qName is limited to 31 characters.
**  rName is limited to 31 characters.
**  description is limited to 255 characters.
** 
*/
#define PRTRACE_NAME_MAX 31
#define PRTRACE_DESC_MAX 255

#define PR_CREATE_TRACE(handle,qName,rName,description)\
    (handle) = PR_CreateTrace((qName),(rName),(description))

NSPR_API(PRTraceHandle)
	PR_CreateTrace( 
    	const char *qName,          /* QName for this trace handle */
	    const char *rName,          /* RName for this trace handle */
	    const char *description     /* description for this trace handle */
);


/* -----------------------------------------------------------------------
** FUNCTION: PR_DestroyTrace() -- Destroy a trace handle
** 
** DESCRIPTION: 
**  PR_DestroyTrace() removes the referenced trace handle and
** associated QName, RName and description data from the Trace
** Facility.
** 
** INPUTS: handle. A PRTraceHandle
** 
** OUTPUTS: 
**  The trace handle is unregistered.
**  The QName, RName and description are removed.
** 
** RETURNS: void
** 
** RESTRICTIONS:
** 
*/
#define PR_DESTROY_TRACE(handle)\
    PR_DestroyTrace((handle))

NSPR_API(void) 
	PR_DestroyTrace( 
		PRTraceHandle handle    /* Handle to be destroyed */
);


/* -----------------------------------------------------------------------
** FUNCTION: PR_Trace() -- Make a trace entry in the in-memory trace
** 
** DESCRIPTION:
** PR_Trace() makes an entry in the in-memory trace buffer for
** the referenced trace handle. The next logically available
** PRTraceEntry is used; when the next trace entry would overflow
** the trace table, the table wraps.
**
** PR_Trace() for a specific trace handle may be disabled by
** calling PR_SetTraceOption() specifying PRTraceDisable for the
** trace handle to be disabled.
** 
** INPUTS:
** handle: PRTraceHandle. The trace handle for this trace.
** 
** userData[0..7]: unsigned 32bit integers. user supplied data
** that is copied into the PRTraceEntry
** 
** OUTPUTS:
**  A PRTraceEntry is (conditionally) formatted in the in-memory
** trace buffer.
** 
** RETURNS: void.
** 
** RESTRICTIONS:
** 
*/
#define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)\
    PR_Trace((handle),(ud0),(ud1),(ud2),(ud3),(ud4),(ud5),(ud6),(ud7))

NSPR_API(void) 
	PR_Trace( 
    	PRTraceHandle handle,       /* use this trace handle */
	    PRUint32    userData0,      /* User supplied data word 0 */
	    PRUint32    userData1,      /* User supplied data word 1 */
	    PRUint32    userData2,      /* User supplied data word 2 */
	    PRUint32    userData3,      /* User supplied data word 3 */
	    PRUint32    userData4,      /* User supplied data word 4 */
	    PRUint32    userData5,      /* User supplied data word 5 */
	    PRUint32    userData6,      /* User supplied data word 6 */
	    PRUint32    userData7       /* User supplied data word 7 */
);

/* -----------------------------------------------------------------------
** FUNCTION: PR_SetTraceOption() -- Control the Trace Facility
** 
** DESCRIPTION:
** PR_SetTraceOption() controls the Trace Facility. Depending on
** command and value, attributes of the Trace Facility may be
** changed.
** 
** INPUTS:
**  command: An enumerated value in the set of PRTraceOption.
**  value: pointer to the data to be set. Type of the data is
**  dependent on command; for each value of command, the type
**  and meaning of dereferenced value is shown.
**
**  PRTraceBufSize: unsigned long: the size of the trace buffer,
** in bytes.
** 
**  PRTraceEnable: PRTraceHandle. The trace handle to be
** enabled.
** 
**  PRTraceDisable: PRTraceHandle. The trace handle to be
** disabled.
** 
**  PRTraceSuspend: void. value must be NULL. All tracing is
** suspended.
** 
**  PRTraceResume: void. value must be NULL. Tracing for all
** previously enabled, prior to a PRTraceSuspend, is resumed.
** 
**  PRTraceStopRecording: void. value must be NULL. If recording
** (see: ** PR_RecordTraceEntries()) is being done, 
** PRTraceStopRecording causes PR_RecordTraceEntries() to return
** to its caller. If recording is not being done, this function
** has no effect.
** 
**  PRTraceSuspendRecording: void. Must be NULL. If recording is
** being done, PRTraceSuspendRecording causes further writes to
** the trace file to be suspended. Data in the in-memory
** trace buffer that would ordinarily be written to the
** trace file will not be written. Trace entries will continue
** to be entered in the in-memory buffer. If the Trace Facility
** recording is already in a suspended state, the call has no
** effect.
** 
**  PRTraceResumeRecording: void. value must be NULL. If
** recording for the Trace Facility has been previously been
** suspended, this causes recording to resume. Recording resumes
** with the next in-memory buffer segment that would be written
** if trace recording had not been suspended. If recording is