15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The contents of this file are subject to the Mozilla Public 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * License Version 1.1 (the "License"); you may not use this file 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * except in compliance with the License. You may obtain a copy of 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the License at http://www.mozilla.org/MPL/ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Software distributed under the License is distributed on an "AS 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * implied. See the License for the specific language governing 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * rights and limitations under the License. 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The Original Code is the Netscape Portable Runtime (NSPR). 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The Initial Developer of the Original Code is Netscape 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Communications Corporation. Portions created by Netscape are 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Copyright (C) 1998-2000 Netscape Communications Corporation. All 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Rights Reserved. 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Contributor(s): 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Alternatively, the contents of this file may be used under the 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * terms of the GNU General Public License Version 2 or later (the 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * "GPL"), in which case the provisions of the GPL are applicable 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * instead of those above. If you wish to allow use of your 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * version of this file only under the terms of the GPL and not to 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * allow others to use your version of this file under the MPL, 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * indicate your decision by deleting the provisions above and 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * replace them with the notice and other provisions required by 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the GPL. If you do not delete the provisions above, a recipient 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * may use your version of this file under either the MPL or the 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * GPL. 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef prtrace_h___ 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define prtrace_h___ 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** prtrace.h -- NSPR's Trace Facility. 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** The Trace Facility provides a means to trace application 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** program events within a process. When implementing an 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** application program an engineer may insert a "Trace" function 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** call, passing arguments to be traced. The "Trace" function 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** combines the user trace data with identifying data and 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** writes this data in time ordered sequence into a circular 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** in-memory buffer; when the buffer fills, it wraps. 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Functions are provided to set and/or re-configure the size of 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** the trace buffer, control what events are recorded in the 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** buffer, enable and disable tracing based on specific user 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** supplied data and other control functions. Methods are provided 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** to record the trace entries in the in-memory trace buffer to 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** a file. 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Tracing may cause a performance degredation to the application 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** depending on the number and placement of calls to the tracing 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** facility. When tracing is compiled in and all tracing is 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** disabled via the runtime controls, the overhead should be 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** minimal. ... Famous last words, eh? 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** When DEBUG is defined at compile time, the Trace Facility is 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** compiled as part of NSPR and any application using NSPR's 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** header files will have tracing compiled in. When DEBUG is not 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** defined, the Trace Facility is not compiled into NSPR nor 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** exported in its header files. If the Trace Facility is 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** desired in a non-debug build, then FORCE_NSPR_TRACE may be 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** defined at compile time for both the optimized build of NSPR 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** and the application. NSPR and any application using NSPR's 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Trace Facility must be compiled with the same level of trace 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** conditioning or unresolved references may be realized at link 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** time. 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** For any of the Trace Facility methods that requires a trace 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** handle as an input argument, the caller must ensure that the 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** trace handle argument is valid. An invalid trace handle 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** argument may cause unpredictable results. 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Trace Facility methods are thread-safe and SMP safe. 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Users of the Trace Facility should use the defined macros to 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** invoke trace methods, not the function calls directly. e.g. 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_TRACE( h1,0,1,2, ...); not PR_Trace(h1,0,1,2, ...); 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Application designers should be aware of the effects of 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** debug and optimized build differences when using result of the 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Trace Facility macros in expressions. 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** See Also: prcountr.h 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** /lth. 08-Jun-1998. 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "prtypes.h" 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "prthread.h" 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "prtime.h" 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)PR_BEGIN_EXTERN_C 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Opaque type for the trace handle 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** ... Don't even think about looking in here. 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef void * PRTraceHandle; 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceEntry -- A trace entry in the in-memory trace buffer 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** looks like this. 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRTraceEntry 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles){ 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRThread *thread; /* The thread creating the trace entry */ 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceHandle handle; /* PRTraceHandle creating the trace entry */ 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTime time; /* Value of PR_Now() at time of trace entry */ 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRUint32 userData[8]; /* user supplied trace data */ 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} PRTraceEntry; 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceOption -- command operands to 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_[Set|Get]TraceOption(). See descriptive meanings there. 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef enum PRTraceOption 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles){ 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceBufSize, 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceEnable, 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceDisable, 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceSuspend, 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceResume, 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceSuspendRecording, 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceResumeRecording, 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceLockHandles, 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceUnLockHandles, 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceStopRecording 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} PRTraceOption; 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_DEFINE_TRACE() -- Define a PRTraceHandle 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: PR_DEFINE_TRACE() is used to define a trace 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** handle. 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_DEFINE_TRACE(name) PRTraceHandle name 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_INIT_TRACE_HANDLE() -- Set the value of a PRTraceHandle 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_INIT_TRACE_HANDLE() sets the value of a PRTraceHandle 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** to value. e.g. PR_INIT_TRACE_HANDLE( myHandle, NULL ); 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_INIT_TRACE_HANDLE(handle,value)\ 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) (handle) = (PRCounterHandle)(value) 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_INIT_TRACE_HANDLE(handle,value) 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_CreateTrace() -- Create a trace handle 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_CreateTrace() creates a new trace handle. Tracing is 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** enabled for this handle when it is created. The trace handle 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** is intended for use in other Trace Facility calls. 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_CreateTrace() registers the QName, RName and description 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** data so that this data can be retrieved later. 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** qName: pointer to string. QName for this trace handle. 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** rName: pointer to string. RName for this trace handle. 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** description: pointer to string. Descriptive data about this 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** trace handle. 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Creates the trace handle. 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Registers the QName and RName with the trace facility. 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: 1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceHandle 1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** qName is limited to 31 characters. 1915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** rName is limited to 31 characters. 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** description is limited to 255 characters. 1935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 1945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PRTRACE_NAME_MAX 31 1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PRTRACE_DESC_MAX 255 1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 1995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_CREATE_TRACE(handle,qName,rName,description)\ 2005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) (handle) = PR_CreateTrace((qName),(rName),(description)) 2015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 2025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_CREATE_TRACE(handle,qName,rName,description) 2035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 2045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(PRTraceHandle) 2065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_CreateTrace( 2075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char *qName, /* QName for this trace handle */ 2085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char *rName, /* RName for this trace handle */ 2095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char *description /* description for this trace handle */ 2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_DestroyTrace() -- Destroy a trace handle 2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 2175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_DestroyTrace() removes the referenced trace handle and 2185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** associated QName, RName and description data from the Trace 2195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Facility. 2205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: handle. A PRTraceHandle 2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: 2245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** The trace handle is unregistered. 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** The QName, RName and description are removed. 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: void 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_DESTROY_TRACE(handle)\ 2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_DestroyTrace((handle)) 2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 2365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_DESTROY_TRACE(handle) 2375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(void) 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_DestroyTrace( 2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceHandle handle /* Handle to be destroyed */ 2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_Trace() -- Make a trace entry in the in-memory trace 2475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 2495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_Trace() makes an entry in the in-memory trace buffer for 2505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** the referenced trace handle. The next logically available 2515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceEntry is used; when the next trace entry would overflow 2525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** the trace table, the table wraps. 2535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_Trace() for a specific trace handle may be disabled by 2555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** calling PR_SetTraceOption() specifying PRTraceDisable for the 2565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** trace handle to be disabled. 2575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: 2595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** handle: PRTraceHandle. The trace handle for this trace. 2605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** userData[0..7]: unsigned 32bit integers. user supplied data 2625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** that is copied into the PRTraceEntry 2635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: 2655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** A PRTraceEntry is (conditionally) formatted in the in-memory 2665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** trace buffer. 2675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: void. 2695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 2715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 2735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 2745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7)\ 2755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_Trace((handle),(ud0),(ud1),(ud2),(ud3),(ud4),(ud5),(ud6),(ud7)) 2765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 2775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_TRACE(handle,ud0,ud1,ud2,ud3,ud4,ud5,ud6,ud7) 2785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 2795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(void) 2815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_Trace( 2825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceHandle handle, /* use this trace handle */ 2835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRUint32 userData0, /* User supplied data word 0 */ 2845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRUint32 userData1, /* User supplied data word 1 */ 2855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRUint32 userData2, /* User supplied data word 2 */ 2865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRUint32 userData3, /* User supplied data word 3 */ 2875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRUint32 userData4, /* User supplied data word 4 */ 2885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRUint32 userData5, /* User supplied data word 5 */ 2895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRUint32 userData6, /* User supplied data word 6 */ 2905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRUint32 userData7 /* User supplied data word 7 */ 2915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 2925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 2945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_SetTraceOption() -- Control the Trace Facility 2955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 2965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 2975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_SetTraceOption() controls the Trace Facility. Depending on 2985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** command and value, attributes of the Trace Facility may be 2995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** changed. 3005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: 3025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** command: An enumerated value in the set of PRTraceOption. 3035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** value: pointer to the data to be set. Type of the data is 3045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** dependent on command; for each value of command, the type 3055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** and meaning of dereferenced value is shown. 3065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceBufSize: unsigned long: the size of the trace buffer, 3085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** in bytes. 3095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceEnable: PRTraceHandle. The trace handle to be 3115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** enabled. 3125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceDisable: PRTraceHandle. The trace handle to be 3145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** disabled. 3155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceSuspend: void. value must be NULL. All tracing is 3175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** suspended. 3185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceResume: void. value must be NULL. Tracing for all 3205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** previously enabled, prior to a PRTraceSuspend, is resumed. 3215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceStopRecording: void. value must be NULL. If recording 3235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** (see: ** PR_RecordTraceEntries()) is being done, 3245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceStopRecording causes PR_RecordTraceEntries() to return 3255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** to its caller. If recording is not being done, this function 3265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** has no effect. 3275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceSuspendRecording: void. Must be NULL. If recording is 3295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** being done, PRTraceSuspendRecording causes further writes to 3305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** the trace file to be suspended. Data in the in-memory 3315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** trace buffer that would ordinarily be written to the 3325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** trace file will not be written. Trace entries will continue 3335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** to be entered in the in-memory buffer. If the Trace Facility 3345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** recording is already in a suspended state, the call has no 3355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** effect. 3365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceResumeRecording: void. value must be NULL. If 3385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** recording for the Trace Facility has been previously been 3395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** suspended, this causes recording to resume. Recording resumes 3405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** with the next in-memory buffer segment that would be written 3415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** if trace recording had not been suspended. If recording is 3425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** not currently suspended, the call has no effect. 3435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceLockHandles: void. value must be NULL. Locks the 3455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** trace handle lock. While the trace handle lock is held, 3465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** calls to PR_CreateTrace() will block until the lock is 3475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** released. 3485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceUnlockHandles: void. value must be NULL. Unlocks the 3505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** trace handle lock. 3515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: 3535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** The operation of the Trace Facility may be changed. 3545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: void 3565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 3585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 3605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 3615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_SET_TRACE_OPTION(command,value)\ 3625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_SetTraceOption((command),(value)) 3635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 3645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_SET_TRACE_OPTION(command,value) 3655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 3665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(void) 3685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_SetTraceOption( 3695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceOption command, /* One of the enumerated values */ 3705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void *value /* command value or NULL */ 3715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 3725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 3755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_GetTraceOption() -- Retrieve settings from the Trace Facility 3765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 3785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_GetTraceOption() retrieves the current setting of the 3795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Trace Facility control depending on command. 3805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceBufSize: unsigned long: the size of the trace buffer, 3835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** in bytes. 3845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: 3875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** command: one of the enumerated values in PRTraceOptions 3885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** valid for PR_GetTraceOption(). 3895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: 3915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** dependent on command. 3925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: void 3945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 3965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 3975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 3985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 3995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_GET_TRACE_OPTION(command,value)\ 4005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_GetTraceOption((command),(value)) 4015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 4025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_GET_TRACE_OPTION(command,value) 4035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 4045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(void) 4065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_GetTraceOption( 4075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceOption command, /* One of the enumerated values */ 4085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void *value /* command value or NULL */ 4095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 4105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 4125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_GetTraceHandleFromName() -- Retrieve an existing 4135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** handle by name. 4145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 4165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_GetTraceHandleFromName() retreives an existing tracehandle 4175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** using the name specified by qName and rName. 4185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: 4205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** qName: pointer to string. QName for this trace handle. 4215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** rName: pointer to string. RName for this trace handle. 4235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: returned. 4265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: 4285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceHandle associated with qName and rName or NULL when 4295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** there is no match. 4305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 4325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 4345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 4355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName)\ 4365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) (handle) = PR_GetTraceHandleFromName((qName),(rName)) 4375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 4385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_GET_TRACE_HANDLE_FROM_NAME(handle,qName,rName) 4395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 4405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(PRTraceHandle) 4425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_GetTraceHandleFromName( 4435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char *qName, /* QName search argument */ 4445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char *rName /* RName search argument */ 4455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 4465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 4485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_GetTraceNameFromHandle() -- Retreive trace name 4495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** by bandle. 4505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 4525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_GetTraceNameFromHandle() retreives the existing qName, 4535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** rName, and description for the referenced trace handle. 4545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: handle: PRTraceHandle. 4565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: pointers to the Trace Facility's copy of qName, 4585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** rName and description. ... Don't mess with these values. 4595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** They're mine. 4605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: void 4625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 4645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 4665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 4675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description)\ 4685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_GetTraceNameFromHandle((handle),(qName),(rName),(description)) 4695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 4705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_GET_TRACE_NAME_FROM_HANDLE(handle,qName,rName,description) 4715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 4725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(void) 4745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_GetTraceNameFromHandle( 4755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceHandle handle, /* handle as search argument */ 4765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char **qName, /* pointer to associated QName */ 4775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char **rName, /* pointer to associated RName */ 4785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char **description /* pointer to associated description */ 4795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 4805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 4825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_FindNextTraceQname() -- Retrieive a QName handle 4835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** iterator. 4845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 4865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_FindNextTraceQname() retreives the first or next trace 4875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** QName handle, depending on the value of handle, from the trace 4885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** database. The PRTraceHandle returned can be used as an 4895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** iterator to traverse the QName handles in the Trace database. 4905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: 4925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** handle: When NULL, PR_FindNextQname() returns the first QName 4935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** handle. When a handle is a valid PRTraceHandle previously 4945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** retreived using PR_FindNextQname() the next QName handle is 4955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** retreived. 4965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: returned. 4985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 4995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: 5005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceHandle or NULL when there are no trace handles. 5015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 5035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Iterating thru the trace handles via FindFirst/FindNext 5045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** should be done under protection of the trace handle lock. 5055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** See: PR_SetTraceOption( PRLockTraceHandles ). 5065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 5085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 5095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_FIND_NEXT_TRACE_QNAME(next,handle)\ 5105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) (next) = PR_FindNextTraceQname((handle)) 5115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 5125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_FIND_NEXT_TRACE_QNAME(next,handle) 5135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 5145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(PRTraceHandle) 5165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_FindNextTraceQname( 5175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceHandle handle 5185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 5195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 5225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_FindNextTraceRname() -- Retrieive an RName handle 5235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** iterator. 5245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 5265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_FindNextTraceRname() retreives the first or next trace 5275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RName handle, depending on the value of handle, from the trace 5285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** database. The PRTraceHandle returned can be used as an 5295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** iterator to traverse the RName handles in the Trace database. 5305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: 5325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** rhandle: When NULL, PR_FindNextRname() returns the first 5335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RName handle. When a handle is a valid PRTraceHandle 5345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** previously retreived using PR_FindNextRname() the next RName 5355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** handle is retreived. 5365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** qhandle: A valid PRTraceHandle retruned from a previous call 5375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** to PR_FIND_NEXT_TRACE_QNAME(). 5385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: returned. 5405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: 5425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PRTraceHandle or NULL when there are no trace handles. 5435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 5455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Iterating thru the trace handles via FindNext should be done 5465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** under protection of the trace handle lock. See: ( 5475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_SetTraceOption( PRLockTraceHandles ). 5485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 5505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 5515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle)\ 5525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) (next) = PR_FindNextTraceRname((rhandle),(qhandle)) 5535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 5545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_FIND_NEXT_TRACE_RNAME(next,rhandle,qhandle) 5555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 5565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(PRTraceHandle) 5585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_FindNextTraceRname( 5595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceHandle rhandle, 5605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceHandle qhandle 5615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 5625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 5645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_RecordTraceEntries() -- Write trace entries to external media 5655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 5675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_RecordTraceEntries() causes entries in the in-memory trace 5685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** buffer to be written to external media. 5695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** When PR_RecordTraceEntries() is called from an application 5715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** thread, the function appears to block until another thread 5725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** calls PR_SetTraceOption() with the PRTraceStopRecording 5735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** option. This suggests that PR_RecordTraceEntries() should be 5745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** called from a user supplied thread whose only job is to 5755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** record trace entries. 5765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** The environment variable NSPR_TRACE_LOG controls the operation 5785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** of this function. When NSPR_TRACE_LOG is not defined in the 5795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** environment, no recording of trace entries occurs. When 5805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** NSPR_TRACE_LOG is defined, the value of its definition must be 5815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** the filename of the file to receive the trace entry buffer. 5825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_RecordTraceEntries() attempts to record the in-memory 5845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** buffer to a file, subject to the setting of the environment 5855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** variable NSPR_TRACE_LOG. It is possible because of system 5865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** load, the thread priority of the recording thread, number of 5875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** active trace records being written over time, and other 5885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** variables that some trace records can be lost. ... In other 5895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** words: don't bet the farm on getting everything. 5905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: none 5925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: none 5945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: PR_STATUS 5965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_SUCCESS no errors were found. 5975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_FAILURE errors were found. 5985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 5995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 6005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Only one thread can call PR_RecordTraceEntries() within a 6015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** process. 6025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** On error, PR_RecordTraceEntries() may return prematurely. 6045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 6065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 6075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_RECORD_TRACE_ENTRIES()\ 6085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_RecordTraceEntries() 6095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 6105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_RECORD_TRACE_ENTRIES() 6115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 6125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(void) 6145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_RecordTraceEntries( 6155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void 6165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 6175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* ----------------------------------------------------------------------- 6195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** FUNCTION: PR_GetTraceEntries() -- Retreive trace entries from 6205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** the Trace Facility 6215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** DESCRIPTION: 6235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** PR_GetTraceEntries() retreives trace entries from the Trace 6245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Facility. Up to count trace entries are copied from the Trace 6255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Facility into buffer. Only those trace entries that have not 6265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** been copied via a previous call to PR_GetTraceEntries() are 6275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** copied. The actual number copied is placed in the PRInt32 6285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** variable pointed to by found. 6295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** If more than count trace entries have entered the Trace 6315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Facility since the last call to PR_GetTraceEntries() 6325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** a lost data condition is returned. In this case, the most 6335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** recent count trace entries are copied into buffer and found is 6345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** set to count. 6355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** INPUTS: 6375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** count. The number of trace entries to be copied into buffer. 6385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** OUTPUTS: 6415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** buffer. An array of PRTraceEntries. The buffer is supplied 6425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** by the caller. 6435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** found: 32bit signed integer. The number of PRTraceEntries 6455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** actually copied. found is always less than or equal to count. 6465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RETURNS: 6485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** zero when there is no lost data. 6495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** non-zero when some PRTraceEntries have been lost. 6505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** RESTRICTIONS: 6525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** This is a real performance pig. The copy out operation is bad 6535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** enough, but depending on then frequency of calls to the 6545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** function, serious performance impact to the operating 6555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** application may be realized. ... YMMV. 6565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** 6575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 6585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined (DEBUG) || defined (FORCE_NSPR_TRACE) 6595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_GET_TRACE_ENTRIES(buffer,count,found)\ 6605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_GetTraceEntries((buffer),(count),(found)) 6615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 6625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PR_GET_TRACE_ENTRIES(buffer,count,found) 6635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 6645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)NSPR_API(PRIntn) 6665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PR_GetTraceEntries( 6675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRTraceEntry *buffer, /* where to write output */ 6685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRInt32 count, /* number to get */ 6695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRInt32 *found /* number you got */ 6705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)); 6715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)PR_END_EXTERN_C 6735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif /* prtrace_h___ */ 6755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 676