| OLD | NEW |
|---|
| (Empty) |
| 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 */ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 665543002:
Remove third_party/npapi/npspy. (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master