![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to prmwait.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Synchronet] / sbbs / include / mozilla / nspr|
Return to prmwait.h CVS log | Up to [Synchronet] / sbbs / include / mozilla / nspr |
1.1 root 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 */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.