src/third_party/npapi/npspy/extern/nspr/prtrace.h

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