andre@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
andre@0: /* This Source Code Form is subject to the terms of the Mozilla Public
andre@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
andre@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
andre@0: 
andre@0: #ifndef prtrace_h___
andre@0: #define prtrace_h___
andre@0: /*
andre@0: ** prtrace.h -- NSPR's Trace Facility.  		           
andre@0: **                                                               		           
andre@0: ** The Trace Facility provides a means to trace application				           
andre@0: ** program events within a process. When implementing an         		           
andre@0: ** application program an engineer may insert a "Trace" function 		           
andre@0: ** call, passing arguments to be traced. The "Trace" function     		           
andre@0: ** combines the user trace data with identifying data and        		           
andre@0: ** writes this data in time ordered sequence into a circular     		           
andre@0: ** in-memory buffer; when the buffer fills, it wraps.
andre@0: **                                                               		           
andre@0: ** Functions are provided to set and/or re-configure the size of		           
andre@0: ** the trace buffer, control what events are recorded in the			           
andre@0: ** buffer, enable and disable tracing based on specific user			           
andre@0: ** supplied data and other control functions. Methods are provided		           
andre@0: ** to record the trace entries in the in-memory trace buffer to
andre@0: ** a file.
andre@0: **                                                               		           
andre@0: ** Tracing may cause a performance degredation to the application		           
andre@0: ** depending on the number and placement of calls to the tracing		           
andre@0: ** facility. When tracing is compiled in and all tracing is				           
andre@0: ** disabled via the runtime controls, the overhead should be			           
andre@0: ** minimal. ... Famous last words, eh?									           
andre@0: ** 																                   
andre@0: ** When DEBUG is defined at compile time, the Trace Facility is                    
andre@0: ** compiled as part of NSPR and any application using NSPR's                       
andre@0: ** header files will have tracing compiled in. When DEBUG is not                   
andre@0: ** defined, the Trace Facility is not compiled into NSPR nor                       
andre@0: ** exported in its header files.  If the Trace Facility is                         
andre@0: ** desired in a non-debug build, then FORCE_NSPR_TRACE may be                      
andre@0: ** defined at compile time for both the optimized build of NSPR                    
andre@0: ** and the application. NSPR and any application using  NSPR's                     
andre@0: ** Trace Facility must be compiled with the same level of trace                    
andre@0: ** conditioning or unresolved references may be realized at link                   
andre@0: ** time.                                                                           
andre@0: **                                                                                 
andre@0: ** For any of the Trace Facility methods that requires a trace                     
andre@0: ** handle as an input argument, the caller must ensure that the                    
andre@0: ** trace handle argument is valid. An invalid trace handle                         
andre@0: ** argument may cause unpredictable results.                                       
andre@0: **                                                                                 
andre@0: ** Trace Facility methods are thread-safe and SMP safe.                            
andre@0: **                                                                                 
andre@0: ** Users of the Trace Facility should use the defined macros to                     
andre@0: ** invoke trace methods, not the function calls directly. e.g.                      
andre@0: ** PR_TRACE( h1,0,1,2, ...); not PR_Trace(h1,0,1,2, ...);
andre@0: **                                                                                  
andre@0: ** Application designers should be aware of the effects of
andre@0: ** debug and optimized build differences when using result of the
andre@0: ** Trace Facility macros in expressions.
andre@0: ** 
andre@0: ** See Also: prcountr.h                                                                                 
andre@0: **                                                                                  
andre@0: ** /lth. 08-Jun-1998.                                                                                  
andre@0: */
andre@0: 
andre@0: #include "prtypes.h"
andre@0: #include "prthread.h"
andre@0: #include "prtime.h"
andre@0: 
andre@0: PR_BEGIN_EXTERN_C
andre@0: 
andre@0: /*
andre@0: ** Opaque type for the trace handle 
andre@0: ** ... Don't even think about looking in here.
andre@0: **
andre@0: */
andre@0: typedef void *  PRTraceHandle;
andre@0: 
andre@0: /*
andre@0: ** PRTraceEntry -- A trace entry in the in-memory trace buffer
andre@0: ** looks like this.
andre@0: **
andre@0: */
andre@0: typedef struct PRTraceEntry
andre@0: {
andre@0:     PRThread        *thread;        /* The thread creating the trace entry */
andre@0:     PRTraceHandle   handle;         /* PRTraceHandle creating the trace entry */
andre@0:     PRTime          time;           /* Value of PR_Now() at time of trace entry */
andre@0:     PRUint32        userData[8];    /* user supplied trace data */
andre@0: } PRTraceEntry;
andre@0: 
andre@0: /*
andre@0: ** PRTraceOption -- command operands to
andre@0: ** PR_[Set|Get]TraceOption(). See descriptive meanings there.
andre@0: **
andre@0: */
andre@0: typedef enum PRTraceOption
andre@0: {
andre@0:     PRTraceBufSize,
andre@0:     PRTraceEnable,              
andre@0:     PRTraceDisable,
andre@0:     PRTraceSuspend,
andre@0:     PRTraceResume,
andre@0:     PRTraceSuspendRecording,
andre@0:     PRTraceResumeRecording,
andre@0:     PRTraceLockHandles,
andre@0:     PRTraceUnLockHandles,
andre@0:     PRTraceStopRecording
andre@0: } PRTraceOption;
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_DEFINE_TRACE() -- Define a PRTraceHandle
andre@0: ** 
andre@0: ** DESCRIPTION: PR_DEFINE_TRACE() is used to define a trace
andre@0: ** handle.
andre@0: ** 
andre@0: */
andre@0: #define PR_DEFINE_TRACE(name) PRTraceHandle name
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_INIT_TRACE_HANDLE() -- Set the value of a PRTraceHandle
andre@0: ** 
andre@0: ** DESCRIPTION: 
andre@0: ** PR_INIT_TRACE_HANDLE() sets the value of a PRTraceHandle
andre@0: ** to value. e.g. PR_INIT_TRACE_HANDLE( myHandle, NULL );
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_INIT_TRACE_HANDLE(handle,value)\
andre@0:     (handle) = (PRCounterHandle)(value)
andre@0: #else
andre@0: #define PR_INIT_TRACE_HANDLE(handle,value)
andre@0: #endif
andre@0: 
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_CreateTrace() -- Create a trace handle
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: **  PR_CreateTrace() creates a new trace handle. Tracing is
andre@0: **  enabled for this handle when it is created. The trace handle
andre@0: **  is intended for use in other Trace Facility calls.
andre@0: **  
andre@0: **  PR_CreateTrace() registers the QName, RName and description
andre@0: **  data so that this data can be retrieved later.
andre@0: ** 
andre@0: ** INPUTS: 
andre@0: **  qName: pointer to string. QName for this trace handle. 
andre@0: ** 
andre@0: **  rName: pointer to string. RName for this trace handle. 
andre@0: ** 
andre@0: **  description: pointer to string. Descriptive data about this
andre@0: **  trace handle.
andre@0: **
andre@0: ** OUTPUTS:
andre@0: **  Creates the trace handle. 
andre@0: **  Registers the QName and RName with the trace facility.
andre@0: ** 
andre@0: ** RETURNS: 
andre@0: **  PRTraceHandle
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: **  qName is limited to 31 characters.
andre@0: **  rName is limited to 31 characters.
andre@0: **  description is limited to 255 characters.
andre@0: ** 
andre@0: */
andre@0: #define PRTRACE_NAME_MAX 31
andre@0: #define PRTRACE_DESC_MAX 255
andre@0: 
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_CREATE_TRACE(handle,qName,rName,description)\
andre@0:     (handle) = PR_CreateTrace((qName),(rName),(description))
andre@0: #else
andre@0: #define PR_CREATE_TRACE(handle,qName,rName,description)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(PRTraceHandle)
andre@0: 	PR_CreateTrace( 
andre@0:     	const char *qName,          /* QName for this trace handle */
andre@0: 	    const char *rName,          /* RName for this trace handle */
andre@0: 	    const char *description     /* description for this trace handle */
andre@0: );
andre@0: 
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_DestroyTrace() -- Destroy a trace handle
andre@0: ** 
andre@0: ** DESCRIPTION: 
andre@0: **  PR_DestroyTrace() removes the referenced trace handle and
andre@0: ** associated QName, RName and description data from the Trace
andre@0: ** Facility.
andre@0: ** 
andre@0: ** INPUTS: handle. A PRTraceHandle
andre@0: ** 
andre@0: ** OUTPUTS: 
andre@0: **  The trace handle is unregistered.
andre@0: **  The QName, RName and description are removed.
andre@0: ** 
andre@0: ** RETURNS: void
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_DESTROY_TRACE(handle)\
andre@0:     PR_DestroyTrace((handle))
andre@0: #else
andre@0: #define PR_DESTROY_TRACE(handle)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(void) 
andre@0: 	PR_DestroyTrace( 
andre@0: 		PRTraceHandle handle    /* Handle to be destroyed */
andre@0: );
andre@0: 
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_Trace() -- Make a trace entry in the in-memory trace
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: ** PR_Trace() makes an entry in the in-memory trace buffer for
andre@0: ** the referenced trace handle. The next logically available
andre@0: ** PRTraceEntry is used; when the next trace entry would overflow
andre@0: ** the trace table, the table wraps.
andre@0: **
andre@0: ** PR_Trace() for a specific trace handle may be disabled by
andre@0: ** calling PR_SetTraceOption() specifying PRTraceDisable for the
andre@0: ** trace handle to be disabled.
andre@0: ** 
andre@0: ** INPUTS:
andre@0: ** handle: PRTraceHandle. The trace handle for this trace.
andre@0: ** 
andre@0: ** userData[0..7]: unsigned 32bit integers. user supplied data
andre@0: ** that is copied into the PRTraceEntry
andre@0: ** 
andre@0: ** OUTPUTS:
andre@0: **  A PRTraceEntry is (conditionally) formatted in the in-memory
andre@0: ** trace buffer.
andre@0: ** 
andre@0: ** RETURNS: void.
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)\
andre@0:     PR_Trace((handle),(ud0),(ud1),(ud2),(ud3),(ud4),(ud5),(ud6),(ud7))
andre@0: #else
andre@0: #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(void) 
andre@0: 	PR_Trace( 
andre@0:     	PRTraceHandle handle,       /* use this trace handle */
andre@0: 	    PRUint32    userData0,      /* User supplied data word 0 */
andre@0: 	    PRUint32    userData1,      /* User supplied data word 1 */
andre@0: 	    PRUint32    userData2,      /* User supplied data word 2 */
andre@0: 	    PRUint32    userData3,      /* User supplied data word 3 */
andre@0: 	    PRUint32    userData4,      /* User supplied data word 4 */
andre@0: 	    PRUint32    userData5,      /* User supplied data word 5 */
andre@0: 	    PRUint32    userData6,      /* User supplied data word 6 */
andre@0: 	    PRUint32    userData7       /* User supplied data word 7 */
andre@0: );
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_SetTraceOption() -- Control the Trace Facility
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: ** PR_SetTraceOption() controls the Trace Facility. Depending on
andre@0: ** command and value, attributes of the Trace Facility may be
andre@0: ** changed.
andre@0: ** 
andre@0: ** INPUTS:
andre@0: **  command: An enumerated value in the set of PRTraceOption.
andre@0: **  value: pointer to the data to be set. Type of the data is
andre@0: **  dependent on command; for each value of command, the type
andre@0: **  and meaning of dereferenced value is shown.
andre@0: **
andre@0: **  PRTraceBufSize: unsigned long: the size of the trace buffer,
andre@0: ** in bytes.
andre@0: ** 
andre@0: **  PRTraceEnable: PRTraceHandle. The trace handle to be
andre@0: ** enabled.
andre@0: ** 
andre@0: **  PRTraceDisable: PRTraceHandle. The trace handle to be
andre@0: ** disabled.
andre@0: ** 
andre@0: **  PRTraceSuspend: void. value must be NULL. All tracing is
andre@0: ** suspended.
andre@0: ** 
andre@0: **  PRTraceResume: void. value must be NULL. Tracing for all
andre@0: ** previously enabled, prior to a PRTraceSuspend, is resumed.
andre@0: ** 
andre@0: **  PRTraceStopRecording: void. value must be NULL. If recording
andre@0: ** (see: ** PR_RecordTraceEntries()) is being done, 
andre@0: ** PRTraceStopRecording causes PR_RecordTraceEntries() to return
andre@0: ** to its caller. If recording is not being done, this function
andre@0: ** has no effect.
andre@0: ** 
andre@0: **  PRTraceSuspendRecording: void. Must be NULL. If recording is
andre@0: ** being done, PRTraceSuspendRecording causes further writes to
andre@0: ** the trace file to be suspended. Data in the in-memory
andre@0: ** trace buffer that would ordinarily be written to the
andre@0: ** trace file will not be written. Trace entries will continue
andre@0: ** to be entered in the in-memory buffer. If the Trace Facility
andre@0: ** recording is already in a suspended state, the call has no
andre@0: ** effect.
andre@0: ** 
andre@0: **  PRTraceResumeRecording: void. value must be NULL. If
andre@0: ** recording for the Trace Facility has been previously been
andre@0: ** suspended, this causes recording to resume. Recording resumes
andre@0: ** with the next in-memory buffer segment that would be written
andre@0: ** if trace recording had not been suspended. If recording is
andre@0: ** not currently suspended, the call has no effect.
andre@0: ** 
andre@0: **  PRTraceLockHandles: void. value must be NULL. Locks the
andre@0: ** trace handle lock. While the trace handle lock is held,
andre@0: ** calls to PR_CreateTrace() will block until the lock is
andre@0: ** released.
andre@0: ** 
andre@0: **  PRTraceUnlockHandles: void. value must be NULL. Unlocks the
andre@0: ** trace handle lock.
andre@0: ** 
andre@0: ** OUTPUTS:
andre@0: **  The operation of the Trace Facility may be changed.
andre@0: ** 
andre@0: ** RETURNS: void
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_SET_TRACE_OPTION(command,value)\
andre@0:     PR_SetTraceOption((command),(value))
andre@0: #else
andre@0: #define PR_SET_TRACE_OPTION(command,value)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(void) 
andre@0: 	PR_SetTraceOption( 
andre@0: 	    PRTraceOption command,  /* One of the enumerated values */
andre@0: 	    void *value             /* command value or NULL */
andre@0: );
andre@0: 
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_GetTraceOption() -- Retrieve settings from the Trace Facility
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: ** PR_GetTraceOption() retrieves the current setting of the
andre@0: ** Trace Facility control depending on command.
andre@0: ** 
andre@0: ** 
andre@0: **  PRTraceBufSize: unsigned long: the size of the trace buffer,
andre@0: ** in bytes.
andre@0: ** 
andre@0: ** 
andre@0: ** INPUTS:
andre@0: **  command: one of the enumerated values in PRTraceOptions
andre@0: ** valid for PR_GetTraceOption().
andre@0: ** 
andre@0: ** OUTPUTS:
andre@0: **  dependent on command.
andre@0: ** 
andre@0: ** RETURNS: void
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_GET_TRACE_OPTION(command,value)\
andre@0:     PR_GetTraceOption((command),(value))
andre@0: #else
andre@0: #define PR_GET_TRACE_OPTION(command,value)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(void) 
andre@0: 	PR_GetTraceOption( 
andre@0:     	PRTraceOption command,  /* One of the enumerated values */
andre@0: 	    void *value             /* command value or NULL */
andre@0: );
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_GetTraceHandleFromName() -- Retrieve an existing
andre@0: ** handle by name.
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: ** PR_GetTraceHandleFromName() retreives an existing tracehandle
andre@0: ** using the name specified by qName and rName.
andre@0: ** 
andre@0: ** INPUTS:
andre@0: **  qName: pointer to string. QName for this trace handle. 
andre@0: ** 
andre@0: **  rName: pointer to string. RName for this trace handle. 
andre@0: ** 
andre@0: ** 
andre@0: ** OUTPUTS: returned.
andre@0: ** 
andre@0: ** RETURNS: 
andre@0: **  PRTraceHandle associated with qName and rName or NULL when
andre@0: ** there is no match.
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)\
andre@0:     (handle) = PR_GetTraceHandleFromName((qName),(rName))
andre@0: #else
andre@0: #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(PRTraceHandle) 
andre@0: 	PR_GetTraceHandleFromName( 
andre@0:     	const char *qName,      /* QName search argument */
andre@0:         const char *rName       /* RName search argument */
andre@0: );
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_GetTraceNameFromHandle() -- Retreive trace name
andre@0: ** by bandle.
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: ** PR_GetTraceNameFromHandle() retreives the existing qName,
andre@0: ** rName, and description for the referenced trace handle.
andre@0: ** 
andre@0: ** INPUTS: handle: PRTraceHandle.
andre@0: ** 
andre@0: ** OUTPUTS: pointers to the Trace Facility's copy of qName,
andre@0: ** rName and description. ... Don't mess with these values.
andre@0: ** They're mine.
andre@0: ** 
andre@0: ** RETURNS: void
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)\
andre@0:     PR_GetTraceNameFromHandle((handle),(qName),(rName),(description))
andre@0: #else
andre@0: #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(void) 
andre@0: 	PR_GetTraceNameFromHandle( 
andre@0:     	PRTraceHandle handle,       /* handle as search argument */
andre@0: 	    const char **qName,         /* pointer to associated QName */
andre@0: 	    const char **rName,         /* pointer to associated RName */
andre@0:     	const char **description    /* pointer to associated description */
andre@0: );
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_FindNextTraceQname() -- Retrieive a QName handle
andre@0: ** iterator.
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: ** PR_FindNextTraceQname() retreives the first or next trace
andre@0: ** QName handle, depending on the value of handle, from the trace
andre@0: ** database. The PRTraceHandle returned can be used as an
andre@0: ** iterator to traverse the QName handles in the Trace database.
andre@0: ** 
andre@0: ** INPUTS:
andre@0: **  handle: When NULL, PR_FindNextQname() returns the first QName
andre@0: ** handle. When a handle is a valid PRTraceHandle previously
andre@0: ** retreived using PR_FindNextQname() the next QName handle is
andre@0: ** retreived.
andre@0: ** 
andre@0: ** OUTPUTS: returned.
andre@0: ** 
andre@0: ** RETURNS: 
andre@0: **  PRTraceHandle or NULL when there are no trace handles.
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: **  Iterating thru the trace handles via FindFirst/FindNext
andre@0: ** should be done under protection of the trace handle lock.
andre@0: ** See: PR_SetTraceOption( PRLockTraceHandles ).
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_FIND_NEXT_TRACE_QNAME(next,handle)\
andre@0:     (next) = PR_FindNextTraceQname((handle))
andre@0: #else
andre@0: #define PR_FIND_NEXT_TRACE_QNAME(next,handle)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(PRTraceHandle) 
andre@0: 	PR_FindNextTraceQname( 
andre@0:         PRTraceHandle handle
andre@0: );
andre@0: 
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_FindNextTraceRname() -- Retrieive an RName handle
andre@0: ** iterator.
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: ** PR_FindNextTraceRname() retreives the first or next trace
andre@0: ** RName handle, depending on the value of handle, from the trace
andre@0: ** database. The PRTraceHandle returned can be used as an
andre@0: ** iterator to traverse the RName handles in the Trace database.
andre@0: ** 
andre@0: ** INPUTS:
andre@0: **  rhandle: When NULL, PR_FindNextRname() returns the first
andre@0: ** RName handle. When a handle is a valid PRTraceHandle
andre@0: ** previously retreived using PR_FindNextRname() the next RName
andre@0: ** handle is retreived.
andre@0: **  qhandle: A valid PRTraceHandle retruned from a previous call
andre@0: ** to PR_FIND_NEXT_TRACE_QNAME().
andre@0: ** 
andre@0: ** OUTPUTS: returned.
andre@0: ** 
andre@0: ** RETURNS: 
andre@0: **  PRTraceHandle or NULL when there are no trace handles.
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: **  Iterating thru the trace handles via FindNext should be done
andre@0: ** under protection of the trace handle lock. See: (
andre@0: ** PR_SetTraceOption( PRLockTraceHandles ).
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)\
andre@0:     (next) = PR_FindNextTraceRname((rhandle),(qhandle))
andre@0: #else
andre@0: #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(PRTraceHandle) 
andre@0: 	PR_FindNextTraceRname( 
andre@0:         PRTraceHandle rhandle,
andre@0:         PRTraceHandle qhandle
andre@0: );
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_RecordTraceEntries() -- Write trace entries to external media
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: ** PR_RecordTraceEntries() causes entries in the in-memory trace
andre@0: ** buffer to be written to external media.
andre@0: **
andre@0: ** When PR_RecordTraceEntries() is called from an application
andre@0: ** thread, the function appears to block until another thread
andre@0: ** calls PR_SetTraceOption() with the PRTraceStopRecording
andre@0: ** option. This suggests that PR_RecordTraceEntries() should be
andre@0: ** called from a user supplied thread whose only job is to
andre@0: ** record trace entries. 
andre@0: ** 
andre@0: ** The environment variable NSPR_TRACE_LOG controls the operation
andre@0: ** of this function. When NSPR_TRACE_LOG is not defined in the
andre@0: ** environment, no recording of trace entries occurs. When
andre@0: ** NSPR_TRACE_LOG is defined, the value of its definition must be
andre@0: ** the filename of the file to receive the trace entry buffer.
andre@0: **
andre@0: ** PR_RecordTraceEntries() attempts to record the in-memory
andre@0: ** buffer to a file, subject to the setting of the environment
andre@0: ** variable NSPR_TRACE_LOG. It is possible because of system
andre@0: ** load, the thread priority of the recording thread, number of
andre@0: ** active trace records being written over time, and other
andre@0: ** variables that some trace records can be lost. ... In other
andre@0: ** words: don't bet the farm on getting everything.
andre@0: ** 
andre@0: ** INPUTS: none
andre@0: ** 
andre@0: ** OUTPUTS: none
andre@0: ** 
andre@0: ** RETURNS: PR_STATUS
andre@0: **    PR_SUCCESS no errors were found.
andre@0: **    PR_FAILURE errors were found.
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: ** Only one thread can call PR_RecordTraceEntries() within a
andre@0: ** process.
andre@0: ** 
andre@0: ** On error, PR_RecordTraceEntries() may return prematurely.
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_RECORD_TRACE_ENTRIES()\
andre@0: 	PR_RecordTraceEntries()
andre@0: #else
andre@0: #define PR_RECORD_TRACE_ENTRIES()
andre@0: #endif
andre@0:     
andre@0: NSPR_API(void)
andre@0: 	PR_RecordTraceEntries(
andre@0:         void 
andre@0: );
andre@0: 
andre@0: /* -----------------------------------------------------------------------
andre@0: ** FUNCTION: PR_GetTraceEntries() -- Retreive trace entries from
andre@0: ** the Trace Facility
andre@0: ** 
andre@0: ** DESCRIPTION:
andre@0: ** PR_GetTraceEntries() retreives trace entries from the Trace
andre@0: ** Facility. Up to count trace entries are copied from the Trace
andre@0: ** Facility into buffer. Only those trace entries that have not
andre@0: ** been copied via a previous call to PR_GetTraceEntries() are
andre@0: ** copied. The actual number copied is placed in the PRInt32
andre@0: ** variable pointed to by found.
andre@0: **
andre@0: ** If more than count trace entries have entered the Trace
andre@0: ** Facility since the last call to PR_GetTraceEntries() 
andre@0: ** a lost data condition is returned. In this case, the most
andre@0: ** recent count trace entries are copied into buffer and found is
andre@0: ** set to count.
andre@0: ** 
andre@0: ** INPUTS:
andre@0: **  count. The number of trace entries to be copied into buffer.
andre@0: ** 
andre@0: ** 
andre@0: ** OUTPUTS:
andre@0: **  buffer. An array of PRTraceEntries. The buffer is supplied
andre@0: ** by the caller.
andre@0: ** 
andre@0: ** found: 32bit signed integer. The number of PRTraceEntries
andre@0: ** actually copied. found is always less than or equal to count.
andre@0: ** 
andre@0: ** RETURNS: 
andre@0: **  zero when there is no lost data.
andre@0: **  non-zero when some PRTraceEntries have been lost.
andre@0: ** 
andre@0: ** RESTRICTIONS:
andre@0: ** This is a real performance pig. The copy out operation is bad
andre@0: ** enough, but depending on then frequency of calls to the
andre@0: ** function, serious performance impact to the operating
andre@0: ** application may be realized. ... YMMV.
andre@0: ** 
andre@0: */
andre@0: #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
andre@0: #define PR_GET_TRACE_ENTRIES(buffer,count,found)\
andre@0:         PR_GetTraceEntries((buffer),(count),(found))
andre@0: #else
andre@0: #define PR_GET_TRACE_ENTRIES(buffer,count,found)
andre@0: #endif
andre@0: 
andre@0: NSPR_API(PRIntn)
andre@0:     PR_GetTraceEntries(
andre@0:         PRTraceEntry    *buffer,    /* where to write output */
andre@0:         PRInt32         count,      /* number to get */
andre@0:         PRInt32         *found      /* number you got */
andre@0: );
andre@0: 
andre@0: PR_END_EXTERN_C
andre@0: 
andre@0: #endif /* prtrace_h___ */
andre@0: