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