| blob | ebfe1baf21a3164e02ff67000209c62ecf240faa |
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 */
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 */
97 PR_BEGIN_EXTERN_C
99 /*
100 ** Opaque type for the trace handle
101 ** ... Don't even think about looking in here.
102 **
103 */
106 /*
107 ** PRTraceEntry -- A trace entry in the in-memory trace buffer
108 ** looks like this.
109 **
110 */
112 {
119 /*
120 ** PRTraceOption -- command operands to
121 ** PR_[Set|Get]TraceOption(). See descriptive meanings there.
122 **
123 */
125 {
126 PRTraceBufSize,
127 PRTraceEnable,
128 PRTraceDisable,
129 PRTraceSuspend,
130 PRTraceResume,
131 PRTraceSuspendRecording,
132 PRTraceResumeRecording,
133 PRTraceLockHandles,
134 PRTraceUnLockHandles,
135 PRTraceStopRecording
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
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
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
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
210 );
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
241 PRTraceHandle handle /* Handle to be destroyed */
242 );
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
290 PRUint32 userData7 /* User supplied data word 7 */
291 );
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
371 );
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
409 );
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
445 );
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
479 );
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
517 PRTraceHandle handle
518 );
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
559 PRTraceHandle rhandle,
560 PRTraceHandle qhandle
561 );
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
615 void
616 );
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
670 );
672 PR_END_EXTERN_C