prtrace.h

Netscape NSPR库源码

** 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:
** 
*/
#define PR_SET_TRACE_OPTION(command,value)\
    PR_SetTraceOption((command),(value))

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:
** 
*/
#define PR_GET_TRACE_OPTION(command,value)\
    PR_GetTraceOption((command),(value))

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:
** 
*/
#define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)\
    (handle) = PR_GetTraceHandleFromName((qName),(rName))

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:
** 
*/
#define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)\
    PR_GetTraceNameFromHandle((handle),(qName),(rName),(description))

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 ).
** 
*/
#define PR_FIND_NEXT_TRACE_QNAME(next,handle)\
    (next) = PR_FindNextTraceQname((handle))

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 ).
** 
*/
#define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)\
    (next) = PR_FindNextTraceRname((rhandle),(qhandle))

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.
** 
*/
#define PR_RECORD_TRACE_ENTRIES()\
	PR_RecordTraceEntries()
    
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.
** 
*/
#define PR_GET_TRACE_ENTRIES(buffer,count,found)\
        PR_GetTraceEntries((buffer),(count),(found))


NSPR_API(PRIntn)
    PR_GetTraceEntries(
        PRTraceEntry    *buffer,    /* where to write output */
        PRInt32         count,      /* number to get */
        PRInt32         *found      /* number you got */
);

#else /* !(defined (DEBUG) || defined (FORCE_NSPR_TRACE)) */
/*
** Define the Trace Facility macros as No-Ops for when the trace
** facility is to be compiled-out of the application.
**
*/
#define PR_DEFINE_TRACE(name) PRTraceHandle name
#define PR_INIT_TRACE_HANDLE(handle,value)
#define PR_CREATE_TRACE(handle,qName,rName,description)
#define PR_DESTROY_TRACE(handle)
#define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)
#define PR_SET_TRACE_OPTION(command,value)
#define PR_GET_TRACE_OPTION(command,value)
#define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)
#define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)
#define PR_FIND_NEXT_TRACE_QNAME(next,handle)
#define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)
#define PR_GET_TRACE_ENTRIES(buffer,count,found)
#define PR_RECORD_TRACE_ENTRIES()

#endif /* !(defined (DEBUG) || defined (FORCE_NSPR_TRACE)) */

PR_END_EXTERN_C

#endif /* prtrace_h___ */