GME  13
Classes | Defines | Typedefs | Enumerations | Functions | Variables
Poll Routines

Classes

union  apr_descriptor
struct  apr_pollfd_t

Defines

#define APR_POLLIN   0x001
#define APR_POLLPRI   0x002
#define APR_POLLOUT   0x004
#define APR_POLLERR   0x010
#define APR_POLLHUP   0x020
#define APR_POLLNVAL   0x040
#define APR_POLLSET_THREADSAFE   0x001
#define APR_POLLSET_NOCOPY   0x002
#define APR_POLLSET_WAKEABLE   0x004
#define APR_POLLSET_NODEFAULT   0x010

Typedefs

typedef struct apr_pollfd_t apr_pollfd_t
typedef struct apr_pollset_t apr_pollset_t
typedef struct apr_pollcb_t apr_pollcb_t
typedef apr_status_t(* apr_pollcb_cb_t )(void *baton, apr_pollfd_t *descriptor)

Enumerations

enum  apr_pollset_method_e {
  APR_POLLSET_DEFAULT, APR_POLLSET_SELECT, APR_POLLSET_KQUEUE, APR_POLLSET_PORT,
  APR_POLLSET_EPOLL, APR_POLLSET_POLL
}
enum  apr_datatype_e { APR_NO_DESC, APR_POLL_SOCKET, APR_POLL_FILE, APR_POLL_LASTDESC }

Functions

 APR_DECLARE (apr_status_t) apr_pollset_create(apr_pollset_t **pollset
 APR_DECLARE (const char *) apr_pollset_method_name(apr_pollset_t *pollset)

Variables

apr_uint32_t size
apr_uint32_t apr_pool_tp
apr_uint32_t apr_pool_t
apr_uint32_t 
flags
apr_uint32_t apr_pool_t
apr_uint32_t
apr_pollset_method_e 
method
const apr_pollfd_tdescriptor
apr_interval_time_t timeout
apr_interval_time_t apr_int32_t * num
apr_interval_time_t
apr_int32_t const apr_pollfd_t ** 
descriptors
apr_int32_t numsock
apr_int32_t apr_int32_t * nsds
apr_interval_time_t apr_pollcb_cb_t func
apr_interval_time_t
apr_pollcb_cb_t void * 
baton

Define Documentation

#define APR_POLLERR   0x010

Pending error

Definition at line 50 of file apr_poll.h.

#define APR_POLLHUP   0x020

Hangup occurred

Definition at line 51 of file apr_poll.h.

#define APR_POLLIN   0x001

Poll options Can read without blocking

Definition at line 47 of file apr_poll.h.

#define APR_POLLNVAL   0x040

Descriptor invalid

Definition at line 52 of file apr_poll.h.

#define APR_POLLOUT   0x004

Can write without blocking

Definition at line 49 of file apr_poll.h.

#define APR_POLLPRI   0x002

Priority data available

Definition at line 48 of file apr_poll.h.

#define APR_POLLSET_NOCOPY   0x002

Descriptors passed to apr_pollset_add() are not copied

Definition at line 60 of file apr_poll.h.

#define APR_POLLSET_NODEFAULT   0x010

Do not try to use the default method if the specified non-default method cannot be used

Definition at line 66 of file apr_poll.h.

#define APR_POLLSET_THREADSAFE   0x001

Pollset Flags Adding or removing a descriptor is thread-safe

Definition at line 57 of file apr_poll.h.

#define APR_POLLSET_WAKEABLE   0x004

Poll operations are interruptable by apr_pollset_wakeup()

Definition at line 63 of file apr_poll.h.


Typedef Documentation

Function prototype for pollcb handlers

Parameters:
batonOpaque baton passed into apr_pollcb_poll()
descriptorContains the notification for an active descriptor, the rtnevents member contains what events were triggered for this descriptor.

Definition at line 385 of file apr_poll.h.

typedef struct apr_pollcb_t apr_pollcb_t

Opaque structure used for pollset API

Definition at line 313 of file apr_poll.h.

typedef struct apr_pollfd_t apr_pollfd_t
See also:
apr_pollfd_t

Definition at line 98 of file apr_poll.h.

typedef struct apr_pollset_t apr_pollset_t

Opaque structure used for pollset API

Definition at line 116 of file apr_poll.h.


Enumeration Type Documentation

Used in apr_pollfd_t to determine what the apr_descriptor is

Enumerator:
APR_NO_DESC 

nothing here

APR_POLL_SOCKET 

descriptor refers to a socket

APR_POLL_FILE 

descriptor refers to a file

APR_POLL_LASTDESC 
Deprecated:
descriptor is the last one in the list

Definition at line 84 of file apr_poll.h.

Pollset Methods

Enumerator:
APR_POLLSET_DEFAULT 

Platform default poll method

APR_POLLSET_SELECT 

Poll uses select method

APR_POLLSET_KQUEUE 

Poll uses kqueue method

APR_POLLSET_PORT 

Poll uses Solaris event port method

APR_POLLSET_EPOLL 

Poll uses epoll method

APR_POLLSET_POLL 

Poll uses poll method

Definition at line 74 of file apr_poll.h.


Function Documentation

Set up a pollset object

Parameters:
pollsetThe pointer in which to return the newly created object
sizeThe maximum number of descriptors that this pollset can hold
pThe pool from which to allocate the pollset
flagsOptional flags to modify the operation of the pollset.
Remarks:
If flags contains APR_POLLSET_THREADSAFE, then a pollset is created on which it is safe to make concurrent calls to apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() from separate threads. This feature is only supported on some platforms; the apr_pollset_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.
If flags contains APR_POLLSET_WAKEABLE, then a pollset is created with an additional internal pipe object used for the apr_pollset_wakeup() call. The actual size of pollset is in that case size + 1. This feature is only supported on some platforms; the apr_pollset_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.
If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t structures passed to apr_pollset_add() are not copied and must have a lifetime at least as long as the pollset.
Some poll methods (including APR_POLLSET_KQUEUE, APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a fixed limit on the size of the pollset. For these methods, the size parameter controls the maximum number of descriptors that will be returned by a single call to apr_pollset_poll().

Set up a pollset object

Parameters:
pollsetThe pointer in which to return the newly created object
sizeThe maximum number of descriptors that this pollset can hold
pThe pool from which to allocate the pollset
flagsOptional flags to modify the operation of the pollset.
methodPoll method to use. See apr_pollset_method_e. If this method cannot be used, the default method will be used unless the APR_POLLSET_NODEFAULT flag has been specified.
Remarks:
If flags contains APR_POLLSET_THREADSAFE, then a pollset is created on which it is safe to make concurrent calls to apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() from separate threads. This feature is only supported on some platforms; the apr_pollset_create_ex() call will fail with APR_ENOTIMPL on platforms where it is not supported.
If flags contains APR_POLLSET_WAKEABLE, then a pollset is created with additional internal pipe object used for the apr_pollset_wakeup() call. The actual size of pollset is in that case size + 1. This feature is only supported on some platforms; the apr_pollset_create_ex() call will fail with APR_ENOTIMPL on platforms where it is not supported.
If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t structures passed to apr_pollset_add() are not copied and must have a lifetime at least as long as the pollset.
Some poll methods (including APR_POLLSET_KQUEUE, APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a fixed limit on the size of the pollset. For these methods, the size parameter controls the maximum number of descriptors that will be returned by a single call to apr_pollset_poll().

Destroy a pollset object

Parameters:
pollsetThe pollset to destroy

Add a socket or file descriptor to a pollset

Parameters:
pollsetThe pollset to which to add the descriptor
descriptorThe descriptor to add
Remarks:
If you set client_data in the descriptor, that value will be returned in the client_data field whenever this descriptor is signalled in apr_pollset_poll().
If the pollset has been created with APR_POLLSET_THREADSAFE and thread T1 is blocked in a call to apr_pollset_poll() for this same pollset that is being modified via apr_pollset_add() in thread T2, the currently executing apr_pollset_poll() call in T1 will either: (1) automatically include the newly added descriptor in the set of descriptors it is watching or (2) return immediately with APR_EINTR. Option (1) is recommended, but option (2) is allowed for implementations where option (1) is impossible or impractical.
If the pollset has been created with APR_POLLSET_NOCOPY, the apr_pollfd_t structure referenced by descriptor will not be copied and must have a lifetime at least as long as the pollset.
Do not add the same socket or file descriptor to the same pollset multiple times, even if the requested events differ for the different calls to apr_pollset_add(). If the events of interest for a descriptor change, you must first remove the descriptor from the pollset with apr_pollset_remove(), then add it again specifying all requested events.

Remove a descriptor from a pollset

Parameters:
pollsetThe pollset from which to remove the descriptor
descriptorThe descriptor to remove
Remarks:
If the pollset has been created with APR_POLLSET_THREADSAFE and thread T1 is blocked in a call to apr_pollset_poll() for this same pollset that is being modified via apr_pollset_remove() in thread T2, the currently executing apr_pollset_poll() call in T1 will either: (1) automatically exclude the newly added descriptor in the set of descriptors it is watching or (2) return immediately with APR_EINTR. Option (1) is recommended, but option (2) is allowed for implementations where option (1) is impossible or impractical.
apr_pollset_remove() cannot be used to remove a subset of requested events for a descriptor. The reqevents field in the apr_pollfd_t parameter must contain the same value when removing as when adding.

Block for activity on the descriptor(s) in a pollset

Parameters:
pollsetThe pollset to use
timeoutThe amount of time in microseconds to wait. This is a maximum, not a minimum. If a descriptor is signalled, the function will return before this time. If timeout is negative, the function will block until a descriptor is signalled or until apr_pollset_wakeup() has been called.
numNumber of signalled descriptors (output parameter)
descriptorsArray of signalled descriptors (output parameter)
Remarks:
APR_EINTR will be returned if the pollset has been created with APR_POLLSET_WAKEABLE, apr_pollset_wakeup() has been called while waiting for activity, and there were no signalled descriptors at the time of the wakeup call.
Multiple signalled conditions for the same descriptor may be reported in one or more returned apr_pollfd_t structures, depending on the implementation.
Bug:
With versions 1.4.2 and prior on Windows, a call with no descriptors and timeout will return immediately with the wrong error code.

Interrupt the blocked apr_pollset_poll() call.

Parameters:
pollsetThe pollset to use
Remarks:
If the pollset was not created with APR_POLLSET_WAKEABLE the return value is APR_EINIT.

Poll the descriptors in the poll structure

Parameters:
aprsetThe poll structure we will be using.
numsockThe number of descriptors we are polling
nsdsThe number of descriptors signalled (output parameter)
timeoutThe amount of time in microseconds to wait. This is a maximum, not a minimum. If a descriptor is signalled, the function will return before this time. If timeout is negative, the function will block until a descriptor is signalled or until apr_pollset_wakeup() has been called.
Remarks:
The number of descriptors signalled is returned in the third argument. This is a blocking call, and it will not return until either a descriptor has been signalled or the timeout has expired.
The rtnevents field in the apr_pollfd_t array will only be filled- in if the return value is APR_SUCCESS.
Bug:
With versions 1.4.2 and prior on Windows, a call with no descriptors and timeout will return immediately with the wrong error code.

Set up a pollcb object

Parameters:
pollcbThe pointer in which to return the newly created object
sizeThe maximum number of descriptors that a single _poll can return.
pThe pool from which to allocate the pollcb
flagsOptional flags to modify the operation of the pollcb.
Remarks:
Pollcb is only supported on some platforms; the apr_pollcb_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.

Set up a pollcb object

Parameters:
pollcbThe pointer in which to return the newly created object
sizeThe maximum number of descriptors that a single _poll can return.
pThe pool from which to allocate the pollcb
flagsOptional flags to modify the operation of the pollcb.
methodPoll method to use. See apr_pollset_method_e. If this method cannot be used, the default method will be used unless the APR_POLLSET_NODEFAULT flag has been specified.
Remarks:
Pollcb is only supported on some platforms; the apr_pollcb_create_ex() call will fail with APR_ENOTIMPL on platforms where it is not supported.

Add a socket or file descriptor to a pollcb

Parameters:
pollcbThe pollcb to which to add the descriptor
descriptorThe descriptor to add
Remarks:
If you set client_data in the descriptor, that value will be returned in the client_data field whenever this descriptor is signalled in apr_pollcb_poll().
Unlike the apr_pollset API, the descriptor is not copied, and users must retain the memory used by descriptor, as the same pointer will be returned to them from apr_pollcb_poll.
Do not add the same socket or file descriptor to the same pollcb multiple times, even if the requested events differ for the different calls to apr_pollcb_add(). If the events of interest for a descriptor change, you must first remove the descriptor from the pollcb with apr_pollcb_remove(), then add it again specifying all requested events.

Remove a descriptor from a pollcb

Parameters:
pollcbThe pollcb from which to remove the descriptor
descriptorThe descriptor to remove
Remarks:
apr_pollcb_remove() cannot be used to remove a subset of requested events for a descriptor. The reqevents field in the apr_pollfd_t parameter must contain the same value when removing as when adding.

Block for activity on the descriptor(s) in a pollcb

Parameters:
pollcbThe pollcb to use
timeoutThe amount of time in microseconds to wait. This is a maximum, not a minimum. If a descriptor is signalled, the function will return before this time. If timeout is negative, the function will block until a descriptor is signalled.
funcCallback function to call for each active descriptor.
batonOpaque baton passed to the callback function.
Remarks:
Multiple signalled conditions for the same descriptor may be reported in one or more calls to the callback function, depending on the implementation.
Bug:
With versions 1.4.2 and prior on Windows, a call with no descriptors and timeout will return immediately with the wrong error code.
APR_DECLARE ( const char *  )

Return a printable representation of the pollset method.

Parameters:
pollsetThe pollset to use

Return a printable representation of the default pollset method (APR_POLLSET_DEFAULT).


Variable Documentation

apr_pool_t char ** baton

Definition at line 404 of file apr_poll.h.

Definition at line 223 of file apr_poll.h.

Definition at line 266 of file apr_poll.h.

apr_uint32_t apr_pool_t apr_uint32_t flags

Definition at line 148 of file apr_poll.h.

Definition at line 404 of file apr_poll.h.

apr_uint32_t apr_pool_t apr_uint32_t apr_pollset_method_e method

Definition at line 185 of file apr_poll.h.

apr_int32_t apr_int32_t* nsds

Definition at line 296 of file apr_poll.h.

apr_interval_time_t apr_int32_t* num

Definition at line 266 of file apr_poll.h.

apr_int32_t numsock

Definition at line 296 of file apr_poll.h.

apr_uint32_t apr_pool_t* p

Definition at line 148 of file apr_poll.h.

apr_size_t size

Definition at line 148 of file apr_poll.h.

Definition at line 266 of file apr_poll.h.