|
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 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 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 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 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 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 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 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 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 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 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 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 |