Back to index

lightning-sunbird  0.9+nobinonly
prtrace.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef prtrace_h___
00039 #define prtrace_h___
00040 /*
00041 ** prtrace.h -- NSPR's Trace Facility.                      
00042 **                                                                                      
00043 ** The Trace Facility provides a means to trace application                                    
00044 ** program events within a process. When implementing an                                
00045 ** application program an engineer may insert a "Trace" function                        
00046 ** call, passing arguments to be traced. The "Trace" function                           
00047 ** combines the user trace data with identifying data and                               
00048 ** writes this data in time ordered sequence into a circular                            
00049 ** in-memory buffer; when the buffer fills, it wraps.
00050 **                                                                                      
00051 ** Functions are provided to set and/or re-configure the size of                        
00052 ** the trace buffer, control what events are recorded in the                            
00053 ** buffer, enable and disable tracing based on specific user                            
00054 ** supplied data and other control functions. Methods are provided                      
00055 ** to record the trace entries in the in-memory trace buffer to
00056 ** a file.
00057 **                                                                                      
00058 ** Tracing may cause a performance degredation to the application                       
00059 ** depending on the number and placement of calls to the tracing                        
00060 ** facility. When tracing is compiled in and all tracing is                                    
00061 ** disabled via the runtime controls, the overhead should be                            
00062 ** minimal. ... Famous last words, eh?                                                                       
00063 **                                                                                                                                 
00064 ** When DEBUG is defined at compile time, the Trace Facility is                    
00065 ** compiled as part of NSPR and any application using NSPR's                       
00066 ** header files will have tracing compiled in. When DEBUG is not                   
00067 ** defined, the Trace Facility is not compiled into NSPR nor                       
00068 ** exported in its header files.  If the Trace Facility is                         
00069 ** desired in a non-debug build, then FORCE_NSPR_TRACE may be                      
00070 ** defined at compile time for both the optimized build of NSPR                    
00071 ** and the application. NSPR and any application using  NSPR's                     
00072 ** Trace Facility must be compiled with the same level of trace                    
00073 ** conditioning or unresolved references may be realized at link                   
00074 ** time.                                                                           
00075 **                                                                                 
00076 ** For any of the Trace Facility methods that requires a trace                     
00077 ** handle as an input argument, the caller must ensure that the                    
00078 ** trace handle argument is valid. An invalid trace handle                         
00079 ** argument may cause unpredictable results.                                       
00080 **                                                                                 
00081 ** Trace Facility methods are thread-safe and SMP safe.                            
00082 **                                                                                 
00083 ** Users of the Trace Facility should use the defined macros to                     
00084 ** invoke trace methods, not the function calls directly. e.g.                      
00085 ** PR_TRACE( h1,0,1,2, ...); not PR_Trace(h1,0,1,2, ...);
00086 **                                                                                  
00087 ** Application designers should be aware of the effects of
00088 ** debug and optimized build differences when using result of the
00089 ** Trace Facility macros in expressions.
00090 ** 
00091 ** See Also: prcountr.h                                                                                 
00092 **                                                                                  
00093 ** /lth. 08-Jun-1998.                                                                                  
00094 */
00095 
00096 #include "prtypes.h"
00097 #include "prthread.h"
00098 #include "prtime.h"
00099 
00100 PR_BEGIN_EXTERN_C
00101 
00102 /*
00103 ** Opaque type for the trace handle 
00104 ** ... Don't even think about looking in here.
00105 **
00106 */
00107 typedef void *  PRTraceHandle;
00108 
00109 /*
00110 ** PRTraceEntry -- A trace entry in the in-memory trace buffer
00111 ** looks like this.
00112 **
00113 */
00114 typedef struct PRTraceEntry
00115 {
00116     PRThread        *thread;        /* The thread creating the trace entry */
00117     PRTraceHandle   handle;         /* PRTraceHandle creating the trace entry */
00118     PRTime          time;           /* Value of PR_Now() at time of trace entry */
00119     PRUint32        userData[8];    /* user supplied trace data */
00120 } PRTraceEntry;
00121 
00122 /*
00123 ** PRTraceOption -- command operands to
00124 ** PR_[Set|Get]TraceOption(). See descriptive meanings there.
00125 **
00126 */
00127 typedef enum PRTraceOption
00128 {
00129     PRTraceBufSize,
00130     PRTraceEnable,              
00131     PRTraceDisable,
00132     PRTraceSuspend,
00133     PRTraceResume,
00134     PRTraceSuspendRecording,
00135     PRTraceResumeRecording,
00136     PRTraceLockHandles,
00137     PRTraceUnLockHandles,
00138     PRTraceStopRecording
00139 } PRTraceOption;
00140 
00141 /* -----------------------------------------------------------------------
00142 ** FUNCTION: PR_DEFINE_TRACE() -- Define a PRTraceHandle
00143 ** 
00144 ** DESCRIPTION: PR_DEFINE_TRACE() is used to define a trace
00145 ** handle.
00146 ** 
00147 */
00148 #define PR_DEFINE_TRACE(name) PRTraceHandle name
00149 
00150 /* -----------------------------------------------------------------------
00151 ** FUNCTION: PR_INIT_TRACE_HANDLE() -- Set the value of a PRTraceHandle
00152 ** 
00153 ** DESCRIPTION: 
00154 ** PR_INIT_TRACE_HANDLE() sets the value of a PRTraceHandle
00155 ** to value. e.g. PR_INIT_TRACE_HANDLE( myHandle, NULL );
00156 ** 
00157 */
00158 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00159 #define PR_INIT_TRACE_HANDLE(handle,value)\
00160     (handle) = (PRCounterHandle)(value)
00161 #else
00162 #define PR_INIT_TRACE_HANDLE(handle,value)
00163 #endif
00164 
00165 
00166 /* -----------------------------------------------------------------------
00167 ** FUNCTION: PR_CreateTrace() -- Create a trace handle
00168 ** 
00169 ** DESCRIPTION:
00170 **  PR_CreateTrace() creates a new trace handle. Tracing is
00171 **  enabled for this handle when it is created. The trace handle
00172 **  is intended for use in other Trace Facility calls.
00173 **  
00174 **  PR_CreateTrace() registers the QName, RName and description
00175 **  data so that this data can be retrieved later.
00176 ** 
00177 ** INPUTS: 
00178 **  qName: pointer to string. QName for this trace handle. 
00179 ** 
00180 **  rName: pointer to string. RName for this trace handle. 
00181 ** 
00182 **  description: pointer to string. Descriptive data about this
00183 **  trace handle.
00184 **
00185 ** OUTPUTS:
00186 **  Creates the trace handle. 
00187 **  Registers the QName and RName with the trace facility.
00188 ** 
00189 ** RETURNS: 
00190 **  PRTraceHandle
00191 ** 
00192 ** RESTRICTIONS:
00193 **  qName is limited to 31 characters.
00194 **  rName is limited to 31 characters.
00195 **  description is limited to 255 characters.
00196 ** 
00197 */
00198 #define PRTRACE_NAME_MAX 31
00199 #define PRTRACE_DESC_MAX 255
00200 
00201 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00202 #define PR_CREATE_TRACE(handle,qName,rName,description)\
00203     (handle) = PR_CreateTrace((qName),(rName),(description))
00204 #else
00205 #define PR_CREATE_TRACE(handle,qName,rName,description)
00206 #endif
00207 
00208 NSPR_API(PRTraceHandle)
00209        PR_CreateTrace( 
00210        const char *qName,          /* QName for this trace handle */
00211            const char *rName,          /* RName for this trace handle */
00212            const char *description     /* description for this trace handle */
00213 );
00214 
00215 
00216 /* -----------------------------------------------------------------------
00217 ** FUNCTION: PR_DestroyTrace() -- Destroy a trace handle
00218 ** 
00219 ** DESCRIPTION: 
00220 **  PR_DestroyTrace() removes the referenced trace handle and
00221 ** associated QName, RName and description data from the Trace
00222 ** Facility.
00223 ** 
00224 ** INPUTS: handle. A PRTraceHandle
00225 ** 
00226 ** OUTPUTS: 
00227 **  The trace handle is unregistered.
00228 **  The QName, RName and description are removed.
00229 ** 
00230 ** RETURNS: void
00231 ** 
00232 ** RESTRICTIONS:
00233 ** 
00234 */
00235 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00236 #define PR_DESTROY_TRACE(handle)\
00237     PR_DestroyTrace((handle))
00238 #else
00239 #define PR_DESTROY_TRACE(handle)
00240 #endif
00241 
00242 NSPR_API(void) 
00243        PR_DestroyTrace( 
00244               PRTraceHandle handle    /* Handle to be destroyed */
00245 );
00246 
00247 
00248 /* -----------------------------------------------------------------------
00249 ** FUNCTION: PR_Trace() -- Make a trace entry in the in-memory trace
00250 ** 
00251 ** DESCRIPTION:
00252 ** PR_Trace() makes an entry in the in-memory trace buffer for
00253 ** the referenced trace handle. The next logically available
00254 ** PRTraceEntry is used; when the next trace entry would overflow
00255 ** the trace table, the table wraps.
00256 **
00257 ** PR_Trace() for a specific trace handle may be disabled by
00258 ** calling PR_SetTraceOption() specifying PRTraceDisable for the
00259 ** trace handle to be disabled.
00260 ** 
00261 ** INPUTS:
00262 ** handle: PRTraceHandle. The trace handle for this trace.
00263 ** 
00264 ** userData[0..7]: unsigned 32bit integers. user supplied data
00265 ** that is copied into the PRTraceEntry
00266 ** 
00267 ** OUTPUTS:
00268 **  A PRTraceEntry is (conditionally) formatted in the in-memory
00269 ** trace buffer.
00270 ** 
00271 ** RETURNS: void.
00272 ** 
00273 ** RESTRICTIONS:
00274 ** 
00275 */
00276 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00277 #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)\
00278     PR_Trace((handle),(ud0),(ud1),(ud2),(ud3),(ud4),(ud5),(ud6),(ud7))
00279 #else
00280 #define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)
00281 #endif
00282 
00283 NSPR_API(void) 
00284        PR_Trace( 
00285        PRTraceHandle handle,       /* use this trace handle */
00286            PRUint32    userData0,      /* User supplied data word 0 */
00287            PRUint32    userData1,      /* User supplied data word 1 */
00288            PRUint32    userData2,      /* User supplied data word 2 */
00289            PRUint32    userData3,      /* User supplied data word 3 */
00290            PRUint32    userData4,      /* User supplied data word 4 */
00291            PRUint32    userData5,      /* User supplied data word 5 */
00292            PRUint32    userData6,      /* User supplied data word 6 */
00293            PRUint32    userData7       /* User supplied data word 7 */
00294 );
00295 
00296 /* -----------------------------------------------------------------------
00297 ** FUNCTION: PR_SetTraceOption() -- Control the Trace Facility
00298 ** 
00299 ** DESCRIPTION:
00300 ** PR_SetTraceOption() controls the Trace Facility. Depending on
00301 ** command and value, attributes of the Trace Facility may be
00302 ** changed.
00303 ** 
00304 ** INPUTS:
00305 **  command: An enumerated value in the set of PRTraceOption.
00306 **  value: pointer to the data to be set. Type of the data is
00307 **  dependent on command; for each value of command, the type
00308 **  and meaning of dereferenced value is shown.
00309 **
00310 **  PRTraceBufSize: unsigned long: the size of the trace buffer,
00311 ** in bytes.
00312 ** 
00313 **  PRTraceEnable: PRTraceHandle. The trace handle to be
00314 ** enabled.
00315 ** 
00316 **  PRTraceDisable: PRTraceHandle. The trace handle to be
00317 ** disabled.
00318 ** 
00319 **  PRTraceSuspend: void. value must be NULL. All tracing is
00320 ** suspended.
00321 ** 
00322 **  PRTraceResume: void. value must be NULL. Tracing for all
00323 ** previously enabled, prior to a PRTraceSuspend, is resumed.
00324 ** 
00325 **  PRTraceStopRecording: void. value must be NULL. If recording
00326 ** (see: ** PR_RecordTraceEntries()) is being done, 
00327 ** PRTraceStopRecording causes PR_RecordTraceEntries() to return
00328 ** to its caller. If recording is not being done, this function
00329 ** has no effect.
00330 ** 
00331 **  PRTraceSuspendRecording: void. Must be NULL. If recording is
00332 ** being done, PRTraceSuspendRecording causes further writes to
00333 ** the trace file to be suspended. Data in the in-memory
00334 ** trace buffer that would ordinarily be written to the
00335 ** trace file will not be written. Trace entries will continue
00336 ** to be entered in the in-memory buffer. If the Trace Facility
00337 ** recording is already in a suspended state, the call has no
00338 ** effect.
00339 ** 
00340 **  PRTraceResumeRecording: void. value must be NULL. If
00341 ** recording for the Trace Facility has been previously been
00342 ** suspended, this causes recording to resume. Recording resumes
00343 ** with the next in-memory buffer segment that would be written
00344 ** if trace recording had not been suspended. If recording is
00345 ** not currently suspended, the call has no effect.
00346 ** 
00347 **  PRTraceLockHandles: void. value must be NULL. Locks the
00348 ** trace handle lock. While the trace handle lock is held,
00349 ** calls to PR_CreateTrace() will block until the lock is
00350 ** released.
00351 ** 
00352 **  PRTraceUnlockHandles: void. value must be NULL. Unlocks the
00353 ** trace handle lock.
00354 ** 
00355 ** OUTPUTS:
00356 **  The operation of the Trace Facility may be changed.
00357 ** 
00358 ** RETURNS: void
00359 ** 
00360 ** RESTRICTIONS:
00361 ** 
00362 */
00363 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00364 #define PR_SET_TRACE_OPTION(command,value)\
00365     PR_SetTraceOption((command),(value))
00366 #else
00367 #define PR_SET_TRACE_OPTION(command,value)
00368 #endif
00369 
00370 NSPR_API(void) 
00371        PR_SetTraceOption( 
00372            PRTraceOption command,  /* One of the enumerated values */
00373            void *value             /* command value or NULL */
00374 );
00375 
00376 
00377 /* -----------------------------------------------------------------------
00378 ** FUNCTION: PR_GetTraceOption() -- Retrieve settings from the Trace Facility
00379 ** 
00380 ** DESCRIPTION:
00381 ** PR_GetTraceOption() retrieves the current setting of the
00382 ** Trace Facility control depending on command.
00383 ** 
00384 ** 
00385 **  PRTraceBufSize: unsigned long: the size of the trace buffer,
00386 ** in bytes.
00387 ** 
00388 ** 
00389 ** INPUTS:
00390 **  command: one of the enumerated values in PRTraceOptions
00391 ** valid for PR_GetTraceOption().
00392 ** 
00393 ** OUTPUTS:
00394 **  dependent on command.
00395 ** 
00396 ** RETURNS: void
00397 ** 
00398 ** RESTRICTIONS:
00399 ** 
00400 */
00401 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00402 #define PR_GET_TRACE_OPTION(command,value)\
00403     PR_GetTraceOption((command),(value))
00404 #else
00405 #define PR_GET_TRACE_OPTION(command,value)
00406 #endif
00407 
00408 NSPR_API(void) 
00409        PR_GetTraceOption( 
00410        PRTraceOption command,  /* One of the enumerated values */
00411            void *value             /* command value or NULL */
00412 );
00413 
00414 /* -----------------------------------------------------------------------
00415 ** FUNCTION: PR_GetTraceHandleFromName() -- Retrieve an existing
00416 ** handle by name.
00417 ** 
00418 ** DESCRIPTION:
00419 ** PR_GetTraceHandleFromName() retreives an existing tracehandle
00420 ** using the name specified by qName and rName.
00421 ** 
00422 ** INPUTS:
00423 **  qName: pointer to string. QName for this trace handle. 
00424 ** 
00425 **  rName: pointer to string. RName for this trace handle. 
00426 ** 
00427 ** 
00428 ** OUTPUTS: returned.
00429 ** 
00430 ** RETURNS: 
00431 **  PRTraceHandle associated with qName and rName or NULL when
00432 ** there is no match.
00433 ** 
00434 ** RESTRICTIONS:
00435 ** 
00436 */
00437 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00438 #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)\
00439     (handle) = PR_GetTraceHandleFromName((qName),(rName))
00440 #else
00441 #define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)
00442 #endif
00443 
00444 NSPR_API(PRTraceHandle) 
00445        PR_GetTraceHandleFromName( 
00446        const char *qName,      /* QName search argument */
00447         const char *rName       /* RName search argument */
00448 );
00449 
00450 /* -----------------------------------------------------------------------
00451 ** FUNCTION: PR_GetTraceNameFromHandle() -- Retreive trace name
00452 ** by bandle.
00453 ** 
00454 ** DESCRIPTION:
00455 ** PR_GetTraceNameFromHandle() retreives the existing qName,
00456 ** rName, and description for the referenced trace handle.
00457 ** 
00458 ** INPUTS: handle: PRTraceHandle.
00459 ** 
00460 ** OUTPUTS: pointers to the Trace Facility's copy of qName,
00461 ** rName and description. ... Don't mess with these values.
00462 ** They're mine.
00463 ** 
00464 ** RETURNS: void
00465 ** 
00466 ** RESTRICTIONS:
00467 ** 
00468 */
00469 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00470 #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)\
00471     PR_GetTraceNameFromHandle((handle),(qName),(rName),(description))
00472 #else
00473 #define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)
00474 #endif
00475 
00476 NSPR_API(void) 
00477        PR_GetTraceNameFromHandle( 
00478        PRTraceHandle handle,       /* handle as search argument */
00479            const char **qName,         /* pointer to associated QName */
00480            const char **rName,         /* pointer to associated RName */
00481        const char **description    /* pointer to associated description */
00482 );
00483 
00484 /* -----------------------------------------------------------------------
00485 ** FUNCTION: PR_FindNextTraceQname() -- Retrieive a QName handle
00486 ** iterator.
00487 ** 
00488 ** DESCRIPTION:
00489 ** PR_FindNextTraceQname() retreives the first or next trace
00490 ** QName handle, depending on the value of handle, from the trace
00491 ** database. The PRTraceHandle returned can be used as an
00492 ** iterator to traverse the QName handles in the Trace database.
00493 ** 
00494 ** INPUTS:
00495 **  handle: When NULL, PR_FindNextQname() returns the first QName
00496 ** handle. When a handle is a valid PRTraceHandle previously
00497 ** retreived using PR_FindNextQname() the next QName handle is
00498 ** retreived.
00499 ** 
00500 ** OUTPUTS: returned.
00501 ** 
00502 ** RETURNS: 
00503 **  PRTraceHandle or NULL when there are no trace handles.
00504 ** 
00505 ** RESTRICTIONS:
00506 **  Iterating thru the trace handles via FindFirst/FindNext
00507 ** should be done under protection of the trace handle lock.
00508 ** See: PR_SetTraceOption( PRLockTraceHandles ).
00509 ** 
00510 */
00511 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00512 #define PR_FIND_NEXT_TRACE_QNAME(next,handle)\
00513     (next) = PR_FindNextTraceQname((handle))
00514 #else
00515 #define PR_FIND_NEXT_TRACE_QNAME(next,handle)
00516 #endif
00517 
00518 NSPR_API(PRTraceHandle) 
00519        PR_FindNextTraceQname( 
00520         PRTraceHandle handle
00521 );
00522 
00523 
00524 /* -----------------------------------------------------------------------
00525 ** FUNCTION: PR_FindNextTraceRname() -- Retrieive an RName handle
00526 ** iterator.
00527 ** 
00528 ** DESCRIPTION:
00529 ** PR_FindNextTraceRname() retreives the first or next trace
00530 ** RName handle, depending on the value of handle, from the trace
00531 ** database. The PRTraceHandle returned can be used as an
00532 ** iterator to traverse the RName handles in the Trace database.
00533 ** 
00534 ** INPUTS:
00535 **  rhandle: When NULL, PR_FindNextRname() returns the first
00536 ** RName handle. When a handle is a valid PRTraceHandle
00537 ** previously retreived using PR_FindNextRname() the next RName
00538 ** handle is retreived.
00539 **  qhandle: A valid PRTraceHandle retruned from a previous call
00540 ** to PR_FIND_NEXT_TRACE_QNAME().
00541 ** 
00542 ** OUTPUTS: returned.
00543 ** 
00544 ** RETURNS: 
00545 **  PRTraceHandle or NULL when there are no trace handles.
00546 ** 
00547 ** RESTRICTIONS:
00548 **  Iterating thru the trace handles via FindNext should be done
00549 ** under protection of the trace handle lock. See: (
00550 ** PR_SetTraceOption( PRLockTraceHandles ).
00551 ** 
00552 */
00553 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00554 #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)\
00555     (next) = PR_FindNextTraceRname((rhandle),(qhandle))
00556 #else
00557 #define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)
00558 #endif
00559 
00560 NSPR_API(PRTraceHandle) 
00561        PR_FindNextTraceRname( 
00562         PRTraceHandle rhandle,
00563         PRTraceHandle qhandle
00564 );
00565 
00566 /* -----------------------------------------------------------------------
00567 ** FUNCTION: PR_RecordTraceEntries() -- Write trace entries to external media
00568 ** 
00569 ** DESCRIPTION:
00570 ** PR_RecordTraceEntries() causes entries in the in-memory trace
00571 ** buffer to be written to external media.
00572 **
00573 ** When PR_RecordTraceEntries() is called from an application
00574 ** thread, the function appears to block until another thread
00575 ** calls PR_SetTraceOption() with the PRTraceStopRecording
00576 ** option. This suggests that PR_RecordTraceEntries() should be
00577 ** called from a user supplied thread whose only job is to
00578 ** record trace entries. 
00579 ** 
00580 ** The environment variable NSPR_TRACE_LOG controls the operation
00581 ** of this function. When NSPR_TRACE_LOG is not defined in the
00582 ** environment, no recording of trace entries occurs. When
00583 ** NSPR_TRACE_LOG is defined, the value of its definition must be
00584 ** the filename of the file to receive the trace entry buffer.
00585 **
00586 ** PR_RecordTraceEntries() attempts to record the in-memory
00587 ** buffer to a file, subject to the setting of the environment
00588 ** variable NSPR_TRACE_LOG. It is possible because of system
00589 ** load, the thread priority of the recording thread, number of
00590 ** active trace records being written over time, and other
00591 ** variables that some trace records can be lost. ... In other
00592 ** words: don't bet the farm on getting everything.
00593 ** 
00594 ** INPUTS: none
00595 ** 
00596 ** OUTPUTS: none
00597 ** 
00598 ** RETURNS: PR_STATUS
00599 **    PR_SUCCESS no errors were found.
00600 **    PR_FAILURE errors were found.
00601 ** 
00602 ** RESTRICTIONS:
00603 ** Only one thread can call PR_RecordTraceEntries() within a
00604 ** process.
00605 ** 
00606 ** On error, PR_RecordTraceEntries() may return prematurely.
00607 ** 
00608 */
00609 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00610 #define PR_RECORD_TRACE_ENTRIES()\
00611        PR_RecordTraceEntries()
00612 #else
00613 #define PR_RECORD_TRACE_ENTRIES()
00614 #endif
00615     
00616 NSPR_API(void)
00617        PR_RecordTraceEntries(
00618         void 
00619 );
00620 
00621 /* -----------------------------------------------------------------------
00622 ** FUNCTION: PR_GetTraceEntries() -- Retreive trace entries from
00623 ** the Trace Facility
00624 ** 
00625 ** DESCRIPTION:
00626 ** PR_GetTraceEntries() retreives trace entries from the Trace
00627 ** Facility. Up to count trace entries are copied from the Trace
00628 ** Facility into buffer. Only those trace entries that have not
00629 ** been copied via a previous call to PR_GetTraceEntries() are
00630 ** copied. The actual number copied is placed in the PRInt32
00631 ** variable pointed to by found.
00632 **
00633 ** If more than count trace entries have entered the Trace
00634 ** Facility since the last call to PR_GetTraceEntries() 
00635 ** a lost data condition is returned. In this case, the most
00636 ** recent count trace entries are copied into buffer and found is
00637 ** set to count.
00638 ** 
00639 ** INPUTS:
00640 **  count. The number of trace entries to be copied into buffer.
00641 ** 
00642 ** 
00643 ** OUTPUTS:
00644 **  buffer. An array of PRTraceEntries. The buffer is supplied
00645 ** by the caller.
00646 ** 
00647 ** found: 32bit signed integer. The number of PRTraceEntries
00648 ** actually copied. found is always less than or equal to count.
00649 ** 
00650 ** RETURNS: 
00651 **  zero when there is no lost data.
00652 **  non-zero when some PRTraceEntries have been lost.
00653 ** 
00654 ** RESTRICTIONS:
00655 ** This is a real performance pig. The copy out operation is bad
00656 ** enough, but depending on then frequency of calls to the
00657 ** function, serious performance impact to the operating
00658 ** application may be realized. ... YMMV.
00659 ** 
00660 */
00661 #if defined (DEBUG) || defined (FORCE_NSPR_TRACE)
00662 #define PR_GET_TRACE_ENTRIES(buffer,count,found)\
00663         PR_GetTraceEntries((buffer),(count),(found))
00664 #else
00665 #define PR_GET_TRACE_ENTRIES(buffer,count,found)
00666 #endif
00667 
00668 NSPR_API(PRIntn)
00669     PR_GetTraceEntries(
00670         PRTraceEntry    *buffer,    /* where to write output */
00671         PRInt32         count,      /* number to get */
00672         PRInt32         *found      /* number you got */
00673 );
00674 
00675 PR_END_EXTERN_C
00676 
00677 #endif /* prtrace_h___ */
00678