| blob | 42f88e93b776ba5dc4560a10ab1b519efb85ae75 |
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 ***** */
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 */
100 PR_BEGIN_EXTERN_C
102 /*
103 ** Opaque type for the trace handle
104 ** ... Don't even think about looking in here.
105 **
106 */
109 /*
110 ** PRTraceEntry -- A trace entry in the in-memory trace buffer
111 ** looks like this.
112 **
113 */
115 {
122 /*
123 ** PRTraceOption -- command operands to
124 ** PR_[Set|Get]TraceOption(). See descriptive meanings there.
125 **
126 */
128 {
129 PRTraceBufSize,
130 PRTraceEnable,
131 PRTraceDisable,
132 PRTraceSuspend,
133 PRTraceResume,
134 PRTraceSuspendRecording,
135 PRTraceResumeRecording,
136 PRTraceLockHandles,
137 PRTraceUnLockHandles,
138 PRTraceStopRecording
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
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
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
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
213 );
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
244 PRTraceHandle handle /* Handle to be destroyed */
245 );
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
293 PRUint32 userData7 /* User supplied data word 7 */
294 );
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
374 );
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
412 );
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
448 );
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
482 );
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
520 PRTraceHandle handle
521 );
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
562 PRTraceHandle rhandle,
563 PRTraceHandle qhandle
564 );
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
618 void
619 );
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
673 );
675 PR_END_EXTERN_C