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