1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prtrace.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,646 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef prtrace_h___
1.10 +#define prtrace_h___
1.11 +/*
1.12 +** prtrace.h -- NSPR's Trace Facility.
1.13 +**
1.14 +** The Trace Facility provides a means to trace application
1.15 +** program events within a process. When implementing an
1.16 +** application program an engineer may insert a "Trace" function
1.17 +** call, passing arguments to be traced. The "Trace" function
1.18 +** combines the user trace data with identifying data and
1.19 +** writes this data in time ordered sequence into a circular
1.20 +** in-memory buffer; when the buffer fills, it wraps.
1.21 +**
1.22 +** Functions are provided to set and/or re-configure the size of
1.23 +** the trace buffer, control what events are recorded in the
1.24 +** buffer, enable and disable tracing based on specific user
1.25 +** supplied data and other control functions. Methods are provided
1.26 +** to record the trace entries in the in-memory trace buffer to
1.27 +** a file.
1.28 +**
1.29 +** Tracing may cause a performance degredation to the application
1.30 +** depending on the number and placement of calls to the tracing
1.31 +** facility. When tracing is compiled in and all tracing is
1.32 +** disabled via the runtime controls, the overhead should be
1.33 +** minimal. ... Famous last words, eh?
1.34 +**
1.35 +** When DEBUG is defined at compile time, the Trace Facility is
1.36 +** compiled as part of NSPR and any application using NSPR's
1.37 +** header files will have tracing compiled in. When DEBUG is not
1.38 +** defined, the Trace Facility is not compiled into NSPR nor
1.39 +** exported in its header files. If the Trace Facility is
1.40 +** desired in a non-debug build, then FORCE_NSPR_TRACE may be
1.41 +** defined at compile time for both the optimized build of NSPR
1.42 +** and the application. NSPR and any application using NSPR's
1.43 +** Trace Facility must be compiled with the same level of trace
1.44 +** conditioning or unresolved references may be realized at link
1.45 +** time.
1.46 +**
1.47 +** For any of the Trace Facility methods that requires a trace
1.48 +** handle as an input argument, the caller must ensure that the
1.49 +** trace handle argument is valid. An invalid trace handle
1.50 +** argument may cause unpredictable results.
1.51 +**
1.52 +** Trace Facility methods are thread-safe and SMP safe.
1.53 +**
1.54 +** Users of the Trace Facility should use the defined macros to
1.55 +** invoke trace methods, not the function calls directly. e.g.
1.56 +** PR_TRACE( h1,0,1,2, ...); not PR_Trace(h1,0,1,2, ...);
1.57 +**
1.58 +** Application designers should be aware of the effects of
1.59 +** debug and optimized build differences when using result of the
1.60 +** Trace Facility macros in expressions.
1.61 +**
1.62 +** See Also: prcountr.h
1.63 +**
1.64 +** /lth. 08-Jun-1998.
1.65 +*/
1.66 +
1.67 +#include "prtypes.h"
1.68 +#include "prthread.h"
1.69 +#include "prtime.h"
1.70 +
1.71 +PR_BEGIN_EXTERN_C
1.72 +
1.73 +/*
1.74 +** Opaque type for the trace handle
1.75 +** ... Don't even think about looking in here.
1.76 +**
1.77 +*/
1.78 +typedef void * PRTraceHandle;
1.79 +
1.80 +/*
1.81 +** PRTraceEntry -- A trace entry in the in-memory trace buffer
1.82 +** looks like this.
1.83 +**
1.84 +*/
1.85 +typedef struct PRTraceEntry
1.86 +{
1.87 + PRThread *thread; /* The thread creating the trace entry */
1.88 + PRTraceHandle handle; /* PRTraceHandle creating the trace entry */
1.89 + PRTime time; /* Value of PR_Now() at time of trace entry */
1.90 + PRUint32 userData[8]; /* user supplied trace data */
1.91 +} PRTraceEntry;
1.92 +
1.93 +/*
1.94 +** PRTraceOption -- command operands to
1.95 +** PR_[Set|Get]TraceOption(). See descriptive meanings there.
1.96 +**
1.97 +*/
1.98 +typedef enum PRTraceOption
1.99 +{
1.100 + PRTraceBufSize,
1.101 + PRTraceEnable,
1.102 + PRTraceDisable,
1.103 + PRTraceSuspend,
1.104 + PRTraceResume,
1.105 + PRTraceSuspendRecording,
1.106 + PRTraceResumeRecording,
1.107 + PRTraceLockHandles,
1.108 + PRTraceUnLockHandles,
1.109 + PRTraceStopRecording
1.110 +} PRTraceOption;
1.111 +
1.112 +/* -----------------------------------------------------------------------
1.113 +** FUNCTION: PR_DEFINE_TRACE() -- Define a PRTraceHandle
1.114 +**
1.115 +** DESCRIPTION: PR_DEFINE_TRACE() is used to define a trace
1.116 +** handle.
1.117 +**
1.118 +*/
1.119 +#define PR_DEFINE_TRACE(name) PRTraceHandle name
1.120 +
1.121 +/* -----------------------------------------------------------------------
1.122 +** FUNCTION: PR_INIT_TRACE_HANDLE() -- Set the value of a PRTraceHandle
1.123 +**
1.124 +** DESCRIPTION:
1.125 +** PR_INIT_TRACE_HANDLE() sets the value of a PRTraceHandle
1.126 +** to value. e.g. PR_INIT_TRACE_HANDLE( myHandle, NULL );
1.127 +**
1.128 +*/
1.129 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.130 +#define PR_INIT_TRACE_HANDLE(handle,value)\
1.131 + (handle) = (PRCounterHandle)(value)
1.132 +#else
1.133 +#define PR_INIT_TRACE_HANDLE(handle,value)
1.134 +#endif
1.135 +
1.136 +
1.137 +/* -----------------------------------------------------------------------
1.138 +** FUNCTION: PR_CreateTrace() -- Create a trace handle
1.139 +**
1.140 +** DESCRIPTION:
1.141 +** PR_CreateTrace() creates a new trace handle. Tracing is
1.142 +** enabled for this handle when it is created. The trace handle
1.143 +** is intended for use in other Trace Facility calls.
1.144 +**
1.145 +** PR_CreateTrace() registers the QName, RName and description
1.146 +** data so that this data can be retrieved later.
1.147 +**
1.148 +** INPUTS:
1.149 +** qName: pointer to string. QName for this trace handle.
1.150 +**
1.151 +** rName: pointer to string. RName for this trace handle.
1.152 +**
1.153 +** description: pointer to string. Descriptive data about this
1.154 +** trace handle.
1.155 +**
1.156 +** OUTPUTS:
1.157 +** Creates the trace handle.
1.158 +** Registers the QName and RName with the trace facility.
1.159 +**
1.160 +** RETURNS:
1.161 +** PRTraceHandle
1.162 +**
1.163 +** RESTRICTIONS:
1.164 +** qName is limited to 31 characters.
1.165 +** rName is limited to 31 characters.
1.166 +** description is limited to 255 characters.
1.167 +**
1.168 +*/
1.169 +#define PRTRACE_NAME_MAX 31
1.170 +#define PRTRACE_DESC_MAX 255
1.171 +
1.172 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.173 +#define PR_CREATE_TRACE(handle,qName,rName,description)\
1.174 + (handle) = PR_CreateTrace((qName),(rName),(description))
1.175 +#else
1.176 +#define PR_CREATE_TRACE(handle,qName,rName,description)
1.177 +#endif
1.178 +
1.179 +NSPR_API(PRTraceHandle)
1.180 + PR_CreateTrace(
1.181 + const char *qName, /* QName for this trace handle */
1.182 + const char *rName, /* RName for this trace handle */
1.183 + const char *description /* description for this trace handle */
1.184 +);
1.185 +
1.186 +
1.187 +/* -----------------------------------------------------------------------
1.188 +** FUNCTION: PR_DestroyTrace() -- Destroy a trace handle
1.189 +**
1.190 +** DESCRIPTION:
1.191 +** PR_DestroyTrace() removes the referenced trace handle and
1.192 +** associated QName, RName and description data from the Trace
1.193 +** Facility.
1.194 +**
1.195 +** INPUTS: handle. A PRTraceHandle
1.196 +**
1.197 +** OUTPUTS:
1.198 +** The trace handle is unregistered.
1.199 +** The QName, RName and description are removed.
1.200 +**
1.201 +** RETURNS: void
1.202 +**
1.203 +** RESTRICTIONS:
1.204 +**
1.205 +*/
1.206 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.207 +#define PR_DESTROY_TRACE(handle)\
1.208 + PR_DestroyTrace((handle))
1.209 +#else
1.210 +#define PR_DESTROY_TRACE(handle)
1.211 +#endif
1.212 +
1.213 +NSPR_API(void)
1.214 + PR_DestroyTrace(
1.215 + PRTraceHandle handle /* Handle to be destroyed */
1.216 +);
1.217 +
1.218 +
1.219 +/* -----------------------------------------------------------------------
1.220 +** FUNCTION: PR_Trace() -- Make a trace entry in the in-memory trace
1.221 +**
1.222 +** DESCRIPTION:
1.223 +** PR_Trace() makes an entry in the in-memory trace buffer for
1.224 +** the referenced trace handle. The next logically available
1.225 +** PRTraceEntry is used; when the next trace entry would overflow
1.226 +** the trace table, the table wraps.
1.227 +**
1.228 +** PR_Trace() for a specific trace handle may be disabled by
1.229 +** calling PR_SetTraceOption() specifying PRTraceDisable for the
1.230 +** trace handle to be disabled.
1.231 +**
1.232 +** INPUTS:
1.233 +** handle: PRTraceHandle. The trace handle for this trace.
1.234 +**
1.235 +** userData[0..7]: unsigned 32bit integers. user supplied data
1.236 +** that is copied into the PRTraceEntry
1.237 +**
1.238 +** OUTPUTS:
1.239 +** A PRTraceEntry is (conditionally) formatted in the in-memory
1.240 +** trace buffer.
1.241 +**
1.242 +** RETURNS: void.
1.243 +**
1.244 +** RESTRICTIONS:
1.245 +**
1.246 +*/
1.247 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.248 +#define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)\
1.249 + PR_Trace((handle),(ud0),(ud1),(ud2),(ud3),(ud4),(ud5),(ud6),(ud7))
1.250 +#else
1.251 +#define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)
1.252 +#endif
1.253 +
1.254 +NSPR_API(void)
1.255 + PR_Trace(
1.256 + PRTraceHandle handle, /* use this trace handle */
1.257 + PRUint32 userData0, /* User supplied data word 0 */
1.258 + PRUint32 userData1, /* User supplied data word 1 */
1.259 + PRUint32 userData2, /* User supplied data word 2 */
1.260 + PRUint32 userData3, /* User supplied data word 3 */
1.261 + PRUint32 userData4, /* User supplied data word 4 */
1.262 + PRUint32 userData5, /* User supplied data word 5 */
1.263 + PRUint32 userData6, /* User supplied data word 6 */
1.264 + PRUint32 userData7 /* User supplied data word 7 */
1.265 +);
1.266 +
1.267 +/* -----------------------------------------------------------------------
1.268 +** FUNCTION: PR_SetTraceOption() -- Control the Trace Facility
1.269 +**
1.270 +** DESCRIPTION:
1.271 +** PR_SetTraceOption() controls the Trace Facility. Depending on
1.272 +** command and value, attributes of the Trace Facility may be
1.273 +** changed.
1.274 +**
1.275 +** INPUTS:
1.276 +** command: An enumerated value in the set of PRTraceOption.
1.277 +** value: pointer to the data to be set. Type of the data is
1.278 +** dependent on command; for each value of command, the type
1.279 +** and meaning of dereferenced value is shown.
1.280 +**
1.281 +** PRTraceBufSize: unsigned long: the size of the trace buffer,
1.282 +** in bytes.
1.283 +**
1.284 +** PRTraceEnable: PRTraceHandle. The trace handle to be
1.285 +** enabled.
1.286 +**
1.287 +** PRTraceDisable: PRTraceHandle. The trace handle to be
1.288 +** disabled.
1.289 +**
1.290 +** PRTraceSuspend: void. value must be NULL. All tracing is
1.291 +** suspended.
1.292 +**
1.293 +** PRTraceResume: void. value must be NULL. Tracing for all
1.294 +** previously enabled, prior to a PRTraceSuspend, is resumed.
1.295 +**
1.296 +** PRTraceStopRecording: void. value must be NULL. If recording
1.297 +** (see: ** PR_RecordTraceEntries()) is being done,
1.298 +** PRTraceStopRecording causes PR_RecordTraceEntries() to return
1.299 +** to its caller. If recording is not being done, this function
1.300 +** has no effect.
1.301 +**
1.302 +** PRTraceSuspendRecording: void. Must be NULL. If recording is
1.303 +** being done, PRTraceSuspendRecording causes further writes to
1.304 +** the trace file to be suspended. Data in the in-memory
1.305 +** trace buffer that would ordinarily be written to the
1.306 +** trace file will not be written. Trace entries will continue
1.307 +** to be entered in the in-memory buffer. If the Trace Facility
1.308 +** recording is already in a suspended state, the call has no
1.309 +** effect.
1.310 +**
1.311 +** PRTraceResumeRecording: void. value must be NULL. If
1.312 +** recording for the Trace Facility has been previously been
1.313 +** suspended, this causes recording to resume. Recording resumes
1.314 +** with the next in-memory buffer segment that would be written
1.315 +** if trace recording had not been suspended. If recording is
1.316 +** not currently suspended, the call has no effect.
1.317 +**
1.318 +** PRTraceLockHandles: void. value must be NULL. Locks the
1.319 +** trace handle lock. While the trace handle lock is held,
1.320 +** calls to PR_CreateTrace() will block until the lock is
1.321 +** released.
1.322 +**
1.323 +** PRTraceUnlockHandles: void. value must be NULL. Unlocks the
1.324 +** trace handle lock.
1.325 +**
1.326 +** OUTPUTS:
1.327 +** The operation of the Trace Facility may be changed.
1.328 +**
1.329 +** RETURNS: void
1.330 +**
1.331 +** RESTRICTIONS:
1.332 +**
1.333 +*/
1.334 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.335 +#define PR_SET_TRACE_OPTION(command,value)\
1.336 + PR_SetTraceOption((command),(value))
1.337 +#else
1.338 +#define PR_SET_TRACE_OPTION(command,value)
1.339 +#endif
1.340 +
1.341 +NSPR_API(void)
1.342 + PR_SetTraceOption(
1.343 + PRTraceOption command, /* One of the enumerated values */
1.344 + void *value /* command value or NULL */
1.345 +);
1.346 +
1.347 +
1.348 +/* -----------------------------------------------------------------------
1.349 +** FUNCTION: PR_GetTraceOption() -- Retrieve settings from the Trace Facility
1.350 +**
1.351 +** DESCRIPTION:
1.352 +** PR_GetTraceOption() retrieves the current setting of the
1.353 +** Trace Facility control depending on command.
1.354 +**
1.355 +**
1.356 +** PRTraceBufSize: unsigned long: the size of the trace buffer,
1.357 +** in bytes.
1.358 +**
1.359 +**
1.360 +** INPUTS:
1.361 +** command: one of the enumerated values in PRTraceOptions
1.362 +** valid for PR_GetTraceOption().
1.363 +**
1.364 +** OUTPUTS:
1.365 +** dependent on command.
1.366 +**
1.367 +** RETURNS: void
1.368 +**
1.369 +** RESTRICTIONS:
1.370 +**
1.371 +*/
1.372 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.373 +#define PR_GET_TRACE_OPTION(command,value)\
1.374 + PR_GetTraceOption((command),(value))
1.375 +#else
1.376 +#define PR_GET_TRACE_OPTION(command,value)
1.377 +#endif
1.378 +
1.379 +NSPR_API(void)
1.380 + PR_GetTraceOption(
1.381 + PRTraceOption command, /* One of the enumerated values */
1.382 + void *value /* command value or NULL */
1.383 +);
1.384 +
1.385 +/* -----------------------------------------------------------------------
1.386 +** FUNCTION: PR_GetTraceHandleFromName() -- Retrieve an existing
1.387 +** handle by name.
1.388 +**
1.389 +** DESCRIPTION:
1.390 +** PR_GetTraceHandleFromName() retreives an existing tracehandle
1.391 +** using the name specified by qName and rName.
1.392 +**
1.393 +** INPUTS:
1.394 +** qName: pointer to string. QName for this trace handle.
1.395 +**
1.396 +** rName: pointer to string. RName for this trace handle.
1.397 +**
1.398 +**
1.399 +** OUTPUTS: returned.
1.400 +**
1.401 +** RETURNS:
1.402 +** PRTraceHandle associated with qName and rName or NULL when
1.403 +** there is no match.
1.404 +**
1.405 +** RESTRICTIONS:
1.406 +**
1.407 +*/
1.408 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.409 +#define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)\
1.410 + (handle) = PR_GetTraceHandleFromName((qName),(rName))
1.411 +#else
1.412 +#define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)
1.413 +#endif
1.414 +
1.415 +NSPR_API(PRTraceHandle)
1.416 + PR_GetTraceHandleFromName(
1.417 + const char *qName, /* QName search argument */
1.418 + const char *rName /* RName search argument */
1.419 +);
1.420 +
1.421 +/* -----------------------------------------------------------------------
1.422 +** FUNCTION: PR_GetTraceNameFromHandle() -- Retreive trace name
1.423 +** by bandle.
1.424 +**
1.425 +** DESCRIPTION:
1.426 +** PR_GetTraceNameFromHandle() retreives the existing qName,
1.427 +** rName, and description for the referenced trace handle.
1.428 +**
1.429 +** INPUTS: handle: PRTraceHandle.
1.430 +**
1.431 +** OUTPUTS: pointers to the Trace Facility's copy of qName,
1.432 +** rName and description. ... Don't mess with these values.
1.433 +** They're mine.
1.434 +**
1.435 +** RETURNS: void
1.436 +**
1.437 +** RESTRICTIONS:
1.438 +**
1.439 +*/
1.440 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.441 +#define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)\
1.442 + PR_GetTraceNameFromHandle((handle),(qName),(rName),(description))
1.443 +#else
1.444 +#define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)
1.445 +#endif
1.446 +
1.447 +NSPR_API(void)
1.448 + PR_GetTraceNameFromHandle(
1.449 + PRTraceHandle handle, /* handle as search argument */
1.450 + const char **qName, /* pointer to associated QName */
1.451 + const char **rName, /* pointer to associated RName */
1.452 + const char **description /* pointer to associated description */
1.453 +);
1.454 +
1.455 +/* -----------------------------------------------------------------------
1.456 +** FUNCTION: PR_FindNextTraceQname() -- Retrieive a QName handle
1.457 +** iterator.
1.458 +**
1.459 +** DESCRIPTION:
1.460 +** PR_FindNextTraceQname() retreives the first or next trace
1.461 +** QName handle, depending on the value of handle, from the trace
1.462 +** database. The PRTraceHandle returned can be used as an
1.463 +** iterator to traverse the QName handles in the Trace database.
1.464 +**
1.465 +** INPUTS:
1.466 +** handle: When NULL, PR_FindNextQname() returns the first QName
1.467 +** handle. When a handle is a valid PRTraceHandle previously
1.468 +** retreived using PR_FindNextQname() the next QName handle is
1.469 +** retreived.
1.470 +**
1.471 +** OUTPUTS: returned.
1.472 +**
1.473 +** RETURNS:
1.474 +** PRTraceHandle or NULL when there are no trace handles.
1.475 +**
1.476 +** RESTRICTIONS:
1.477 +** Iterating thru the trace handles via FindFirst/FindNext
1.478 +** should be done under protection of the trace handle lock.
1.479 +** See: PR_SetTraceOption( PRLockTraceHandles ).
1.480 +**
1.481 +*/
1.482 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.483 +#define PR_FIND_NEXT_TRACE_QNAME(next,handle)\
1.484 + (next) = PR_FindNextTraceQname((handle))
1.485 +#else
1.486 +#define PR_FIND_NEXT_TRACE_QNAME(next,handle)
1.487 +#endif
1.488 +
1.489 +NSPR_API(PRTraceHandle)
1.490 + PR_FindNextTraceQname(
1.491 + PRTraceHandle handle
1.492 +);
1.493 +
1.494 +
1.495 +/* -----------------------------------------------------------------------
1.496 +** FUNCTION: PR_FindNextTraceRname() -- Retrieive an RName handle
1.497 +** iterator.
1.498 +**
1.499 +** DESCRIPTION:
1.500 +** PR_FindNextTraceRname() retreives the first or next trace
1.501 +** RName handle, depending on the value of handle, from the trace
1.502 +** database. The PRTraceHandle returned can be used as an
1.503 +** iterator to traverse the RName handles in the Trace database.
1.504 +**
1.505 +** INPUTS:
1.506 +** rhandle: When NULL, PR_FindNextRname() returns the first
1.507 +** RName handle. When a handle is a valid PRTraceHandle
1.508 +** previously retreived using PR_FindNextRname() the next RName
1.509 +** handle is retreived.
1.510 +** qhandle: A valid PRTraceHandle retruned from a previous call
1.511 +** to PR_FIND_NEXT_TRACE_QNAME().
1.512 +**
1.513 +** OUTPUTS: returned.
1.514 +**
1.515 +** RETURNS:
1.516 +** PRTraceHandle or NULL when there are no trace handles.
1.517 +**
1.518 +** RESTRICTIONS:
1.519 +** Iterating thru the trace handles via FindNext should be done
1.520 +** under protection of the trace handle lock. See: (
1.521 +** PR_SetTraceOption( PRLockTraceHandles ).
1.522 +**
1.523 +*/
1.524 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.525 +#define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)\
1.526 + (next) = PR_FindNextTraceRname((rhandle),(qhandle))
1.527 +#else
1.528 +#define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)
1.529 +#endif
1.530 +
1.531 +NSPR_API(PRTraceHandle)
1.532 + PR_FindNextTraceRname(
1.533 + PRTraceHandle rhandle,
1.534 + PRTraceHandle qhandle
1.535 +);
1.536 +
1.537 +/* -----------------------------------------------------------------------
1.538 +** FUNCTION: PR_RecordTraceEntries() -- Write trace entries to external media
1.539 +**
1.540 +** DESCRIPTION:
1.541 +** PR_RecordTraceEntries() causes entries in the in-memory trace
1.542 +** buffer to be written to external media.
1.543 +**
1.544 +** When PR_RecordTraceEntries() is called from an application
1.545 +** thread, the function appears to block until another thread
1.546 +** calls PR_SetTraceOption() with the PRTraceStopRecording
1.547 +** option. This suggests that PR_RecordTraceEntries() should be
1.548 +** called from a user supplied thread whose only job is to
1.549 +** record trace entries.
1.550 +**
1.551 +** The environment variable NSPR_TRACE_LOG controls the operation
1.552 +** of this function. When NSPR_TRACE_LOG is not defined in the
1.553 +** environment, no recording of trace entries occurs. When
1.554 +** NSPR_TRACE_LOG is defined, the value of its definition must be
1.555 +** the filename of the file to receive the trace entry buffer.
1.556 +**
1.557 +** PR_RecordTraceEntries() attempts to record the in-memory
1.558 +** buffer to a file, subject to the setting of the environment
1.559 +** variable NSPR_TRACE_LOG. It is possible because of system
1.560 +** load, the thread priority of the recording thread, number of
1.561 +** active trace records being written over time, and other
1.562 +** variables that some trace records can be lost. ... In other
1.563 +** words: don't bet the farm on getting everything.
1.564 +**
1.565 +** INPUTS: none
1.566 +**
1.567 +** OUTPUTS: none
1.568 +**
1.569 +** RETURNS: PR_STATUS
1.570 +** PR_SUCCESS no errors were found.
1.571 +** PR_FAILURE errors were found.
1.572 +**
1.573 +** RESTRICTIONS:
1.574 +** Only one thread can call PR_RecordTraceEntries() within a
1.575 +** process.
1.576 +**
1.577 +** On error, PR_RecordTraceEntries() may return prematurely.
1.578 +**
1.579 +*/
1.580 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.581 +#define PR_RECORD_TRACE_ENTRIES()\
1.582 + PR_RecordTraceEntries()
1.583 +#else
1.584 +#define PR_RECORD_TRACE_ENTRIES()
1.585 +#endif
1.586 +
1.587 +NSPR_API(void)
1.588 + PR_RecordTraceEntries(
1.589 + void
1.590 +);
1.591 +
1.592 +/* -----------------------------------------------------------------------
1.593 +** FUNCTION: PR_GetTraceEntries() -- Retreive trace entries from
1.594 +** the Trace Facility
1.595 +**
1.596 +** DESCRIPTION:
1.597 +** PR_GetTraceEntries() retreives trace entries from the Trace
1.598 +** Facility. Up to count trace entries are copied from the Trace
1.599 +** Facility into buffer. Only those trace entries that have not
1.600 +** been copied via a previous call to PR_GetTraceEntries() are
1.601 +** copied. The actual number copied is placed in the PRInt32
1.602 +** variable pointed to by found.
1.603 +**
1.604 +** If more than count trace entries have entered the Trace
1.605 +** Facility since the last call to PR_GetTraceEntries()
1.606 +** a lost data condition is returned. In this case, the most
1.607 +** recent count trace entries are copied into buffer and found is
1.608 +** set to count.
1.609 +**
1.610 +** INPUTS:
1.611 +** count. The number of trace entries to be copied into buffer.
1.612 +**
1.613 +**
1.614 +** OUTPUTS:
1.615 +** buffer. An array of PRTraceEntries. The buffer is supplied
1.616 +** by the caller.
1.617 +**
1.618 +** found: 32bit signed integer. The number of PRTraceEntries
1.619 +** actually copied. found is always less than or equal to count.
1.620 +**
1.621 +** RETURNS:
1.622 +** zero when there is no lost data.
1.623 +** non-zero when some PRTraceEntries have been lost.
1.624 +**
1.625 +** RESTRICTIONS:
1.626 +** This is a real performance pig. The copy out operation is bad
1.627 +** enough, but depending on then frequency of calls to the
1.628 +** function, serious performance impact to the operating
1.629 +** application may be realized. ... YMMV.
1.630 +**
1.631 +*/
1.632 +#if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
1.633 +#define PR_GET_TRACE_ENTRIES(buffer,count,found)\
1.634 + PR_GetTraceEntries((buffer),(count),(found))
1.635 +#else
1.636 +#define PR_GET_TRACE_ENTRIES(buffer,count,found)
1.637 +#endif
1.638 +
1.639 +NSPR_API(PRIntn)
1.640 + PR_GetTraceEntries(
1.641 + PRTraceEntry *buffer, /* where to write output */
1.642 + PRInt32 count, /* number to get */
1.643 + PRInt32 *found /* number you got */
1.644 +);
1.645 +
1.646 +PR_END_EXTERN_C
1.647 +
1.648 +#endif /* prtrace_h___ */
1.649 +
