0
 ?÷     /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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/. */

#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

/* ---------------