mozilla/nsprpub/pr/include/prtrace.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is the Netscape Portable Runtime (NSPR).
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998-2000
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef prtrace_h___
  39 #define prtrace_h___
  40 /*
  41 ** prtrace.h -- NSPR's Trace Facility.
  42 **
  43 ** The Trace Facility provides a means to trace application
  44 ** program events within a process. When implementing an
  45 ** application program an engineer may insert a "Trace" function
  46 ** call, passing arguments to be traced. The "Trace" function
  47 ** combines the user trace data with identifying data and
  48 ** writes this data in time ordered sequence into a circular
  49 ** in-memory buffer; when the buffer fills, it wraps.
  50 **
  51 ** Functions are provided to set and/or re-configure the size of
  52 ** the trace buffer, control what events are recorded in the
  53 ** buffer, enable and disable tracing based on specific user
  54 ** supplied data and other control functions. Methods are provided
  55 ** to record the trace entries in the in-memory trace buffer to
  56 ** a file.
  57 **
  58 ** Tracing may cause a performance degredation to the application
  59 ** depending on the number and placement of calls to the tracing
  60 ** facility. When tracing is compiled in and all tracing is
  61 ** disabled via the runtime controls, the overhead should be
  62 ** minimal. ... Famous last words, eh?
  63 **
  64 ** When DEBUG is defined at compile time, the Trace Facility is
  65 ** compiled as part of NSPR and any application using NSPR's
  66 ** header files will have tracing compiled in. When DEBUG is not
  67 ** defined, the Trace Facility is not compiled into NSPR nor
  68 ** exported in its header files.  If the Trace Facility is
  69 ** desired in a non-debug build, then FORCE_NSPR_TRACE may be
  70 ** defined at compile time for both the optimized build of NSPR
  71 ** and the application. NSPR and any application using  NSPR's
  72 ** Trace Facility must be compiled with the same level of trace
  73 ** conditioning or unresolved references may be realized at link
  74 ** time.
  75 **
  76 ** For any of the Trace Facility methods that requires a trace
  77 ** handle as an input argument, the caller must ensure that the
  78 ** trace handle argument is valid. An invalid trace handle
  79 ** argument may cause unpredictable results.
  80 **
  81 ** Trace Facility methods are thread-safe and SMP safe.
  82 **
  83 ** Users of the Trace Facility should use the defined macros to
  84 ** invoke trace methods, not the function calls directly. e.g.
  85 ** PR_TRACE( h1,0,1,2, ...); not PR_Trace(h1,0,1,2, ...);
  86 **
  87 ** Application designers should be aware of the effects of
  88 ** debug and optimized build differences when using result of the
  89 ** Trace Facility macros in expressions.
  90 **
  91 ** See Also: prcountr.h
  92 **
  93 ** /lth. 08-Jun-1998.
  94 */
  95
  96 #include "prtypes.h"
  97 #include "prthread.h"
  98 #include "prtime.h"
  99
 100 PR_BEGIN_EXTERN_C
 101
 102 /*
 103 ** Opaque type for the trace handle
 104 ** ... Don't even think about looking in here.
 105 **
 106 */
 107 typedef void *  PRTraceHandle;
 108
 109 /*
 110 ** PRTraceEntry -- A trace entry in the in-memory trace buffer
 111 ** looks like this.
 112 **
 113 */
 114 typedef struct PRTraceEntry
 115 {
 116     PRThread        *thread;        /* The thread creating the trace entry */
 117     PRTraceHandle   handle;         /* PRTraceHandle creating the trace entry */
 118     PRTime          time;           /* Value of PR_Now() at time of trace entry */
 119     PRUint32        userData[8];    /* user supplied trace data */
 120 } PRTraceEntry;
 121
 122 /*
 123 ** PRTraceOption -- command operands to
 124 ** PR_[Set|Get]TraceOption(). See descriptive meanings there.
 125 **
 126 */
 127 typedef enum PRTraceOption
 128 {
 129     PRTraceBufSize,
 130     PRTraceEnable,
 131     PRTraceDisable,
 132     PRTraceSuspend,
 133     PRTraceResume,
 134     PRTraceSuspendRecording,
 135     PRTraceResumeRecording,
 136     PRTraceLockHandles,
 137     PRTraceUnLockHandles,
 138     PRTraceStopRecording
 139 } PRTraceOption;
 140
 141 /* -----------------------------------------------------------------------
 142 ** FUNCTION: PR_DEFINE_TRACE() -- Define a PRTraceHandle
 143 **
 144 ** DESCRIPTION: PR_DEFINE_TRACE() is used to define a trace
 145 ** handle.
 146 **
 147 */
 148 #define PR_DEFINE_TRACE(name) PRTraceHandle name
 149
 150 /* -----------------------------------------------------------------------
 151 ** FUNCTION: PR_INIT_TRACE_HANDLE() -- Set the value of a PRTraceHandle
 152 **
 153 ** DESCRIPTION:
 154 ** PR_INIT_TRACE_HANDLE() sets the value of a PRTraceHandle
 155 ** to value. e.g. PR_INIT_TRACE_HANDLE( myHandle, NULL );
 156 **
 157 */
 158 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 159 #define PR_INIT_TRACE_HANDLE(handle,value)\
 160     (handle) = (PRCounterHandle)(value)
 161 #else
 162 #define PR_INIT_TRACE_HANDLE(handle,value)
 163 #endif
 164
 165
 166 /* -----------------------------------------------------------------------
 167 ** FUNCTION: PR_CreateTrace() -- Create a trace handle
 168 **
 169 ** DESCRIPTION:
 170 **  PR_CreateTrace() creates a new trace handle. Tracing is
 171 **  enabled for this handle when it is created. The trace handle
 172 **  is intended for use in other Trace Facility calls.
 173 **
 174 **  PR_CreateTrace() registers the QName, RName and description
 175 **  data so that this data can be retrieved later.
 176 **
 177 ** INPUTS:
 178 **  qName: pointer to string. QName for this trace handle.
 179 **
 180 **  rName: pointer to string. RName for this trace handle.
 181 **
 182 **  description: pointer to string. Descriptive data about this
 183 **  trace handle.
 184 **
 185 ** OUTPUTS:
 186 **  Creates the trace handle.
 187 **  Registers the QName and RName with the trace facility.
 188 **
 189 ** RETURNS:
 190 **  PRTraceHandle
 191 **
 192 ** RESTRICTIONS:
 193 **  qName is limited to 31 characters.
 194 **  rName is limited to 31 characters.
 195 **  description is limited to 255 characters.
 196 **
 197 */
 198 #define PRTRACE_NAME_MAX 31
 199 #define PRTRACE_DESC_MAX 255
 200
 201 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 202 #define PR_CREATE_TRACE(handle,qName,rName,description)\
 203     (handle) = PR_CreateTrace((qName),(rName),(description))
 204 #else
 205 #define PR_CREATE_TRACE(handle,qName,rName,description)
 206 #endif
 207
 208 NSPR_API(PRTraceHandle)
 209         PR_CreateTrace(
 210         const char *qName,          /* QName for this trace handle */
 211             const char *rName,          /* RName for this trace handle */
 212             const char *description     /* description for this trace handle */
 213 );
 214
 215
 216 /* -----------------------------------------------------------------------
 217 ** FUNCTION: PR_DestroyTrace() -- Destroy a trace handle
 218 **
 219 ** DESCRIPTION:
 220 **  PR_DestroyTrace() removes the referenced trace handle and
 221 ** associated QName, RName and description data from the Trace
 222 ** Facility.
 223 **
 224 ** INPUTS: handle. A PRTraceHandle
 225 **
 226 ** OUTPUTS:
 227 **  The trace handle is unregistered.
 228 **  The QName, RName and description are removed.
 229 **
 230 ** RETURNS: void
 231 **
 232 ** RESTRICTIONS:
 233 **
 234 */
 235 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 236 #define PR_DESTROY_TRACE(handle)\
 237     PR_DestroyTrace((handle))
 238 #else
 239 #define PR_DESTROY_TRACE(handle)
 240 #endif
 241
 242 NSPR_API(void)
 243         PR_DestroyTrace(
 244                 PRTraceHandle handle    /* Handle to be destroyed */
 245 );
 246
 247
 248 /* -----------------------------------------------------------------------
 249 ** FUNCTION: PR_Trace() -- Make a trace entry in the in-memory trace
 250 **
 251 ** DESCRIPTION:
 252 ** PR_Trace() makes an entry in the in-memory trace buffer for
 253 ** the referenced trace handle. The next logically available
 254 ** PRTraceEntry is used; when the next trace entry would overflow
 255 ** the trace table, the table wraps.
 256 **
 257 ** PR_Trace() for a specific trace handle may be disabled by
 258 ** calling PR_SetTraceOption() specifying PRTraceDisable for the
 259 ** trace handle to be disabled.
 260 **
 261 ** INPUTS:
 262 ** handle: PRTraceHandle. The trace handle for this trace.
 263 **
 264 ** userData[0..7]: unsigned 32bit integers. user supplied data
 265 ** that is copied into the PRTraceEntry
 266 **
 267 ** OUTPUTS:
 268 **  A PRTraceEntry is (conditionally) formatted in the in-memory
 269 ** trace buffer.
 270 **
 271 ** RETURNS: void.
 272 **
 273 ** RESTRICTIONS:
 274 **
 275 */
 276 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 277 #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)\
 278     PR_Trace((handle),(ud0),(ud1),(ud2),(ud3),(ud4),(ud5),(ud6),(ud7))
 279 #else
 280 #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)
 281 #endif
 282
 283 NSPR_API(void)
 284         PR_Trace(
 285         PRTraceHandle handle,       /* use this trace handle */
 286             PRUint32    userData0,      /* User supplied data word 0 */
 287             PRUint32    userData1,      /* User supplied data word 1 */
 288             PRUint32    userData2,      /* User supplied data word 2 */
 289             PRUint32    userData3,      /* User supplied data word 3 */
 290             PRUint32    userData4,      /* User supplied data word 4 */
 291             PRUint32    userData5,      /* User supplied data word 5 */
 292             PRUint32    userData6,      /* User supplied data word 6 */
 293             PRUint32    userData7       /* User supplied data word 7 */
 294 );
 295
 296 /* -----------------------------------------------------------------------
 297 ** FUNCTION: PR_SetTraceOption() -- Control the Trace Facility
 298 **
 299 ** DESCRIPTION:
 300 ** PR_SetTraceOption() controls the Trace Facility. Depending on
 301 ** command and value, attributes of the Trace Facility may be
 302 ** changed.
 303 **
 304 ** INPUTS:
 305 **  command: An enumerated value in the set of PRTraceOption.
 306 **  value: pointer to the data to be set. Type of the data is
 307 **  dependent on command; for each value of command, the type
 308 **  and meaning of dereferenced value is shown.
 309 **
 310 **  PRTraceBufSize: unsigned long: the size of the trace buffer,
 311 ** in bytes.
 312 **
 313 **  PRTraceEnable: PRTraceHandle. The trace handle to be
 314 ** enabled.
 315 **
 316 **  PRTraceDisable: PRTraceHandle. The trace handle to be
 317 ** disabled.
 318 **
 319 **  PRTraceSuspend: void. value must be NULL. All tracing is
 320 ** suspended.
 321 **
 322 **  PRTraceResume: void. value must be NULL. Tracing for all
 323 ** previously enabled, prior to a PRTraceSuspend, is resumed.
 324 **
 325 **  PRTraceStopRecording: void. value must be NULL. If recording
 326 ** (see: ** PR_RecordTraceEntries()) is being done,
 327 ** PRTraceStopRecording causes PR_RecordTraceEntries() to return
 328 ** to its caller. If recording is not being done, this function
 329 ** has no effect.
 330 **
 331 **  PRTraceSuspendRecording: void. Must be NULL. If recording is
 332 ** being done, PRTraceSuspendRecording causes further writes to
 333 ** the trace file to be suspended. Data in the in-memory
 334 ** trace buffer that would ordinarily be written to the
 335 ** trace file will not be written. Trace entries will continue
 336 ** to be entered in the in-memory buffer. If the Trace Facility
 337 ** recording is already in a suspended state, the call has no
 338 ** effect.
 339 **
 340 **  PRTraceResumeRecording: void. value must be NULL. If
 341 ** recording for the Trace Facility has been previously been
 342 ** suspended, this causes recording to resume. Recording resumes
 343 ** with the next in-memory buffer segment that would be written
 344 ** if trace recording had not been suspended. If recording is
 345 ** not currently suspended, the call has no effect.
 346 **
 347 **  PRTraceLockHandles: void. value must be NULL. Locks the
 348 ** trace handle lock. While the trace handle lock is held,
 349 ** calls to PR_CreateTrace() will block until the lock is
 350 ** released.
 351 **
 352 **  PRTraceUnlockHandles: void. value must be NULL. Unlocks the
 353 ** trace handle lock.
 354 **
 355 ** OUTPUTS:
 356 **  The operation of the Trace Facility may be changed.
 357 **
 358 ** RETURNS: void
 359 **
 360 ** RESTRICTIONS:
 361 **
 362 */
 363 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 364 #define PR_SET_TRACE_OPTION(command,value)\
 365     PR_SetTraceOption((command),(value))
 366 #else
 367 #define PR_SET_TRACE_OPTION(command,value)
 368 #endif
 369
 370 NSPR_API(void)
 371         PR_SetTraceOption(
 372             PRTraceOption command,  /* One of the enumerated values */
 373             void *value             /* command value or NULL */
 374 );
 375
 376
 377 /* -----------------------------------------------------------------------
 378 ** FUNCTION: PR_GetTraceOption() -- Retrieve settings from the Trace Facility
 379 **
 380 ** DESCRIPTION:
 381 ** PR_GetTraceOption() retrieves the current setting of the
 382 ** Trace Facility control depending on command.
 383 **
 384 **
 385 **  PRTraceBufSize: unsigned long: the size of the trace buffer,
 386 ** in bytes.
 387 **
 388 **
 389 ** INPUTS:
 390 **  command: one of the enumerated values in PRTraceOptions
 391 ** valid for PR_GetTraceOption().
 392 **
 393 ** OUTPUTS:
 394 **  dependent on command.
 395 **
 396 ** RETURNS: void
 397 **
 398 ** RESTRICTIONS:
 399 **
 400 */
 401 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 402 #define PR_GET_TRACE_OPTION(command,value)\
 403     PR_GetTraceOption((command),(value))
 404 #else
 405 #define PR_GET_TRACE_OPTION(command,value)
 406 #endif
 407
 408 NSPR_API(void)
 409         PR_GetTraceOption(
 410         PRTraceOption command,  /* One of the enumerated values */
 411             void *value             /* command value or NULL */
 412 );
 413
 414 /* -----------------------------------------------------------------------
 415 ** FUNCTION: PR_GetTraceHandleFromName() -- Retrieve an existing
 416 ** handle by name.
 417 **
 418 ** DESCRIPTION:
 419 ** PR_GetTraceHandleFromName() retreives an existing tracehandle
 420 ** using the name specified by qName and rName.
 421 **
 422 ** INPUTS:
 423 **  qName: pointer to string. QName for this trace handle.
 424 **
 425 **  rName: pointer to string. RName for this trace handle.
 426 **
 427 **
 428 ** OUTPUTS: returned.
 429 **
 430 ** RETURNS:
 431 **  PRTraceHandle associated with qName and rName or NULL when
 432 ** there is no match.
 433 **
 434 ** RESTRICTIONS:
 435 **
 436 */
 437 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 438 #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)\
 439     (handle) = PR_GetTraceHandleFromName((qName),(rName))
 440 #else
 441 #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)
 442 #endif
 443
 444 NSPR_API(PRTraceHandle)
 445         PR_GetTraceHandleFromName(
 446         const char *qName,      /* QName search argument */
 447         const char *rName       /* RName search argument */
 448 );
 449
 450 /* -----------------------------------------------------------------------
 451 ** FUNCTION: PR_GetTraceNameFromHandle() -- Retreive trace name
 452 ** by bandle.
 453 **
 454 ** DESCRIPTION:
 455 ** PR_GetTraceNameFromHandle() retreives the existing qName,
 456 ** rName, and description for the referenced trace handle.
 457 **
 458 ** INPUTS: handle: PRTraceHandle.
 459 **
 460 ** OUTPUTS: pointers to the Trace Facility's copy of qName,
 461 ** rName and description. ... Don't mess with these values.
 462 ** They're mine.
 463 **
 464 ** RETURNS: void
 465 **
 466 ** RESTRICTIONS:
 467 **
 468 */
 469 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 470 #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)\
 471     PR_GetTraceNameFromHandle((handle),(qName),(rName),(description))
 472 #else
 473 #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)
 474 #endif
 475
 476 NSPR_API(void)
 477         PR_GetTraceNameFromHandle(
 478         PRTraceHandle handle,       /* handle as search argument */
 479             const char **qName,         /* pointer to associated QName */
 480             const char **rName,         /* pointer to associated RName */
 481         const char **description    /* pointer to associated description */
 482 );
 483
 484 /* -----------------------------------------------------------------------
 485 ** FUNCTION: PR_FindNextTraceQname() -- Retrieive a QName handle
 486 ** iterator.
 487 **
 488 ** DESCRIPTION:
 489 ** PR_FindNextTraceQname() retreives the first or next trace
 490 ** QName handle, depending on the value of handle, from the trace
 491 ** database. The PRTraceHandle returned can be used as an
 492 ** iterator to traverse the QName handles in the Trace database.
 493 **
 494 ** INPUTS:
 495 **  handle: When NULL, PR_FindNextQname() returns the first QName
 496 ** handle. When a handle is a valid PRTraceHandle previously
 497 ** retreived using PR_FindNextQname() the next QName handle is
 498 ** retreived.
 499 **
 500 ** OUTPUTS: returned.
 501 **
 502 ** RETURNS:
 503 **  PRTraceHandle or NULL when there are no trace handles.
 504 **
 505 ** RESTRICTIONS:
 506 **  Iterating thru the trace handles via FindFirst/FindNext
 507 ** should be done under protection of the trace handle lock.
 508 ** See: PR_SetTraceOption( PRLockTraceHandles ).
 509 **
 510 */
 511 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 512 #define PR_FIND_NEXT_TRACE_QNAME(next,handle)\
 513     (next) = PR_FindNextTraceQname((handle))
 514 #else
 515 #define PR_FIND_NEXT_TRACE_QNAME(next,handle)
 516 #endif
 517
 518 NSPR_API(PRTraceHandle)
 519         PR_FindNextTraceQname(
 520         PRTraceHandle handle
 521 );
 522
 523
 524 /* -----------------------------------------------------------------------
 525 ** FUNCTION: PR_FindNextTraceRname() -- Retrieive an RName handle
 526 ** iterator.
 527 **
 528 ** DESCRIPTION:
 529 ** PR_FindNextTraceRname() retreives the first or next trace
 530 ** RName handle, depending on the value of handle, from the trace
 531 ** database. The PRTraceHandle returned can be used as an
 532 ** iterator to traverse the RName handles in the Trace database.
 533 **
 534 ** INPUTS:
 535 **  rhandle: When NULL, PR_FindNextRname() returns the first
 536 ** RName handle. When a handle is a valid PRTraceHandle
 537 ** previously retreived using PR_FindNextRname() the next RName
 538 ** handle is retreived.
 539 **  qhandle: A valid PRTraceHandle retruned from a previous call
 540 ** to PR_FIND_NEXT_TRACE_QNAME().
 541 **
 542 ** OUTPUTS: returned.
 543 **
 544 ** RETURNS:
 545 **  PRTraceHandle or NULL when there are no trace handles.
 546 **
 547 ** RESTRICTIONS:
 548 **  Iterating thru the trace handles via FindNext should be done
 549 ** under protection of the trace handle lock. See: (
 550 ** PR_SetTraceOption( PRLockTraceHandles ).
 551 **
 552 */
 553 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 554 #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)\
 555     (next) = PR_FindNextTraceRname((rhandle),(qhandle))
 556 #else
 557 #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)
 558 #endif
 559
 560 NSPR_API(PRTraceHandle)
 561         PR_FindNextTraceRname(
 562         PRTraceHandle rhandle,
 563         PRTraceHandle qhandle
 564 );
 565
 566 /* -----------------------------------------------------------------------
 567 ** FUNCTION: PR_RecordTraceEntries() -- Write trace entries to external media
 568 **
 569 ** DESCRIPTION:
 570 ** PR_RecordTraceEntries() causes entries in the in-memory trace
 571 ** buffer to be written to external media.
 572 **
 573 ** When PR_RecordTraceEntries() is called from an application
 574 ** thread, the function appears to block until another thread
 575 ** calls PR_SetTraceOption() with the PRTraceStopRecording
 576 ** option. This suggests that PR_RecordTraceEntries() should be
 577 ** called from a user supplied thread whose only job is to
 578 ** record trace entries.
 579 **
 580 ** The environment variable NSPR_TRACE_LOG controls the operation
 581 ** of this function. When NSPR_TRACE_LOG is not defined in the
 582 ** environment, no recording of trace entries occurs. When
 583 ** NSPR_TRACE_LOG is defined, the value of its definition must be
 584 ** the filename of the file to receive the trace entry buffer.
 585 **
 586 ** PR_RecordTraceEntries() attempts to record the in-memory
 587 ** buffer to a file, subject to the setting of the environment
 588 ** variable NSPR_TRACE_LOG. It is possible because of system
 589 ** load, the thread priority of the recording thread, number of
 590 ** active trace records being written over time, and other
 591 ** variables that some trace records can be lost. ... In other
 592 ** words: don't bet the farm on getting everything.
 593 **
 594 ** INPUTS: none
 595 **
 596 ** OUTPUTS: none
 597 **
 598 ** RETURNS: PR_STATUS
 599 **    PR_SUCCESS no errors were found.
 600 **    PR_FAILURE errors were found.
 601 **
 602 ** RESTRICTIONS:
 603 ** Only one thread can call PR_RecordTraceEntries() within a
 604 ** process.
 605 **
 606 ** On error, PR_RecordTraceEntries() may return prematurely.
 607 **
 608 */
 609 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 610 #define PR_RECORD_TRACE_ENTRIES()\
 611         PR_RecordTraceEntries()
 612 #else
 613 #define PR_RECORD_TRACE_ENTRIES()
 614 #endif
 615
 616 NSPR_API(void)
 617         PR_RecordTraceEntries(
 618         void
 619 );
 620
 621 /* -----------------------------------------------------------------------
 622 ** FUNCTION: PR_GetTraceEntries() -- Retreive trace entries from
 623 ** the Trace Facility
 624 **
 625 ** DESCRIPTION:
 626 ** PR_GetTraceEntries() retreives trace entries from the Trace
 627 ** Facility. Up to count trace entries are copied from the Trace
 628 ** Facility into buffer. Only those trace entries that have not
 629 ** been copied via a previous call to PR_GetTraceEntries() are
 630 ** copied. The actual number copied is placed in the PRInt32
 631 ** variable pointed to by found.
 632 **
 633 ** If more than count trace entries have entered the Trace
 634 ** Facility since the last call to PR_GetTraceEntries()
 635 ** a lost data condition is returned. In this case, the most
 636 ** recent count trace entries are copied into buffer and found is
 637 ** set to count.
 638 **
 639 ** INPUTS:
 640 **  count. The number of trace entries to be copied into buffer.
 641 **
 642 **
 643 ** OUTPUTS:
 644 **  buffer. An array of PRTraceEntries. The buffer is supplied
 645 ** by the caller.
 646 **
 647 ** found: 32bit signed integer. The number of PRTraceEntries
 648 ** actually copied. found is always less than or equal to count.
 649 **
 650 ** RETURNS:
 651 **  zero when there is no lost data.
 652 **  non-zero when some PRTraceEntries have been lost.
 653 **
 654 ** RESTRICTIONS:
 655 ** This is a real performance pig. The copy out operation is bad
 656 ** enough, but depending on then frequency of calls to the
 657 ** function, serious performance impact to the operating
 658 ** application may be realized. ... YMMV.
 659 **
 660 */
 661 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
 662 #define PR_GET_TRACE_ENTRIES(buffer,count,found)\
 663         PR_GetTraceEntries((buffer),(count),(found))
 664 #else
 665 #define PR_GET_TRACE_ENTRIES(buffer,count,found)
 666 #endif
 667
 668 NSPR_API(PRIntn)
 669     PR_GetTraceEntries(
 670         PRTraceEntry    *buffer,    /* where to write output */
 671         PRInt32         count,      /* number to get */
 672         PRInt32         *found      /* number you got */
 673 );
 674
 675 PR_END_EXTERN_C
 676
 677 #endif /* prtrace_h___ */
 678