michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #if defined(_PRMWAIT_H) michael@0: #else michael@0: #define _PRMWAIT_H michael@0: michael@0: #include "prio.h" michael@0: #include "prtypes.h" michael@0: #include "prclist.h" michael@0: michael@0: PR_BEGIN_EXTERN_C michael@0: michael@0: /********************************************************************************/ michael@0: /********************************************************************************/ michael@0: /********************************************************************************/ michael@0: /****************************** WARNING ****************************/ michael@0: /********************************************************************************/ michael@0: /**************************** This is work in progress. *************************/ michael@0: /************************** Do not make any assumptions *************************/ michael@0: /************************** about the stability of this *************************/ michael@0: /************************** API or the underlying imple- ************************/ michael@0: /************************** mentation. ************************/ michael@0: /********************************************************************************/ michael@0: /********************************************************************************/ michael@0: michael@0: /* michael@0: ** STRUCTURE: PRWaitGroup michael@0: ** DESCRIPTION: michael@0: ** The client may define several wait groups in order to semantically michael@0: ** tie a collection of file descriptors for a single purpose. This allows michael@0: ** easier dispatching of threads that returned with active file descriptors michael@0: ** from the wait function. michael@0: */ michael@0: typedef struct PRWaitGroup PRWaitGroup; michael@0: michael@0: /* michael@0: ** ENUMERATION: PRMWStatus michael@0: ** DESCRIPTION: michael@0: ** This enumeration is used to indicate the completion status of michael@0: ** a receive wait object. Generally stated, a positive value indicates michael@0: ** that the operation is not yet complete. A zero value indicates michael@0: ** success (similar to PR_SUCCESS) and any negative value is an michael@0: ** indication of failure. The reason for the failure can be retrieved michael@0: ** by calling PR_GetError(). michael@0: ** michael@0: ** PR_MW_PENDING The operation is still pending. None of the other michael@0: ** fields of the object are currently valid. michael@0: ** PR_MW_SUCCESS The operation is complete and it was successful. michael@0: ** PR_MW_FAILURE The operation failed. The reason for the failure michael@0: ** can be retrieved by calling PR_GetError(). michael@0: ** PR_MW_TIMEOUT The amount of time allowed for by the object's michael@0: ** 'timeout' field has expired w/o the operation michael@0: ** otherwise coming to closure. michael@0: ** PR_MW_INTERRUPT The operation was cancelled, either by the client michael@0: ** calling PR_CancelWaitFileDesc() or destroying the michael@0: ** entire wait group (PR_DestroyWaitGroup()). michael@0: */ michael@0: typedef enum PRMWStatus michael@0: { michael@0: PR_MW_PENDING = 1, michael@0: PR_MW_SUCCESS = 0, michael@0: PR_MW_FAILURE = -1, michael@0: PR_MW_TIMEOUT = -2, michael@0: PR_MW_INTERRUPT = -3 michael@0: } PRMWStatus; michael@0: michael@0: /* michael@0: ** STRUCTURE: PRMemoryDescriptor michael@0: ** DESCRIPTION: michael@0: ** THis is a descriptor for an interval of memory. It contains a michael@0: ** pointer to the first byte of that memory and the length (in michael@0: ** bytes) of the interval. michael@0: */ michael@0: typedef struct PRMemoryDescriptor michael@0: { michael@0: void *start; /* pointer to first byte of memory */ michael@0: PRSize length; /* length (in bytes) of memory interval */ michael@0: } PRMemoryDescriptor; michael@0: michael@0: /* michael@0: ** STRUCTURE: PRMWaitClientData michael@0: ** DESCRIPTION: michael@0: ** An opague stucture for which a client MAY give provide a concrete michael@0: ** definition and associate with a receive descriptor. The NSPR runtime michael@0: ** does not manage this field. It is completely up to the client. michael@0: */ michael@0: typedef struct PRMWaitClientData PRMWaitClientData; michael@0: michael@0: /* michael@0: ** STRUCTURE: PRRecvWait michael@0: ** DESCRIPTION: michael@0: ** A receive wait object contains the file descriptor that is subject michael@0: ** to the wait and the amount of time (beginning epoch established michael@0: ** when the object is presented to the runtime) the the channel should michael@0: ** block before abandoning the process. michael@0: ** michael@0: ** The success of the wait operation will be noted in the object's michael@0: ** 'outcome' field. The fields are not valid when the NSPR runtime michael@0: ** is in possession of the object. michael@0: ** michael@0: ** The memory descriptor describes an interval of writable memory michael@0: ** in the caller's address space where data from an initial read michael@0: ** can be placed. The description may indicate a null interval. michael@0: */ michael@0: typedef struct PRRecvWait michael@0: { michael@0: PRCList internal; /* internal runtime linkages */ michael@0: michael@0: PRFileDesc *fd; /* file descriptor associated w/ object */ michael@0: PRMWStatus outcome; /* outcome of the current/last operation */ michael@0: PRIntervalTime timeout; /* time allowed for entire operation */ michael@0: michael@0: PRInt32 bytesRecv; /* number of bytes transferred into buffer */ michael@0: PRMemoryDescriptor buffer; /* where to store first segment of input data */ michael@0: PRMWaitClientData *client; /* pointer to arbitrary client defined data */ michael@0: } PRRecvWait; michael@0: michael@0: /* michael@0: ** STRUCTURE: PRMWaitEnumerator michael@0: ** DESCRIPTION: michael@0: ** An enumeration object is used to store the state of an existing michael@0: ** enumeration over a wait group. The opaque object must be allocated michael@0: ** by the client and the reference presented on each call to the michael@0: ** pseudo-stateless enumerator. The enumeration objects are sharable michael@0: ** only in serial fashion. michael@0: */ michael@0: typedef struct PRMWaitEnumerator PRMWaitEnumerator; michael@0: michael@0: michael@0: /* michael@0: ** FUNCTION: PR_AddWaitFileDesc michael@0: ** DESCRIPTION: michael@0: ** This function will effectively add a file descriptor to the michael@0: ** list of those waiting for network receive. The new descriptor michael@0: ** will be semantically tied to the wait group specified. michael@0: ** michael@0: ** The ownership for the storage pointed to by 'desc' is temporarily michael@0: ** passed over the the NSPR runtime. It will be handed back by the michael@0: ** function PR_WaitRecvReady(). michael@0: ** michael@0: ** INPUTS michael@0: ** group A reference to a PRWaitGroup or NULL. Wait groups are michael@0: ** created by calling PR_CreateWaitGroup() and are used michael@0: ** to semantically group various file descriptors by the michael@0: ** client's application. michael@0: ** desc A reference to a valid PRRecvWait. The object of the michael@0: ** reference must be preserved and not be modified michael@0: ** until its ownership is returned to the client. michael@0: ** RETURN michael@0: ** PRStatus An indication of success. If equal to PR_FAILUE details michael@0: ** of the failure are avaiable via PR_GetError(). michael@0: ** michael@0: ** ERRORS michael@0: ** PR_INVALID_ARGUMENT_ERROR michael@0: ** Invalid 'group' identifier or duplicate 'desc' object. michael@0: ** PR_OUT_OF_MEMORY_ERROR michael@0: ** Insuffient memory for internal data structures. michael@0: ** PR_INVALID_STATE_ERROR michael@0: ** The group is being destroyed. michael@0: */ michael@0: NSPR_API(PRStatus) PR_AddWaitFileDesc(PRWaitGroup *group, PRRecvWait *desc); michael@0: michael@0: /* michael@0: ** FUNCTION: PR_WaitRecvReady michael@0: ** DESCRIPTION: michael@0: ** PR_WaitRecvReady will block the calling thread until one of the michael@0: ** file descriptors that have been added via PR_AddWaitFileDesc is michael@0: ** available for input I/O. michael@0: ** INPUT michael@0: ** group A pointer to a valid PRWaitGroup or NULL (the null michael@0: ** group. The function will block the caller until a michael@0: ** channel from the wait group becomes ready for receive michael@0: ** or there is some sort of error. michael@0: ** RETURN michael@0: ** PRReciveWait michael@0: ** When the caller is resumed it is either returned a michael@0: ** valid pointer to a previously added receive wait or michael@0: ** a NULL. If the latter, the function has terminated michael@0: ** for a reason that can be determined by calling michael@0: ** PR_GetError(). michael@0: ** If a valid pointer is returned, the reference is to the michael@0: ** file descriptor contained in the receive wait object. michael@0: ** The outcome of the wait operation may still fail, and michael@0: ** if it has, that fact will be noted in the object's michael@0: ** outcome field. Details can be retrieved from PR_GetError(). michael@0: ** michael@0: ** ERRORS michael@0: ** PR_INVALID_ARGUMENT_ERROR michael@0: ** The 'group' is not known by the runtime. michael@0: ** PR_PENDING_INTERRUPT_ERROR michael@0: The thread was interrupted. michael@0: ** PR_INVALID_STATE_ERROR michael@0: ** The group is being destroyed. michael@0: */ michael@0: NSPR_API(PRRecvWait*) PR_WaitRecvReady(PRWaitGroup *group); michael@0: michael@0: /* michael@0: ** FUNCTION: PR_CancelWaitFileDesc michael@0: ** DESCRIPTION: michael@0: ** PR_CancelWaitFileDesc is provided as a means for cancelling operations michael@0: ** on objects previously submitted by use of PR_AddWaitFileDesc(). If michael@0: ** the runtime knows of the object, it will be marked as having failed michael@0: ** because it was interrupted (similar to PR_Interrupt()). The first michael@0: ** available thread waiting on the group will be made to return the michael@0: ** PRRecvWait object with the outcome noted. michael@0: ** michael@0: ** INPUTS michael@0: ** group The wait group under which the wait receive object was michael@0: ** added. michael@0: ** desc A pointer to the wait receive object that is to be michael@0: ** cancelled. michael@0: ** RETURN michael@0: ** PRStatus If the wait receive object was located and associated michael@0: ** with the specified wait group, the status returned will michael@0: ** be PR_SUCCESS. There is still a race condition that would michael@0: ** permit the offected object to complete normally, but it michael@0: ** is assured that it will complete in the near future. michael@0: ** If the receive object or wait group are invalid, the michael@0: ** function will return with a status of PR_FAILURE. michael@0: ** michael@0: ** ERRORS michael@0: ** PR_INVALID_ARGUMENT_ERROR michael@0: ** The 'group' argument is not recognized as a valid group. michael@0: ** PR_COLLECTION_EMPTY_ERROR michael@0: ** There are no more receive wait objects in the group's michael@0: ** collection. michael@0: ** PR_INVALID_STATE_ERROR michael@0: ** The group is being destroyed. michael@0: */ michael@0: NSPR_API(PRStatus) PR_CancelWaitFileDesc(PRWaitGroup *group, PRRecvWait *desc); michael@0: michael@0: /* michael@0: ** FUNCTION: PR_CancelWaitGroup michael@0: ** DESCRIPTION: michael@0: ** PR_CancelWaitGroup is provided as a means for cancelling operations michael@0: ** on objects previously submitted by use of PR_AddWaitFileDesc(). Each michael@0: ** successive call will return a pointer to a PRRecvWait object that michael@0: ** was previously registered via PR_AddWaitFileDesc(). If no wait michael@0: ** objects are associated with the wait group, a NULL will be returned. michael@0: ** This function should be called in a loop until a NULL is returned michael@0: ** to reclaim all the wait objects prior to calling PR_DestroyWaitGroup(). michael@0: ** michael@0: ** INPUTS michael@0: ** group The wait group under which the wait receive object was michael@0: ** added. michael@0: ** RETURN michael@0: ** PRRecvWait* If the wait group is valid and at least one receive wait michael@0: ** object is present in the group, that object will be michael@0: ** marked as PR_MW_INTERRUPT'd and removed from the group's michael@0: ** queues. Otherwise a NULL will be returned and the reason michael@0: ** for the NULL may be retrieved by calling PR_GetError(). michael@0: ** michael@0: ** ERRORS michael@0: ** PR_INVALID_ARGUMENT_ERROR michael@0: ** PR_GROUP_EMPTY_ERROR michael@0: */ michael@0: NSPR_API(PRRecvWait*) PR_CancelWaitGroup(PRWaitGroup *group); michael@0: michael@0: /* michael@0: ** FUNCTION: PR_CreateWaitGroup michael@0: ** DESCRIPTION: michael@0: ** A wait group is an opaque object that a client may create in order michael@0: ** to semantically group various wait requests. Each wait group is michael@0: ** unique, including the default wait group (NULL). A wait request michael@0: ** that was added under a wait group will only be serviced by a caller michael@0: ** that specified the same wait group. michael@0: ** michael@0: ** INPUT michael@0: ** size The size of the hash table to be used to contain the michael@0: ** receive wait objects. This is just the initial size. michael@0: ** It will grow as it needs to, but to avoid that hassle michael@0: ** one can suggest a suitable size initially. It should michael@0: ** be ~30% larger than the maximum number of receive wait michael@0: ** objects expected. michael@0: ** RETURN michael@0: ** PRWaitGroup If successful, the function will return a pointer to an michael@0: ** object that was allocated by and owned by the runtime. michael@0: ** The reference remains valid until it is explicitly destroyed michael@0: ** by calling PR_DestroyWaitGroup(). michael@0: ** michael@0: ** ERRORS michael@0: ** PR_OUT_OF_MEMORY_ERROR michael@0: */ michael@0: NSPR_API(PRWaitGroup*) PR_CreateWaitGroup(PRInt32 size); michael@0: michael@0: /* michael@0: ** FUNCTION: PR_DestroyWaitGroup michael@0: ** DESCRIPTION: michael@0: ** Undo the effects of PR_CreateWaitGroup(). Any receive wait operations michael@0: ** on the group will be treated as if the each had been the target of a michael@0: ** PR_CancelWaitFileDesc(). michael@0: ** michael@0: ** INPUT michael@0: ** group Reference to a wait group previously allocated using michael@0: ** PR_CreateWaitGroup(). michael@0: ** RETURN michael@0: ** PRStatus Will be PR_SUCCESS if the wait group was valid and there michael@0: ** are no receive wait objects in that group. Otherwise michael@0: ** will indicate PR_FAILURE. michael@0: ** michael@0: ** ERRORS michael@0: ** PR_INVALID_ARGUMENT_ERROR michael@0: ** The 'group' argument does not reference a known object. michael@0: ** PR_INVALID_STATE_ERROR michael@0: ** The group still contains receive wait objects. michael@0: */ michael@0: NSPR_API(PRStatus) PR_DestroyWaitGroup(PRWaitGroup *group); michael@0: michael@0: /* michael@0: ** FUNCTION: PR_CreateMWaitEnumerator michael@0: ** DESCRIPTION: michael@0: ** The PR_CreateMWaitEnumerator() function returns a reference to an michael@0: ** opaque PRMWaitEnumerator object. The enumerator object is required michael@0: ** as an argument for each successive call in the stateless enumeration michael@0: ** of the indicated wait group. michael@0: ** michael@0: ** group The wait group that the enumeration is intended to michael@0: ** process. It may be be the default wait group (NULL). michael@0: ** RETURN michael@0: ** PRMWaitEnumerator* group michael@0: ** A reference to an object that will be used to store michael@0: ** intermediate state of enumerations. michael@0: ** ERRORS michael@0: ** Errors are indicated by the function returning a NULL. michael@0: ** PR_INVALID_ARGUMENT_ERROR michael@0: ** The 'group' argument does not reference a known object. michael@0: ** PR_OUT_OF_MEMORY_ERROR michael@0: */ michael@0: NSPR_API(PRMWaitEnumerator*) PR_CreateMWaitEnumerator(PRWaitGroup *group); michael@0: michael@0: /* michael@0: ** FUNCTION: PR_DestroyMWaitEnumerator michael@0: ** DESCRIPTION: michael@0: ** Destroys the object created by PR_CreateMWaitEnumerator(). The reference michael@0: ** used as an argument becomes invalid. michael@0: ** michael@0: ** INPUT michael@0: ** PRMWaitEnumerator* enumerator michael@0: ** The PRMWaitEnumerator object to destroy. michael@0: ** RETURN michael@0: ** PRStatus michael@0: ** PR_SUCCESS if successful, PR_FAILURE otherwise. michael@0: ** ERRORS michael@0: ** PR_INVALID_ARGUMENT_ERROR michael@0: ** The enumerator is invalid. michael@0: */ michael@0: NSPR_API(PRStatus) PR_DestroyMWaitEnumerator(PRMWaitEnumerator* enumerator); michael@0: michael@0: /* michael@0: ** FUNCTION: PR_EnumerateWaitGroup michael@0: ** DESCRIPTION: michael@0: ** PR_EnumerateWaitGroup is a thread safe enumerator over a wait group. michael@0: ** Each call to the enumerator must present a valid PRMWaitEnumerator michael@0: ** rererence and a pointer to the "previous" element returned from the michael@0: ** enumeration process or a NULL. michael@0: ** michael@0: ** An enumeration is started by passing a NULL as the "previous" value. michael@0: ** Subsequent calls to the enumerator must pass in the result of the michael@0: ** previous call. The enumeration end is signaled by the runtime returning michael@0: ** a NULL as the result. michael@0: ** michael@0: ** Modifications to the content of the wait group are allowed during michael@0: ** an enumeration. The effect is that the enumeration may have to be michael@0: ** "reset" and that may result in duplicates being returned from the michael@0: ** enumeration. michael@0: ** michael@0: ** An enumeration may be abandoned at any time. The runtime is not michael@0: ** keeping any state, so there are no issues in that regard. michael@0: */ michael@0: NSPR_API(PRRecvWait*) PR_EnumerateWaitGroup( michael@0: PRMWaitEnumerator *enumerator, const PRRecvWait *previous); michael@0: michael@0: PR_END_EXTERN_C michael@0: michael@0: #endif /* defined(_PRMWAIT_H) */ michael@0: michael@0: /* prmwait.h */