prtrace.h
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:23k
- /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
- /* ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
- *
- * 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 the Initial Developer are Copyright (C) 1998-2000
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
- *
- * ***** END LICENSE BLOCK ***** */
- #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;
- /*
- ** 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 );
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_INIT_TRACE_HANDLE(handle,value)
- (handle) = (PRCounterHandle)(value)
- #else
- #define PR_INIT_TRACE_HANDLE(handle,value)
- #endif
- /* -----------------------------------------------------------------------
- ** 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
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_CREATE_TRACE(handle,qName,rName,description)
- (handle) = PR_CreateTrace((qName),(rName),(description))
- #else
- #define PR_CREATE_TRACE(handle,qName,rName,description)
- #endif
- 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:
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_DESTROY_TRACE(handle)
- PR_DestroyTrace((handle))
- #else
- #define PR_DESTROY_TRACE(handle)
- #endif
- 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:
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)
- PR_Trace((handle),(ud0),(ud1),(ud2),(ud3),(ud4),(ud5),(ud6),(ud7))
- #else
- #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)
- #endif
- 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
- ** not currently suspended, the call has no effect.
- **
- ** PRTraceLockHandles: void. value must be NULL. Locks the
- ** trace handle lock. While the trace handle lock is held,
- ** calls to PR_CreateTrace() will block until the lock is
- ** released.
- **
- ** PRTraceUnlockHandles: void. value must be NULL. Unlocks the
- ** trace handle lock.
- **
- ** OUTPUTS:
- ** The operation of the Trace Facility may be changed.
- **
- ** RETURNS: void
- **
- ** RESTRICTIONS:
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_SET_TRACE_OPTION(command,value)
- PR_SetTraceOption((command),(value))
- #else
- #define PR_SET_TRACE_OPTION(command,value)
- #endif
- NSPR_API(void)
- PR_SetTraceOption(
- PRTraceOption command, /* One of the enumerated values */
- void *value /* command value or NULL */
- );
- /* -----------------------------------------------------------------------
- ** FUNCTION: PR_GetTraceOption() -- Retrieve settings from the Trace Facility
- **
- ** DESCRIPTION:
- ** PR_GetTraceOption() retrieves the current setting of the
- ** Trace Facility control depending on command.
- **
- **
- ** PRTraceBufSize: unsigned long: the size of the trace buffer,
- ** in bytes.
- **
- **
- ** INPUTS:
- ** command: one of the enumerated values in PRTraceOptions
- ** valid for PR_GetTraceOption().
- **
- ** OUTPUTS:
- ** dependent on command.
- **
- ** RETURNS: void
- **
- ** RESTRICTIONS:
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_GET_TRACE_OPTION(command,value)
- PR_GetTraceOption((command),(value))
- #else
- #define PR_GET_TRACE_OPTION(command,value)
- #endif
- NSPR_API(void)
- PR_GetTraceOption(
- PRTraceOption command, /* One of the enumerated values */
- void *value /* command value or NULL */
- );
- /* -----------------------------------------------------------------------
- ** FUNCTION: PR_GetTraceHandleFromName() -- Retrieve an existing
- ** handle by name.
- **
- ** DESCRIPTION:
- ** PR_GetTraceHandleFromName() retreives an existing tracehandle
- ** using the name specified by qName and rName.
- **
- ** INPUTS:
- ** qName: pointer to string. QName for this trace handle.
- **
- ** rName: pointer to string. RName for this trace handle.
- **
- **
- ** OUTPUTS: returned.
- **
- ** RETURNS:
- ** PRTraceHandle associated with qName and rName or NULL when
- ** there is no match.
- **
- ** RESTRICTIONS:
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)
- (handle) = PR_GetTraceHandleFromName((qName),(rName))
- #else
- #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)
- #endif
- NSPR_API(PRTraceHandle)
- PR_GetTraceHandleFromName(
- const char *qName, /* QName search argument */
- const char *rName /* RName search argument */
- );
- /* -----------------------------------------------------------------------
- ** FUNCTION: PR_GetTraceNameFromHandle() -- Retreive trace name
- ** by bandle.
- **
- ** DESCRIPTION:
- ** PR_GetTraceNameFromHandle() retreives the existing qName,
- ** rName, and description for the referenced trace handle.
- **
- ** INPUTS: handle: PRTraceHandle.
- **
- ** OUTPUTS: pointers to the Trace Facility's copy of qName,
- ** rName and description. ... Don't mess with these values.
- ** They're mine.
- **
- ** RETURNS: void
- **
- ** RESTRICTIONS:
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)
- PR_GetTraceNameFromHandle((handle),(qName),(rName),(description))
- #else
- #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)
- #endif
- NSPR_API(void)
- PR_GetTraceNameFromHandle(
- PRTraceHandle handle, /* handle as search argument */
- const char **qName, /* pointer to associated QName */
- const char **rName, /* pointer to associated RName */
- const char **description /* pointer to associated description */
- );
- /* -----------------------------------------------------------------------
- ** FUNCTION: PR_FindNextTraceQname() -- Retrieive a QName handle
- ** iterator.
- **
- ** DESCRIPTION:
- ** PR_FindNextTraceQname() retreives the first or next trace
- ** QName handle, depending on the value of handle, from the trace
- ** database. The PRTraceHandle returned can be used as an
- ** iterator to traverse the QName handles in the Trace database.
- **
- ** INPUTS:
- ** handle: When NULL, PR_FindNextQname() returns the first QName
- ** handle. When a handle is a valid PRTraceHandle previously
- ** retreived using PR_FindNextQname() the next QName handle is
- ** retreived.
- **
- ** OUTPUTS: returned.
- **
- ** RETURNS:
- ** PRTraceHandle or NULL when there are no trace handles.
- **
- ** RESTRICTIONS:
- ** Iterating thru the trace handles via FindFirst/FindNext
- ** should be done under protection of the trace handle lock.
- ** See: PR_SetTraceOption( PRLockTraceHandles ).
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_FIND_NEXT_TRACE_QNAME(next,handle)
- (next) = PR_FindNextTraceQname((handle))
- #else
- #define PR_FIND_NEXT_TRACE_QNAME(next,handle)
- #endif
- NSPR_API(PRTraceHandle)
- PR_FindNextTraceQname(
- PRTraceHandle handle
- );
- /* -----------------------------------------------------------------------
- ** FUNCTION: PR_FindNextTraceRname() -- Retrieive an RName handle
- ** iterator.
- **
- ** DESCRIPTION:
- ** PR_FindNextTraceRname() retreives the first or next trace
- ** RName handle, depending on the value of handle, from the trace
- ** database. The PRTraceHandle returned can be used as an
- ** iterator to traverse the RName handles in the Trace database.
- **
- ** INPUTS:
- ** rhandle: When NULL, PR_FindNextRname() returns the first
- ** RName handle. When a handle is a valid PRTraceHandle
- ** previously retreived using PR_FindNextRname() the next RName
- ** handle is retreived.
- ** qhandle: A valid PRTraceHandle retruned from a previous call
- ** to PR_FIND_NEXT_TRACE_QNAME().
- **
- ** OUTPUTS: returned.
- **
- ** RETURNS:
- ** PRTraceHandle or NULL when there are no trace handles.
- **
- ** RESTRICTIONS:
- ** Iterating thru the trace handles via FindNext should be done
- ** under protection of the trace handle lock. See: (
- ** PR_SetTraceOption( PRLockTraceHandles ).
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)
- (next) = PR_FindNextTraceRname((rhandle),(qhandle))
- #else
- #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)
- #endif
- NSPR_API(PRTraceHandle)
- PR_FindNextTraceRname(
- PRTraceHandle rhandle,
- PRTraceHandle qhandle
- );
- /* -----------------------------------------------------------------------
- ** FUNCTION: PR_RecordTraceEntries() -- Write trace entries to external media
- **
- ** DESCRIPTION:
- ** PR_RecordTraceEntries() causes entries in the in-memory trace
- ** buffer to be written to external media.
- **
- ** When PR_RecordTraceEntries() is called from an application
- ** thread, the function appears to block until another thread
- ** calls PR_SetTraceOption() with the PRTraceStopRecording
- ** option. This suggests that PR_RecordTraceEntries() should be
- ** called from a user supplied thread whose only job is to
- ** record trace entries.
- **
- ** The environment variable NSPR_TRACE_LOG controls the operation
- ** of this function. When NSPR_TRACE_LOG is not defined in the
- ** environment, no recording of trace entries occurs. When
- ** NSPR_TRACE_LOG is defined, the value of its definition must be
- ** the filename of the file to receive the trace entry buffer.
- **
- ** PR_RecordTraceEntries() attempts to record the in-memory
- ** buffer to a file, subject to the setting of the environment
- ** variable NSPR_TRACE_LOG. It is possible because of system
- ** load, the thread priority of the recording thread, number of
- ** active trace records being written over time, and other
- ** variables that some trace records can be lost. ... In other
- ** words: don't bet the farm on getting everything.
- **
- ** INPUTS: none
- **
- ** OUTPUTS: none
- **
- ** RETURNS: PR_STATUS
- ** PR_SUCCESS no errors were found.
- ** PR_FAILURE errors were found.
- **
- ** RESTRICTIONS:
- ** Only one thread can call PR_RecordTraceEntries() within a
- ** process.
- **
- ** On error, PR_RecordTraceEntries() may return prematurely.
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_RECORD_TRACE_ENTRIES()
- PR_RecordTraceEntries()
- #else
- #define PR_RECORD_TRACE_ENTRIES()
- #endif
-
- NSPR_API(void)
- PR_RecordTraceEntries(
- void
- );
- /* -----------------------------------------------------------------------
- ** FUNCTION: PR_GetTraceEntries() -- Retreive trace entries from
- ** the Trace Facility
- **
- ** DESCRIPTION:
- ** PR_GetTraceEntries() retreives trace entries from the Trace
- ** Facility. Up to count trace entries are copied from the Trace
- ** Facility into buffer. Only those trace entries that have not
- ** been copied via a previous call to PR_GetTraceEntries() are
- ** copied. The actual number copied is placed in the PRInt32
- ** variable pointed to by found.
- **
- ** If more than count trace entries have entered the Trace
- ** Facility since the last call to PR_GetTraceEntries()
- ** a lost data condition is returned. In this case, the most
- ** recent count trace entries are copied into buffer and found is
- ** set to count.
- **
- ** INPUTS:
- ** count. The number of trace entries to be copied into buffer.
- **
- **
- ** OUTPUTS:
- ** buffer. An array of PRTraceEntries. The buffer is supplied
- ** by the caller.
- **
- ** found: 32bit signed integer. The number of PRTraceEntries
- ** actually copied. found is always less than or equal to count.
- **
- ** RETURNS:
- ** zero when there is no lost data.
- ** non-zero when some PRTraceEntries have been lost.
- **
- ** RESTRICTIONS:
- ** This is a real performance pig. The copy out operation is bad
- ** enough, but depending on then frequency of calls to the
- ** function, serious performance impact to the operating
- ** application may be realized. ... YMMV.
- **
- */
- #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
- #define PR_GET_TRACE_ENTRIES(buffer,count,found)
- PR_GetTraceEntries((buffer),(count),(found))
- #else
- #define PR_GET_TRACE_ENTRIES(buffer,count,found)
- #endif
- NSPR_API(PRIntn)
- PR_GetTraceEntries(
- PRTraceEntry *buffer, /* where to write output */
- PRInt32 count, /* number to get */
- PRInt32 *found /* number you got */
- );
- PR_END_EXTERN_C
- #endif /* prtrace_h___ */