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
68PR_BEGIN_EXTERN_C
69
70/*
71** Opaque type for the trace handle
72** ... Don't even think about looking in here.
73**
74*/
75typedef void * PRTraceHandle;
76
77/*
78** PRTraceEntry -- A trace entry in the in-memory trace buffer
79** looks like this.
80**
81*/
82typedef 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*/
95typedef 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
176NSPR_API(PRTraceHandle)
177PR_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
210NSPR_API(void)
211PR_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
251NSPR_API(void)
252PR_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
338NSPR_API(void)
339PR_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
376NSPR_API(void)
377PR_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
412NSPR_API(PRTraceHandle)
413PR_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
444NSPR_API(void)
445PR_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
486NSPR_API(PRTraceHandle)
487PR_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
528NSPR_API(PRTraceHandle)
529PR_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
584NSPR_API(void)
585PR_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
636NSPR_API(PRIntn)
637PR_GetTraceEntries(
638 PRTraceEntry *buffer, /* where to write output */
639 PRInt32 count, /* number to get */
640 PRInt32 *found /* number you got */
641);
642
643PR_END_EXTERN_C
644
645#endif /* prtrace_h___ */
646
647

source code of include/nspr/prtrace.h