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 97PR_BEGIN_EXTERN_C 98 99/* 100** Opaque type for the trace handle 101** ... Don't even think about looking in here. 102** 103*/ 104typedef void * PRTraceHandle; 105 106/* 107** PRTraceEntry -- A trace entry in the in-memory trace buffer 108** looks like this. 109** 110*/ 111typedef 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*/ 124typedef 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 205NSPR_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 239NSPR_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 280NSPR_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 367NSPR_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 405NSPR_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 441NSPR_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 473NSPR_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 515NSPR_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 557NSPR_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 613NSPR_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 665NSPR_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 672PR_END_EXTERN_C 673 674#endif /* prtrace_h___ */ 675 676