![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to prtrace.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Synchronet] / sbbs / include / mozilla / nspr|
Return to prtrace.h CVS log | Up to [Synchronet] / sbbs / include / mozilla / nspr |
1.1 ! root 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:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.