PageRenderTime 50ms CodeModel.GetById 32ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 1ms

/gecko_api/include/prtrace.h

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