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

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 prcountr_h___
  38. #define prcountr_h___
  39. /*----------------------------------------------------------------------------
  40. ** prcountr.h -- NSPR Instrumentation counters
  41. **
  42. ** The NSPR Counter Feature provides a means to "count
  43. ** something." Counters can be dynamically defined, incremented,
  44. ** decremented, set, and deleted under application program
  45. ** control.
  46. **                     
  47. ** The Counter Feature is intended to be used as instrumentation,                  
  48. ** not as operational data. If you need a counter for operational                  
  49. ** data, use native integral types.                                                
  50. **                     
  51. ** Counters are 32bit unsigned intergers. On overflow, a counter                   
  52. ** will wrap. No exception is recognized or reported.                              
  53. **                                                                                 
  54. ** A counter can be dynamically created using a two level naming
  55. ** convention. A "handle" is returned when the counter is
  56. ** created. The counter can subsequently be addressed by its
  57. ** handle. An API is provided to get an existing counter's handle
  58. ** given the names with  which it was originally created. 
  59. ** Similarly, a counter's name can be retrieved given its handle.
  60. ** 
  61. ** The counter naming convention is a two-level hierarchy. The
  62. ** QName is the higher level of the hierarchy; RName is the
  63. ** lower level. RNames can be thought of as existing within a
  64. ** QName. The same RName can exist within multiple QNames. QNames
  65. ** are unique. The NSPR Counter is not a near-zero overhead
  66. ** feature. Application designers should be aware of 
  67. ** serialization issues when using the Counter API. Creating a
  68. ** counter locks a large asset, potentially causing a stall. This
  69. ** suggest that applications should create counters at component
  70. ** initialization, for example, and not create and destroy them
  71. ** willy-nilly. ... You have been warned.
  72. ** 
  73. ** Incrementing and Adding to counters uses atomic operations.
  74. ** The performance of these operations will vary from platform
  75. ** to platform. On platforms where atomic operations are not
  76. ** supported the overhead may be substantial.
  77. ** 
  78. ** When traversing the counter database with FindNext functions,
  79. ** the instantaneous values of any given counter is that at the
  80. ** moment of extraction. The state of the entire counter database
  81. ** may not be viewed as atomic.
  82. ** 
  83. ** The counter interface may be disabled (No-Op'd) at compile
  84. ** time. When DEBUG is defined at compile time, the Counter
  85. ** Feature is compiled into NSPR and applications invoking it.
  86. ** When DEBUG is not defined, the counter macros compile to
  87. ** nothing. To force the Counter Feature to be compiled into an
  88. ** optimized build, define FORCE_NSPR_COUNTERS at compile time
  89. ** for both NSPR and the application intending to use it.
  90. ** 
  91. ** Application designers should use the macro form of the Counter
  92. ** Feature methods to minimize performance impact in optimized
  93. ** builds. The macros normally compile to nothing on optimized
  94. ** builds.
  95. ** 
  96. ** Application designers should be aware of the effects of
  97. ** debug and optimized build differences when using result of the
  98. ** Counter Feature macros in expressions.
  99. ** 
  100. ** The Counter Feature is thread-safe and SMP safe.
  101. ** 
  102. ** /lth. 09-Jun-1998.
  103. */
  104. #include "prtypes.h"
  105. PR_BEGIN_EXTERN_C
  106. /*
  107. ** Opaque counter handle type.
  108. ** ... don't even think of looking in here.
  109. **
  110. */
  111. typedef void *  PRCounterHandle;
  112. #define PRCOUNTER_NAME_MAX 31
  113. #define PRCOUNTER_DESC_MAX 255
  114. /* -----------------------------------------------------------------------
  115. ** FUNCTION: PR_DEFINE_COUNTER() -- Define a PRCounterHandle
  116. ** 
  117. ** DESCRIPTION: PR_DEFINE_COUNTER() is used to define a counter
  118. ** handle.
  119. ** 
  120. */
  121. #define PR_DEFINE_COUNTER(name) PRCounterHandle name
  122. /* -----------------------------------------------------------------------
  123. ** FUNCTION: PR_INIT_COUNTER_HANDLE() -- Set the value of a PRCounterHandle
  124. ** 
  125. ** DESCRIPTION: 
  126. ** PR_INIT_COUNTER_HANDLE() sets the value of a PRCounterHandle
  127. ** to value.
  128. ** 
  129. */
  130. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  131. #define PR_INIT_COUNTER_HANDLE(handle,value)
  132.     (handle) = (PRCounterHandle)(value)
  133. #else
  134. #define PR_INIT_COUNTER_HANDLE(handle,value)
  135. #endif
  136. /* -----------------------------------------------------------------------
  137. ** FUNCTION: PR_CreateCounter() -- Create a counter
  138. ** 
  139. ** DESCRIPTION: PR_CreateCounter() creates a counter object and
  140. ** initializes it to zero.
  141. ** 
  142. ** The macro form takes as its first argument the name of the
  143. ** PRCounterHandle to receive the handle returned from
  144. ** PR_CreateCounter().
  145. ** 
  146. ** INPUTS:
  147. **  qName: The QName for the counter object. The maximum length
  148. ** of qName is defined by PRCOUNTER_NAME_MAX
  149. ** 
  150. **  rName: The RName for the counter object. The maximum length
  151. ** of qName is defined by PRCOUNTER_NAME_MAX
  152. ** 
  153. **  descrioption: The description of the counter object. The
  154. ** maximum length of description is defined by
  155. ** PRCOUNTER_DESC_MAX.
  156. ** 
  157. ** OUTPUTS:
  158. ** 
  159. ** RETURNS:
  160. **  PRCounterHandle.
  161. ** 
  162. ** RESTRICTIONS:
  163. ** 
  164. */
  165. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  166. #define PR_CREATE_COUNTER(handle,qName,rName,description)
  167.    (handle) = PR_CreateCounter((qName),(rName),(description))
  168. #else
  169. #define PR_CREATE_COUNTER(handle,qName,rName,description)
  170. #endif
  171. NSPR_API(PRCounterHandle) 
  172. PR_CreateCounter( 
  173. const char *qName, 
  174.      const char *rName, 
  175.         const char *description 
  176. );
  177. /* -----------------------------------------------------------------------
  178. ** FUNCTION: PR_DestroyCounter() -- Destroy a counter object.
  179. ** 
  180. ** DESCRIPTION: PR_DestroyCounter() removes a counter and
  181. ** unregisters its handle from the counter database.
  182. ** 
  183. ** INPUTS:
  184. **  handle: the PRCounterHandle of the counter to be destroyed.
  185. ** 
  186. ** OUTPUTS: 
  187. **  The counter is destroyed.
  188. ** 
  189. ** RETURNS: void
  190. ** 
  191. ** RESTRICTIONS:
  192. ** 
  193. */
  194. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  195. #define PR_DESTROY_COUNTER(handle) PR_DestroyCounter((handle))
  196. #else
  197. #define PR_DESTROY_COUNTER(handle)
  198. #endif
  199. NSPR_API(void) 
  200. PR_DestroyCounter( 
  201. PRCounterHandle handle 
  202. );
  203. /* -----------------------------------------------------------------------
  204. ** FUNCTION: PR_GetCounterHandleFromName() -- Retreive a
  205. ** counter's handle give its name.
  206. ** 
  207. ** DESCRIPTION: PR_GetCounterHandleFromName() retreives a
  208. ** counter's handle from the counter database, given the name
  209. ** the counter was originally created with.
  210. ** 
  211. ** INPUTS:
  212. **  qName: Counter's original QName.
  213. **  rName: Counter's original RName.
  214. ** 
  215. ** OUTPUTS:
  216. ** 
  217. ** RETURNS: 
  218. **  PRCounterHandle or PRCounterError.
  219. ** 
  220. ** RESTRICTIONS:
  221. ** 
  222. */
  223. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  224. #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)
  225.     (handle) = PR_GetCounterHandleFromName((qName),(rName))
  226. #else
  227. #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)
  228. #endif
  229. NSPR_API(PRCounterHandle) 
  230. PR_GetCounterHandleFromName( 
  231.      const char *qName, 
  232.      const char *rName 
  233. );
  234. /* -----------------------------------------------------------------------
  235. ** FUNCTION: PR_GetCounterNameFromHandle() -- Retreive a
  236. ** counter's name, given its handle.
  237. ** 
  238. ** DESCRIPTION: PR_GetCounterNameFromHandle() retreives a
  239. ** counter's name given its handle.
  240. ** 
  241. ** INPUTS:
  242. **  qName: Where to store a pointer to qName.
  243. **  rName: Where to store a pointer to rName.
  244. **  description: Where to store a pointer to description.
  245. ** 
  246. ** OUTPUTS: Pointers to the Counter Feature's copies of the names
  247. ** used when the counters were created.
  248. ** 
  249. ** RETURNS: void
  250. ** 
  251. ** RESTRICTIONS:
  252. ** 
  253. */
  254. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  255. #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description)
  256.     PR_GetCounterNameFromHandle((handle),(qName),(rName),(description))
  257. #else
  258. #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description )
  259. #endif
  260. NSPR_API(void) 
  261. PR_GetCounterNameFromHandle( 
  262.      PRCounterHandle handle,  
  263.     const char **qName, 
  264.     const char **rName, 
  265. const char **description 
  266. );
  267. /* -----------------------------------------------------------------------
  268. ** FUNCTION: PR_IncrementCounter() -- Add one to the referenced
  269. ** counter.
  270. ** 
  271. ** DESCRIPTION: Add one to the referenced counter.
  272. ** 
  273. ** INPUTS:
  274. **  handle: The PRCounterHandle of the counter to be incremented
  275. ** 
  276. ** OUTPUTS: The counter is incrementd.
  277. ** 
  278. ** RETURNS: void
  279. ** 
  280. ** RESTRICTIONS:
  281. ** 
  282. */
  283. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  284. #define PR_INCREMENT_COUNTER(handle) PR_IncrementCounter(handle)
  285. #else
  286. #define PR_INCREMENT_COUNTER(handle)
  287. #endif
  288. NSPR_API(void) 
  289. PR_IncrementCounter( 
  290. PRCounterHandle handle
  291. );
  292. /* -----------------------------------------------------------------------
  293. ** FUNCTION: PR_DecrementCounter() -- Subtract one from the
  294. ** referenced counter
  295. ** 
  296. ** DESCRIPTION: Subtract one from the referenced counter.
  297. ** 
  298. ** INPUTS: 
  299. **  handle: The PRCounterHandle of the coutner to be
  300. ** decremented.
  301. ** 
  302. ** OUTPUTS: the counter is decremented.
  303. ** 
  304. ** RETURNS: void
  305. ** 
  306. ** RESTRICTIONS:
  307. ** 
  308. */
  309. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  310. #define PR_DECREMENT_COUNTER(handle) PR_DecrementCounter(handle)
  311. #else
  312. #define PR_DECREMENT_COUNTER(handle)
  313. #endif
  314. NSPR_API(void) 
  315. PR_DecrementCounter( 
  316. PRCounterHandle handle
  317. );
  318. /* -----------------------------------------------------------------------
  319. ** FUNCTION: PR_AddToCounter() -- Add a value to a counter.
  320. ** 
  321. ** DESCRIPTION: Add value to the counter referenced by handle.
  322. ** 
  323. ** INPUTS:
  324. **  handle: the PRCounterHandle of the counter to be added to.
  325. ** 
  326. **  value: the value to be added to the counter.
  327. ** 
  328. ** OUTPUTS: new value for counter.
  329. ** 
  330. ** RETURNS: void
  331. ** 
  332. ** RESTRICTIONS:
  333. ** 
  334. */
  335. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  336. #define PR_ADD_TO_COUNTER(handle,value)
  337.     PR_AddToCounter((handle),(value))
  338. #else
  339. #define PR_ADD_TO_COUNTER(handle,value)
  340. #endif
  341. NSPR_API(void) 
  342. PR_AddToCounter( 
  343.      PRCounterHandle handle, 
  344.     PRUint32 value 
  345. );
  346. /* -----------------------------------------------------------------------
  347. ** FUNCTION: PR_SubtractFromCounter() -- A value is subtracted
  348. ** from a counter.
  349. ** 
  350. ** DESCRIPTION:
  351. ** Subtract a value from a counter.
  352. ** 
  353. ** INPUTS:
  354. **  handle: the PRCounterHandle of the counter to be subtracted
  355. ** from.
  356. ** 
  357. **  value: the value to be subtracted from the counter.
  358. ** 
  359. ** OUTPUTS: new value for counter
  360. ** 
  361. ** RETURNS: void
  362. ** 
  363. ** RESTRICTIONS:
  364. ** 
  365. */
  366. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  367. #define PR_SUBTRACT_FROM_COUNTER(handle,value)
  368.     PR_SubtractFromCounter((handle),(value))
  369. #else
  370. #define PR_SUBTRACT_FROM_COUNTER(handle,value)
  371. #endif
  372. NSPR_API(void) 
  373. PR_SubtractFromCounter( 
  374.      PRCounterHandle handle, 
  375.     PRUint32 value 
  376. );
  377. /* -----------------------------------------------------------------------
  378. ** FUNCTION: PR_GetCounter() -- Retreive the value of a counter
  379. ** 
  380. ** DESCRIPTION:
  381. ** Retreive the value of a counter.
  382. ** 
  383. ** INPUTS:
  384. **  handle: the PR_CounterHandle of the counter to be retreived
  385. ** 
  386. ** OUTPUTS:
  387. ** 
  388. ** RETURNS: The value of the referenced counter
  389. ** 
  390. ** RESTRICTIONS:
  391. ** 
  392. */
  393. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  394. #define PR_GET_COUNTER(counter,handle)
  395.     (counter) = PR_GetCounter((handle))
  396. #else
  397. #define PR_GET_COUNTER(counter,handle) 0
  398. #endif
  399. NSPR_API(PRUint32) 
  400. PR_GetCounter( 
  401. PRCounterHandle handle 
  402. );
  403. /* -----------------------------------------------------------------------
  404. ** FUNCTION: PR_SetCounter() -- Replace the content of counter
  405. ** with value.
  406. ** 
  407. ** DESCRIPTION: The contents of the referenced counter are
  408. ** replaced by value.
  409. ** 
  410. ** INPUTS:
  411. **  handle: the PRCounterHandle of the counter whose contents
  412. ** are to be replaced.
  413. ** 
  414. **  value: the new value of the counter.
  415. ** 
  416. ** OUTPUTS:
  417. ** 
  418. ** RETURNS: void
  419. ** 
  420. ** RESTRICTIONS:
  421. ** 
  422. */
  423. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  424. #define PR_SET_COUNTER(handle,value) PR_SetCounter((handle),(value))
  425. #else
  426. #define PR_SET_COUNTER(handle,value)
  427. #endif
  428. NSPR_API(void) 
  429. PR_SetCounter( 
  430. PRCounterHandle handle, 
  431. PRUint32 value 
  432. );
  433. /* -----------------------------------------------------------------------
  434. ** FUNCTION: PR_FindNextCounterQname() -- Retreive the next QName counter
  435. ** handle iterator
  436. ** 
  437. ** DESCRIPTION:
  438. ** PR_FindNextCounterQname() retreives the first or next Qname
  439. ** the counter data base, depending on the value of handle. When
  440. ** handle is NULL, the function attempts to retreive the first
  441. ** QName handle in the database. When handle is a handle previosly
  442. ** retreived QName handle, then the function attempts to retreive
  443. ** the next QName handle.
  444. ** 
  445. ** INPUTS: 
  446. **  handle: PRCounterHandle or NULL.
  447. ** 
  448. ** OUTPUTS: returned
  449. ** 
  450. ** RETURNS: PRCounterHandle or NULL when no more QName counter
  451. ** handles are present.
  452. ** 
  453. ** RESTRICTIONS:
  454. **  A concurrent PR_CreateCounter() or PR_DestroyCounter() may
  455. ** cause unpredictable results.
  456. ** 
  457. ** A PRCounterHandle returned from this function may only be used
  458. ** in another PR_FindNextCounterQname() function call; other
  459. ** operations may cause unpredictable results.
  460. ** 
  461. */
  462. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  463. #define PR_FIND_NEXT_COUNTER_QNAME(next,handle)
  464.     (next) = PR_FindNextCounterQname((handle))
  465. #else
  466. #define PR_FIND_NEXT_COUNTER_QNAME(next,handle) NULL
  467. #endif
  468. NSPR_API(PRCounterHandle) 
  469. PR_FindNextCounterQname( 
  470.         PRCounterHandle handle
  471. );
  472. /* -----------------------------------------------------------------------
  473. ** FUNCTION: PR_FindNextCounterRname() -- Retreive the next RName counter
  474. ** handle iterator
  475. ** 
  476. ** DESCRIPTION:
  477. ** PR_FindNextCounterRname() retreives the first or next RNname
  478. ** handle from the counter data base, depending on the
  479. ** value of handle. When handle is NULL, the function attempts to
  480. ** retreive the first RName handle in the database. When handle is
  481. ** a handle previosly retreived RName handle, then the function
  482. ** attempts to retreive the next RName handle.
  483. ** 
  484. ** INPUTS:
  485. **  handle: PRCounterHandle or NULL.
  486. **  qhandle: PRCounterHandle of a previously aquired via
  487. ** PR_FIND_NEXT_QNAME_HANDLE()
  488. ** 
  489. ** OUTPUTS: returned
  490. ** 
  491. ** RETURNS: PRCounterHandle or NULL when no more RName counter
  492. ** handles are present.
  493. ** 
  494. ** RESTRICTIONS:
  495. **  A concurrent PR_CreateCounter() or PR_DestroyCounter() may
  496. ** cause unpredictable results.
  497. ** 
  498. ** A PRCounterHandle returned from this function may only be used
  499. ** in another PR_FindNextCounterRname() function call; other
  500. ** operations may cause unpredictable results.
  501. ** 
  502. */
  503. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  504. #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)
  505.     (next) = PR_FindNextCounterRname((rhandle),(qhandle))
  506. #else
  507. #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)
  508. #endif
  509. NSPR_API(PRCounterHandle) 
  510. PR_FindNextCounterRname( 
  511.         PRCounterHandle rhandle,
  512.         PRCounterHandle qhandle
  513. );
  514. PR_END_EXTERN_C
  515. #endif /* prcountr_h___ */