prtrace.h
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:23k
源码类别:

PlugIns编程

开发平台:

Visual C++

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