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

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. #if defined(_PRMWAIT_H)
  38. #else
  39. #define _PRMWAIT_H
  40. #include "prio.h"
  41. #include "prtypes.h"
  42. #include "prclist.h"
  43. PR_BEGIN_EXTERN_C
  44. /********************************************************************************/
  45. /********************************************************************************/
  46. /********************************************************************************/
  47. /******************************       WARNING        ****************************/
  48. /********************************************************************************/
  49. /**************************** This is work in progress. *************************/
  50. /************************** Do not make any assumptions *************************/
  51. /************************** about the stability of this *************************/
  52. /************************** API or the underlying imple- ************************/
  53. /************************** mentation.                   ************************/
  54. /********************************************************************************/
  55. /********************************************************************************/
  56. /*
  57. ** STRUCTURE:   PRWaitGroup
  58. ** DESCRIPTION:
  59. **      The client may define several wait groups in order to semantically
  60. **      tie a collection of file descriptors for a single purpose. This allows
  61. **      easier dispatching of threads that returned with active file descriptors
  62. **      from the wait function.
  63. */
  64. typedef struct PRWaitGroup PRWaitGroup;
  65. /*
  66. ** ENUMERATION: PRMWStatus
  67. ** DESCRIPTION:
  68. **      This enumeration is used to indicate the completion status of
  69. **      a receive wait object. Generally stated, a positive value indicates
  70. **      that the operation is not yet complete. A zero value indicates
  71. **      success (similar to PR_SUCCESS) and any negative value is an
  72. **      indication of failure. The reason for the failure can be retrieved
  73. **      by calling PR_GetError().
  74. **
  75. **  PR_MW_PENDING       The operation is still pending. None of the other
  76. **                      fields of the object are currently valid.
  77. **  PR_MW_SUCCESS       The operation is complete and it was successful.
  78. **  PR_MW_FAILURE       The operation failed. The reason for the failure
  79. **                      can be retrieved by calling PR_GetError().
  80. **  PR_MW_TIMEOUT       The amount of time allowed for by the object's
  81. **                      'timeout' field has expired w/o the operation
  82. **                      otherwise coming to closure.
  83. **  PR_MW_INTERRUPT     The operation was cancelled, either by the client
  84. **                      calling PR_CancelWaitFileDesc() or destroying the
  85. **                      entire wait group (PR_DestroyWaitGroup()).
  86. */
  87. typedef enum PRMWStatus
  88. {
  89.     PR_MW_PENDING = 1,
  90.     PR_MW_SUCCESS = 0,
  91.     PR_MW_FAILURE = -1,
  92.     PR_MW_TIMEOUT = -2,
  93.     PR_MW_INTERRUPT = -3
  94. } PRMWStatus;
  95. /*
  96. ** STRUCTURE:   PRMemoryDescriptor
  97. ** DESCRIPTION:
  98. **      THis is a descriptor for an interval of memory. It contains a
  99. **      pointer to the first byte of that memory and the length (in
  100. **      bytes) of the interval.
  101. */
  102. typedef struct PRMemoryDescriptor
  103. {
  104.     void *start;                /* pointer to first byte of memory */
  105.     PRSize length;              /* length (in bytes) of memory interval */
  106. } PRMemoryDescriptor;
  107. /*
  108. ** STRUCTURE:   PRMWaitClientData
  109. ** DESCRIPTION:
  110. **      An opague stucture for which a client MAY give provide a concrete
  111. **      definition and associate with a receive descriptor. The NSPR runtime
  112. **      does not manage this field. It is completely up to the client.
  113. */
  114. typedef struct PRMWaitClientData PRMWaitClientData;
  115. /*
  116. ** STRUCTURE:   PRRecvWait
  117. ** DESCRIPTION:
  118. **      A receive wait object contains the file descriptor that is subject
  119. **      to the wait and the amount of time (beginning epoch established
  120. **      when the object is presented to the runtime) the the channel should
  121. **      block before abandoning the process.
  122. **
  123. **      The success of the wait operation will be noted in the object's
  124. **      'outcome' field. The fields are not valid when the NSPR runtime
  125. **      is in possession of the object.
  126. **
  127. **      The memory descriptor describes an interval of writable memory
  128. **      in the caller's address space where data from an initial read
  129. **      can be placed. The description may indicate a null interval.
  130. */
  131. typedef struct PRRecvWait 
  132. {
  133.     PRCList internal;           /* internal runtime linkages */
  134.     PRFileDesc *fd;             /* file descriptor associated w/ object */
  135.     PRMWStatus outcome;         /* outcome of the current/last operation */
  136.     PRIntervalTime timeout;     /* time allowed for entire operation */
  137.     PRInt32 bytesRecv;          /* number of bytes transferred into buffer */
  138.     PRMemoryDescriptor buffer;  /* where to store first segment of input data */
  139.     PRMWaitClientData *client;  /* pointer to arbitrary client defined data */
  140. } PRRecvWait;
  141. /*
  142. ** STRUCTURE:   PRMWaitEnumerator
  143. ** DESCRIPTION:
  144. **      An enumeration object is used to store the state of an existing
  145. **      enumeration over a wait group. The opaque object must be allocated
  146. **      by the client and the reference presented on each call to the
  147. **      pseudo-stateless enumerator. The enumeration objects are sharable
  148. **      only in serial fashion.
  149. */
  150. typedef struct PRMWaitEnumerator PRMWaitEnumerator;
  151. /*
  152. ** FUNCTION:    PR_AddWaitFileDesc
  153. ** DESCRIPTION:
  154. **      This function will effectively add a file descriptor to the
  155. **      list of those waiting for network receive. The new descriptor
  156. **      will be semantically tied to the wait group specified.
  157. **
  158. **      The ownership for the storage pointed to by 'desc' is temporarily
  159. **      passed over the the NSPR runtime. It will be handed back by the
  160. **      function PR_WaitRecvReady().
  161. **
  162. **  INPUTS
  163. **      group       A reference to a PRWaitGroup or NULL. Wait groups are
  164. **                  created by calling PR_CreateWaitGroup() and are used
  165. **                  to semantically group various file descriptors by the
  166. **                  client's application.
  167. **      desc        A reference to a valid PRRecvWait. The object of the
  168. **                  reference must be preserved and not be modified
  169. **                  until its ownership is returned to the client.
  170. **  RETURN
  171. **      PRStatus    An indication of success. If equal to PR_FAILUE details
  172. **                  of the failure are avaiable via PR_GetError().
  173. **
  174. **  ERRORS
  175. **      PR_INVALID_ARGUMENT_ERROR
  176. **                  Invalid 'group' identifier or duplicate 'desc' object.
  177. **      PR_OUT_OF_MEMORY_ERROR
  178. **                  Insuffient memory for internal data structures.
  179. **      PR_INVALID_STATE_ERROR
  180. **                  The group is being destroyed.
  181. */
  182. NSPR_API(PRStatus) PR_AddWaitFileDesc(PRWaitGroup *group, PRRecvWait *desc);
  183. /*
  184. ** FUNCTION:    PR_WaitRecvReady
  185. ** DESCRIPTION:
  186. **      PR_WaitRecvReady will block the calling thread until one of the
  187. **      file descriptors that have been added via PR_AddWaitFileDesc is
  188. **      available for input I/O.
  189. **  INPUT
  190. **      group       A pointer to a valid PRWaitGroup or NULL (the null
  191. **                  group. The function will block the caller until a
  192. **                  channel from the wait group becomes ready for receive
  193. **                  or there is some sort of error.
  194. **  RETURN
  195. **      PRReciveWait
  196. **                  When the caller is resumed it is either returned a
  197. **                  valid pointer to a previously added receive wait or
  198. **                  a NULL. If the latter, the function has terminated
  199. **                  for a reason that can be determined by calling
  200. **                  PR_GetError().
  201. **                  If a valid pointer is returned, the reference is to the
  202. **                  file descriptor contained in the receive wait object.
  203. **                  The outcome of the wait operation may still fail, and
  204. **                  if it has, that fact will be noted in the object's
  205. **                  outcome field. Details can be retrieved from PR_GetError().
  206. **
  207. **  ERRORS
  208. **      PR_INVALID_ARGUMENT_ERROR
  209. **                  The 'group' is not known by the runtime.
  210. **      PR_PENDING_INTERRUPT_ERROR
  211.                     The thread was interrupted.
  212. **      PR_INVALID_STATE_ERROR
  213. **                  The group is being destroyed.
  214. */
  215. NSPR_API(PRRecvWait*) PR_WaitRecvReady(PRWaitGroup *group);
  216. /*
  217. ** FUNCTION:    PR_CancelWaitFileDesc
  218. ** DESCRIPTION:
  219. **      PR_CancelWaitFileDesc is provided as a means for cancelling operations
  220. **      on objects previously submitted by use of PR_AddWaitFileDesc(). If
  221. **      the runtime knows of the object, it will be marked as having failed
  222. **      because it was interrupted (similar to PR_Interrupt()). The first
  223. **      available thread waiting on the group will be made to return the
  224. **      PRRecvWait object with the outcome noted.
  225. **
  226. **  INPUTS
  227. **      group       The wait group under which the wait receive object was
  228. **                  added.
  229. **      desc        A pointer to the wait receive object that is to be
  230. **                  cancelled.
  231. **  RETURN
  232. **      PRStatus    If the wait receive object was located and associated
  233. **                  with the specified wait group, the status returned will
  234. **                  be PR_SUCCESS. There is still a race condition that would
  235. **                  permit the offected object to complete normally, but it
  236. **                  is assured that it will complete in the near future.
  237. **                  If the receive object or wait group are invalid, the
  238. **                  function will return with a status of PR_FAILURE.
  239. **
  240. **  ERRORS
  241. **      PR_INVALID_ARGUMENT_ERROR
  242. **                  The 'group' argument is not recognized as a valid group.
  243. **      PR_COLLECTION_EMPTY_ERROR
  244. **                  There are no more receive wait objects in the group's
  245. **                  collection.
  246. **      PR_INVALID_STATE_ERROR
  247. **                  The group is being destroyed.
  248. */
  249. NSPR_API(PRStatus) PR_CancelWaitFileDesc(PRWaitGroup *group, PRRecvWait *desc);
  250. /*
  251. ** FUNCTION:    PR_CancelWaitGroup
  252. ** DESCRIPTION:
  253. **      PR_CancelWaitGroup is provided as a means for cancelling operations
  254. **      on objects previously submitted by use of PR_AddWaitFileDesc(). Each
  255. **      successive call will return a pointer to a PRRecvWait object that
  256. **      was previously registered via PR_AddWaitFileDesc(). If no wait
  257. **      objects are associated with the wait group, a NULL will be returned.
  258. **      This function should be called in a loop until a NULL is returned
  259. **      to reclaim all the wait objects prior to calling PR_DestroyWaitGroup().
  260. **
  261. **  INPUTS
  262. **      group       The wait group under which the wait receive object was
  263. **                  added.
  264. **  RETURN
  265. **      PRRecvWait* If the wait group is valid and at least one receive wait
  266. **                  object is present in the group, that object will be
  267. **                  marked as PR_MW_INTERRUPT'd and removed from the group's
  268. **                  queues. Otherwise a NULL will be returned and the reason
  269. **                  for the NULL may be retrieved by calling PR_GetError().
  270. **
  271. **  ERRORS
  272. **      PR_INVALID_ARGUMENT_ERROR
  273. **      PR_GROUP_EMPTY_ERROR
  274. */
  275. NSPR_API(PRRecvWait*) PR_CancelWaitGroup(PRWaitGroup *group);
  276. /*
  277. ** FUNCTION:    PR_CreateWaitGroup
  278. ** DESCRIPTION:
  279. **      A wait group is an opaque object that a client may create in order
  280. **      to semantically group various wait requests. Each wait group is
  281. **      unique, including the default wait group (NULL). A wait request
  282. **      that was added under a wait group will only be serviced by a caller
  283. **      that specified the same wait group.
  284. **
  285. **  INPUT
  286. **      size        The size of the hash table to be used to contain the
  287. **                  receive wait objects. This is just the initial size.
  288. **                  It will grow as it needs to, but to avoid that hassle
  289. **                  one can suggest a suitable size initially. It should
  290. **                  be ~30% larger than the maximum number of receive wait
  291. **                  objects expected.
  292. **  RETURN
  293. **      PRWaitGroup If successful, the function will return a pointer to an
  294. **                  object that was allocated by and owned by the runtime.
  295. **                  The reference remains valid until it is explicitly destroyed
  296. **                  by calling PR_DestroyWaitGroup().
  297. **
  298. **  ERRORS
  299. **      PR_OUT_OF_MEMORY_ERROR
  300. */
  301. NSPR_API(PRWaitGroup*) PR_CreateWaitGroup(PRInt32 size);
  302. /*
  303. ** FUNCTION:    PR_DestroyWaitGroup
  304. ** DESCRIPTION:
  305. **      Undo the effects of PR_CreateWaitGroup(). Any receive wait operations
  306. **      on the group will be treated as if the each had been the target of a
  307. **      PR_CancelWaitFileDesc().
  308. **
  309. **  INPUT
  310. **      group       Reference to a wait group previously allocated using
  311. **                  PR_CreateWaitGroup().
  312. **  RETURN
  313. **      PRStatus    Will be PR_SUCCESS if the wait group was valid and there
  314. **                  are no receive wait objects in that group. Otherwise
  315. **                  will indicate PR_FAILURE.
  316. **
  317. **  ERRORS
  318. **      PR_INVALID_ARGUMENT_ERROR
  319. **                  The 'group' argument does not reference a known object.
  320. **      PR_INVALID_STATE_ERROR
  321. **                  The group still contains receive wait objects.
  322. */
  323. NSPR_API(PRStatus) PR_DestroyWaitGroup(PRWaitGroup *group);
  324. /*
  325. ** FUNCTION:    PR_CreateMWaitEnumerator
  326. ** DESCRIPTION:
  327. **      The PR_CreateMWaitEnumerator() function returns a reference to an
  328. **      opaque PRMWaitEnumerator object. The enumerator object is required
  329. **      as an argument for each successive call in the stateless enumeration
  330. **      of the indicated wait group.
  331. **
  332. **      group       The wait group that the enumeration is intended to
  333. **                  process. It may be be the default wait group (NULL).
  334. ** RETURN
  335. **      PRMWaitEnumerator* group
  336. **                  A reference to an object that will be used to store
  337. **                  intermediate state of enumerations.
  338. ** ERRORS
  339. **      Errors are indicated by the function returning a NULL.
  340. **      PR_INVALID_ARGUMENT_ERROR
  341. **                  The 'group' argument does not reference a known object.
  342. **      PR_OUT_OF_MEMORY_ERROR
  343. */
  344. NSPR_API(PRMWaitEnumerator*) PR_CreateMWaitEnumerator(PRWaitGroup *group);
  345. /*
  346. ** FUNCTION:    PR_DestroyMWaitEnumerator
  347. ** DESCRIPTION:
  348. **      Destroys the object created by PR_CreateMWaitEnumerator(). The reference
  349. **      used as an argument becomes invalid.
  350. **
  351. ** INPUT
  352. **      PRMWaitEnumerator* enumerator
  353. **          The PRMWaitEnumerator object to destroy.
  354. ** RETURN
  355. **      PRStatus
  356. **          PR_SUCCESS if successful, PR_FAILURE otherwise.
  357. ** ERRORS
  358. **      PR_INVALID_ARGUMENT_ERROR
  359. **                  The enumerator is invalid.
  360. */
  361. NSPR_API(PRStatus) PR_DestroyMWaitEnumerator(PRMWaitEnumerator* enumerator);
  362. /*
  363. ** FUNCTION:    PR_EnumerateWaitGroup
  364. ** DESCRIPTION:
  365. **      PR_EnumerateWaitGroup is a thread safe enumerator over a wait group.
  366. **      Each call to the enumerator must present a valid PRMWaitEnumerator
  367. **      rererence and a pointer to the "previous" element returned from the
  368. **      enumeration process or a NULL.
  369. **
  370. **      An enumeration is started by passing a NULL as the "previous" value.
  371. **      Subsequent calls to the enumerator must pass in the result of the
  372. **      previous call. The enumeration end is signaled by the runtime returning
  373. **      a NULL as the result.
  374. **
  375. **      Modifications to the content of the wait group are allowed during
  376. **      an enumeration. The effect is that the enumeration may have to be
  377. **      "reset" and that may result in duplicates being returned from the
  378. **      enumeration.
  379. **
  380. **      An enumeration may be abandoned at any time. The runtime is not
  381. **      keeping any state, so there are no issues in that regard.
  382. */
  383. NSPR_API(PRRecvWait*) PR_EnumerateWaitGroup(
  384.     PRMWaitEnumerator *enumerator, const PRRecvWait *previous);
  385.    
  386. PR_END_EXTERN_C
  387. #endif /* defined(_PRMWAIT_H) */
  388. /* prmwait.h */