third_party/npapi/npspy/extern/nspr/prmwait.h

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