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