prtrace.h@ 50011

Last change on this file since 50011 was 11551, checked in by vboxsync, 16 years ago
API/xpcom: prefix any C symbols in VBoxXPCOM.so, to avoid namespace pollution. Enabled only on Linux at the moment.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 24.1 KB

Line
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 *** */
37
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	*/
95
96	#include "prtypes.h"
97	#include "prthread.h"
98	#include "prtime.h"
99
100	#ifdef VBOX_WITH_XPCOM_NAMESPACE_CLEANUP
101	#define PR_CreateTrace VBoxNsprPR_CreateTrace
102	#define PR_DestroyTrace VBoxNsprPR_DestroyTrace
103	#define PR_Trace VBoxNsprPR_Trace
104	#define PR_SetTraceOption VBoxNsprPR_SetTraceOption
105	#define PR_GetTraceOption VBoxNsprPR_GetTraceOption
106	#define PR_GetTraceHandleFromName VBoxNsprPR_GetTraceHandleFromName
107	#define PR_GetTraceNameFromHandle VBoxNsprPR_GetTraceNameFromHandle
108	#define PR_FindNextTraceQname VBoxNsprPR_FindNextTraceQname
109	#define PR_FindNextTraceRname VBoxNsprPR_FindNextTraceRname
110	#define PR_RecordTraceEntries VBoxNsprPR_RecordTraceEntries
111	#define PR_GetTraceEntries VBoxNsprPR_GetTraceEntries
112	#endif /* VBOX_WITH_XPCOM_NAMESPACE_CLEANUP */
113
114	PR_BEGIN_EXTERN_C
115
116	/*
117	** Opaque type for the trace handle
118	** ... Don't even think about looking in here.
119	**
120	*/
121	typedef void * PRTraceHandle;
122
123	/*
124	** PRTraceEntry -- A trace entry in the in-memory trace buffer
125	** looks like this.
126	**
127	*/
128	typedef struct PRTraceEntry
129	{
130	PRThread thread; / The thread creating the trace entry */
131	PRTraceHandle handle; /* PRTraceHandle creating the trace entry */
132	PRTime time; /* Value of PR_Now() at time of trace entry */
133	PRUint32 userData[8]; /* user supplied trace data */
134	} PRTraceEntry;
135
136	/*
137	** PRTraceOption -- command operands to
138	** PR_[Set\|Get]TraceOption(). See descriptive meanings there.
139	**
140	*/
141	typedef enum PRTraceOption
142	{
143	PRTraceBufSize,
144	PRTraceEnable,
145	PRTraceDisable,
146	PRTraceSuspend,
147	PRTraceResume,
148	PRTraceSuspendRecording,
149	PRTraceResumeRecording,
150	PRTraceLockHandles,
151	PRTraceUnLockHandles,
152	PRTraceStopRecording
153	} PRTraceOption;
154
155	/* -----------------------------------------------------------------------
156	** FUNCTION: PR_DEFINE_TRACE() -- Define a PRTraceHandle
157	**
158	** DESCRIPTION: PR_DEFINE_TRACE() is used to define a trace
159	** handle.
160	**
161	*/
162	#define PR_DEFINE_TRACE(name) PRTraceHandle name
163
164	/* -----------------------------------------------------------------------
165	** FUNCTION: PR_INIT_TRACE_HANDLE() -- Set the value of a PRTraceHandle
166	**
167	** DESCRIPTION:
168	** PR_INIT_TRACE_HANDLE() sets the value of a PRTraceHandle
169	** to value. e.g. PR_INIT_TRACE_HANDLE( myHandle, NULL );
170	**
171	*/
172	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
173	#define PR_INIT_TRACE_HANDLE(handle,value)\
174	(handle) = (PRCounterHandle)(value)
175	#else
176	#define PR_INIT_TRACE_HANDLE(handle,value)
177	#endif
178
179
180	/* -----------------------------------------------------------------------
181	** FUNCTION: PR_CreateTrace() -- Create a trace handle
182	**
183	** DESCRIPTION:
184	** PR_CreateTrace() creates a new trace handle. Tracing is
185	** enabled for this handle when it is created. The trace handle
186	** is intended for use in other Trace Facility calls.
187	**
188	** PR_CreateTrace() registers the QName, RName and description
189	** data so that this data can be retrieved later.
190	**
191	** INPUTS:
192	** qName: pointer to string. QName for this trace handle.
193	**
194	** rName: pointer to string. RName for this trace handle.
195	**
196	** description: pointer to string. Descriptive data about this
197	** trace handle.
198	**
199	** OUTPUTS:
200	** Creates the trace handle.
201	** Registers the QName and RName with the trace facility.
202	**
203	** RETURNS:
204	** PRTraceHandle
205	**
206	** RESTRICTIONS:
207	** qName is limited to 31 characters.
208	** rName is limited to 31 characters.
209	** description is limited to 255 characters.
210	**
211	*/
212	#define PRTRACE_NAME_MAX 31
213	#define PRTRACE_DESC_MAX 255
214
215	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
216	#define PR_CREATE_TRACE(handle,qName,rName,description)\
217	(handle) = PR_CreateTrace((qName),(rName),(description))
218	#else
219	#define PR_CREATE_TRACE(handle,qName,rName,description)
220	#endif
221
222	NSPR_API(PRTraceHandle)
223	PR_CreateTrace(
224	const char qName, / QName for this trace handle */
225	const char rName, / RName for this trace handle */
226	const char description / description for this trace handle */
227	);
228
229
230	/* -----------------------------------------------------------------------
231	** FUNCTION: PR_DestroyTrace() -- Destroy a trace handle
232	**
233	** DESCRIPTION:
234	** PR_DestroyTrace() removes the referenced trace handle and
235	** associated QName, RName and description data from the Trace
236	** Facility.
237	**
238	** INPUTS: handle. A PRTraceHandle
239	**
240	** OUTPUTS:
241	** The trace handle is unregistered.
242	** The QName, RName and description are removed.
243	**
244	** RETURNS: void
245	**
246	** RESTRICTIONS:
247	**
248	*/
249	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
250	#define PR_DESTROY_TRACE(handle)\
251	PR_DestroyTrace((handle))
252	#else
253	#define PR_DESTROY_TRACE(handle)
254	#endif
255
256	NSPR_API(void)
257	PR_DestroyTrace(
258	PRTraceHandle handle /* Handle to be destroyed */
259	);
260
261
262	/* -----------------------------------------------------------------------
263	** FUNCTION: PR_Trace() -- Make a trace entry in the in-memory trace
264	**
265	** DESCRIPTION:
266	** PR_Trace() makes an entry in the in-memory trace buffer for
267	** the referenced trace handle. The next logically available
268	** PRTraceEntry is used; when the next trace entry would overflow
269	** the trace table, the table wraps.
270	**
271	** PR_Trace() for a specific trace handle may be disabled by
272	** calling PR_SetTraceOption() specifying PRTraceDisable for the
273	** trace handle to be disabled.
274	**
275	** INPUTS:
276	** handle: PRTraceHandle. The trace handle for this trace.
277	**
278	** userData[0..7]: unsigned 32bit integers. user supplied data
279	** that is copied into the PRTraceEntry
280	**
281	** OUTPUTS:
282	** A PRTraceEntry is (conditionally) formatted in the in-memory
283	** trace buffer.
284	**
285	** RETURNS: void.
286	**
287	** RESTRICTIONS:
288	**
289	*/
290	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
291	#define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)\
292	PR_Trace((handle),(ud0),(ud1),(ud2),(ud3),(ud4),(ud5),(ud6),(ud7))
293	#else
294	#define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)
295	#endif
296
297	NSPR_API(void)
298	PR_Trace(
299	PRTraceHandle handle, /* use this trace handle */
300	PRUint32 userData0, /* User supplied data word 0 */
301	PRUint32 userData1, /* User supplied data word 1 */
302	PRUint32 userData2, /* User supplied data word 2 */
303	PRUint32 userData3, /* User supplied data word 3 */
304	PRUint32 userData4, /* User supplied data word 4 */
305	PRUint32 userData5, /* User supplied data word 5 */
306	PRUint32 userData6, /* User supplied data word 6 */
307	PRUint32 userData7 /* User supplied data word 7 */
308	);
309
310	/* -----------------------------------------------------------------------
311	** FUNCTION: PR_SetTraceOption() -- Control the Trace Facility
312	**
313	** DESCRIPTION:
314	** PR_SetTraceOption() controls the Trace Facility. Depending on
315	** command and value, attributes of the Trace Facility may be
316	** changed.
317	**
318	** INPUTS:
319	** command: An enumerated value in the set of PRTraceOption.
320	** value: pointer to the data to be set. Type of the data is
321	** dependent on command; for each value of command, the type
322	** and meaning of dereferenced value is shown.
323	**
324	** PRTraceBufSize: unsigned long: the size of the trace buffer,
325	** in bytes.
326	**
327	** PRTraceEnable: PRTraceHandle. The trace handle to be
328	** enabled.
329	**
330	** PRTraceDisable: PRTraceHandle. The trace handle to be
331	** disabled.
332	**
333	** PRTraceSuspend: void. value must be NULL. All tracing is
334	** suspended.
335	**
336	** PRTraceResume: void. value must be NULL. Tracing for all
337	** previously enabled, prior to a PRTraceSuspend, is resumed.
338	**
339	** PRTraceStopRecording: void. value must be NULL. If recording
340	(see: PR_RecordTraceEntries()) is being done,
341	** PRTraceStopRecording causes PR_RecordTraceEntries() to return
342	** to its caller. If recording is not being done, this function
343	** has no effect.
344	**
345	** PRTraceSuspendRecording: void. Must be NULL. If recording is
346	** being done, PRTraceSuspendRecording causes further writes to
347	** the trace file to be suspended. Data in the in-memory
348	** trace buffer that would ordinarily be written to the
349	** trace file will not be written. Trace entries will continue
350	** to be entered in the in-memory buffer. If the Trace Facility
351	** recording is already in a suspended state, the call has no
352	** effect.
353	**
354	** PRTraceResumeRecording: void. value must be NULL. If
355	** recording for the Trace Facility has been previously been
356	** suspended, this causes recording to resume. Recording resumes
357	** with the next in-memory buffer segment that would be written
358	** if trace recording had not been suspended. If recording is
359	** not currently suspended, the call has no effect.
360	**
361	** PRTraceLockHandles: void. value must be NULL. Locks the
362	** trace handle lock. While the trace handle lock is held,
363	** calls to PR_CreateTrace() will block until the lock is
364	** released.
365	**
366	** PRTraceUnlockHandles: void. value must be NULL. Unlocks the
367	** trace handle lock.
368	**
369	** OUTPUTS:
370	** The operation of the Trace Facility may be changed.
371	**
372	** RETURNS: void
373	**
374	** RESTRICTIONS:
375	**
376	*/
377	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
378	#define PR_SET_TRACE_OPTION(command,value)\
379	PR_SetTraceOption((command),(value))
380	#else
381	#define PR_SET_TRACE_OPTION(command,value)
382	#endif
383
384	NSPR_API(void)
385	PR_SetTraceOption(
386	PRTraceOption command, /* One of the enumerated values */
387	void value / command value or NULL */
388	);
389
390
391	/* -----------------------------------------------------------------------
392	** FUNCTION: PR_GetTraceOption() -- Retrieve settings from the Trace Facility
393	**
394	** DESCRIPTION:
395	** PR_GetTraceOption() retrieves the current setting of the
396	** Trace Facility control depending on command.
397	**
398	**
399	** PRTraceBufSize: unsigned long: the size of the trace buffer,
400	** in bytes.
401	**
402	**
403	** INPUTS:
404	** command: one of the enumerated values in PRTraceOptions
405	** valid for PR_GetTraceOption().
406	**
407	** OUTPUTS:
408	** dependent on command.
409	**
410	** RETURNS: void
411	**
412	** RESTRICTIONS:
413	**
414	*/
415	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
416	#define PR_GET_TRACE_OPTION(command,value)\
417	PR_GetTraceOption((command),(value))
418	#else
419	#define PR_GET_TRACE_OPTION(command,value)
420	#endif
421
422	NSPR_API(void)
423	PR_GetTraceOption(
424	PRTraceOption command, /* One of the enumerated values */
425	void value / command value or NULL */
426	);
427
428	/* -----------------------------------------------------------------------
429	** FUNCTION: PR_GetTraceHandleFromName() -- Retrieve an existing
430	** handle by name.
431	**
432	** DESCRIPTION:
433	** PR_GetTraceHandleFromName() retreives an existing tracehandle
434	** using the name specified by qName and rName.
435	**
436	** INPUTS:
437	** qName: pointer to string. QName for this trace handle.
438	**
439	** rName: pointer to string. RName for this trace handle.
440	**
441	**
442	** OUTPUTS: returned.
443	**
444	** RETURNS:
445	** PRTraceHandle associated with qName and rName or NULL when
446	** there is no match.
447	**
448	** RESTRICTIONS:
449	**
450	*/
451	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
452	#define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)\
453	(handle) = PR_GetTraceHandleFromName((qName),(rName))
454	#else
455	#define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)
456	#endif
457
458	NSPR_API(PRTraceHandle)
459	PR_GetTraceHandleFromName(
460	const char qName, / QName search argument */
461	const char rName / RName search argument */
462	);
463
464	/* -----------------------------------------------------------------------
465	** FUNCTION: PR_GetTraceNameFromHandle() -- Retreive trace name
466	** by bandle.
467	**
468	** DESCRIPTION:
469	** PR_GetTraceNameFromHandle() retreives the existing qName,
470	** rName, and description for the referenced trace handle.
471	**
472	** INPUTS: handle: PRTraceHandle.
473	**
474	** OUTPUTS: pointers to the Trace Facility's copy of qName,
475	** rName and description. ... Don't mess with these values.
476	** They're mine.
477	**
478	** RETURNS: void
479	**
480	** RESTRICTIONS:
481	**
482	*/
483	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
484	#define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)\
485	PR_GetTraceNameFromHandle((handle),(qName),(rName),(description))
486	#else
487	#define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)
488	#endif
489
490	NSPR_API(void)
491	PR_GetTraceNameFromHandle(
492	PRTraceHandle handle, /* handle as search argument */
493	const char *qName, / pointer to associated QName */
494	const char *rName, / pointer to associated RName */
495	const char *description / pointer to associated description */
496	);
497
498	/* -----------------------------------------------------------------------
499	** FUNCTION: PR_FindNextTraceQname() -- Retrieive a QName handle
500	** iterator.
501	**
502	** DESCRIPTION:
503	** PR_FindNextTraceQname() retreives the first or next trace
504	** QName handle, depending on the value of handle, from the trace
505	** database. The PRTraceHandle returned can be used as an
506	** iterator to traverse the QName handles in the Trace database.
507	**
508	** INPUTS:
509	** handle: When NULL, PR_FindNextQname() returns the first QName
510	** handle. When a handle is a valid PRTraceHandle previously
511	** retreived using PR_FindNextQname() the next QName handle is
512	** retreived.
513	**
514	** OUTPUTS: returned.
515	**
516	** RETURNS:
517	** PRTraceHandle or NULL when there are no trace handles.
518	**
519	** RESTRICTIONS:
520	** Iterating thru the trace handles via FindFirst/FindNext
521	** should be done under protection of the trace handle lock.
522	** See: PR_SetTraceOption( PRLockTraceHandles ).
523	**
524	*/
525	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
526	#define PR_FIND_NEXT_TRACE_QNAME(next,handle)\
527	(next) = PR_FindNextTraceQname((handle))
528	#else
529	#define PR_FIND_NEXT_TRACE_QNAME(next,handle)
530	#endif
531
532	NSPR_API(PRTraceHandle)
533	PR_FindNextTraceQname(
534	PRTraceHandle handle
535	);
536
537
538	/* -----------------------------------------------------------------------
539	** FUNCTION: PR_FindNextTraceRname() -- Retrieive an RName handle
540	** iterator.
541	**
542	** DESCRIPTION:
543	** PR_FindNextTraceRname() retreives the first or next trace
544	** RName handle, depending on the value of handle, from the trace
545	** database. The PRTraceHandle returned can be used as an
546	** iterator to traverse the RName handles in the Trace database.
547	**
548	** INPUTS:
549	** rhandle: When NULL, PR_FindNextRname() returns the first
550	** RName handle. When a handle is a valid PRTraceHandle
551	** previously retreived using PR_FindNextRname() the next RName
552	** handle is retreived.
553	** qhandle: A valid PRTraceHandle retruned from a previous call
554	** to PR_FIND_NEXT_TRACE_QNAME().
555	**
556	** OUTPUTS: returned.
557	**
558	** RETURNS:
559	** PRTraceHandle or NULL when there are no trace handles.
560	**
561	** RESTRICTIONS:
562	** Iterating thru the trace handles via FindNext should be done
563	** under protection of the trace handle lock. See: (
564	** PR_SetTraceOption( PRLockTraceHandles ).
565	**
566	*/
567	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
568	#define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)\
569	(next) = PR_FindNextTraceRname((rhandle),(qhandle))
570	#else
571	#define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)
572	#endif
573
574	NSPR_API(PRTraceHandle)
575	PR_FindNextTraceRname(
576	PRTraceHandle rhandle,
577	PRTraceHandle qhandle
578	);
579
580	/* -----------------------------------------------------------------------
581	** FUNCTION: PR_RecordTraceEntries() -- Write trace entries to external media
582	**
583	** DESCRIPTION:
584	** PR_RecordTraceEntries() causes entries in the in-memory trace
585	** buffer to be written to external media.
586	**
587	** When PR_RecordTraceEntries() is called from an application
588	** thread, the function appears to block until another thread
589	** calls PR_SetTraceOption() with the PRTraceStopRecording
590	** option. This suggests that PR_RecordTraceEntries() should be
591	** called from a user supplied thread whose only job is to
592	** record trace entries.
593	**
594	** The environment variable NSPR_TRACE_LOG controls the operation
595	** of this function. When NSPR_TRACE_LOG is not defined in the
596	** environment, no recording of trace entries occurs. When
597	** NSPR_TRACE_LOG is defined, the value of its definition must be
598	** the filename of the file to receive the trace entry buffer.
599	**
600	** PR_RecordTraceEntries() attempts to record the in-memory
601	** buffer to a file, subject to the setting of the environment
602	** variable NSPR_TRACE_LOG. It is possible because of system
603	** load, the thread priority of the recording thread, number of
604	** active trace records being written over time, and other
605	** variables that some trace records can be lost. ... In other
606	** words: don't bet the farm on getting everything.
607	**
608	** INPUTS: none
609	**
610	** OUTPUTS: none
611	**
612	** RETURNS: PR_STATUS
613	** PR_SUCCESS no errors were found.
614	** PR_FAILURE errors were found.
615	**
616	** RESTRICTIONS:
617	** Only one thread can call PR_RecordTraceEntries() within a
618	** process.
619	**
620	** On error, PR_RecordTraceEntries() may return prematurely.
621	**
622	*/
623	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
624	#define PR_RECORD_TRACE_ENTRIES()\
625	PR_RecordTraceEntries()
626	#else
627	#define PR_RECORD_TRACE_ENTRIES()
628	#endif
629
630	NSPR_API(void)
631	PR_RecordTraceEntries(
632	void
633	);
634
635	/* -----------------------------------------------------------------------
636	** FUNCTION: PR_GetTraceEntries() -- Retreive trace entries from
637	** the Trace Facility
638	**
639	** DESCRIPTION:
640	** PR_GetTraceEntries() retreives trace entries from the Trace
641	** Facility. Up to count trace entries are copied from the Trace
642	** Facility into buffer. Only those trace entries that have not
643	** been copied via a previous call to PR_GetTraceEntries() are
644	** copied. The actual number copied is placed in the PRInt32
645	** variable pointed to by found.
646	**
647	** If more than count trace entries have entered the Trace
648	** Facility since the last call to PR_GetTraceEntries()
649	** a lost data condition is returned. In this case, the most
650	** recent count trace entries are copied into buffer and found is
651	** set to count.
652	**
653	** INPUTS:
654	** count. The number of trace entries to be copied into buffer.
655	**
656	**
657	** OUTPUTS:
658	** buffer. An array of PRTraceEntries. The buffer is supplied
659	** by the caller.
660	**
661	** found: 32bit signed integer. The number of PRTraceEntries
662	** actually copied. found is always less than or equal to count.
663	**
664	** RETURNS:
665	** zero when there is no lost data.
666	** non-zero when some PRTraceEntries have been lost.
667	**
668	** RESTRICTIONS:
669	** This is a real performance pig. The copy out operation is bad
670	** enough, but depending on then frequency of calls to the
671	** function, serious performance impact to the operating
672	** application may be realized. ... YMMV.
673	**
674	*/
675	#if defined (DEBUG) \|\| defined (FORCE_NSPR_TRACE)
676	#define PR_GET_TRACE_ENTRIES(buffer,count,found)\
677	PR_GetTraceEntries((buffer),(count),(found))
678	#else
679	#define PR_GET_TRACE_ENTRIES(buffer,count,found)
680	#endif
681
682	NSPR_API(PRIntn)
683	PR_GetTraceEntries(
684	PRTraceEntry buffer, / where to write output */
685	PRInt32 count, /* number to get */
686	PRInt32 found / number you got */
687	);
688
689	PR_END_EXTERN_C
690
691	#endif /* prtrace_h___ */
692

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/xpcom18a4/nsprpub/pr/include/prtrace.h@ 50011

Download in other formats: