Poll Routines

Modules
	Poll options
	Pollset Flags

Data Structures
union	apr_descriptor
struct	apr_pollfd_t

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, APR_POLLSET_AIO_MSGQ }
enum	apr_datatype_e { APR_NO_DESC, APR_POLL_SOCKET, APR_POLL_FILE, APR_POLL_LASTDESC }

Functions
apr_status_t	apr_pollset_create (apr_pollset_t **pollset, apr_uint32_t size, apr_pool_t *p, apr_uint32_t flags)
apr_status_t	apr_pollset_create_ex (apr_pollset_t **pollset, apr_uint32_t size, apr_pool_t *p, apr_uint32_t flags, apr_pollset_method_e method)
apr_status_t	apr_pollset_destroy (apr_pollset_t *pollset)
apr_status_t	apr_pollset_add (apr_pollset_t *pollset, const apr_pollfd_t *descriptor)
apr_status_t	apr_pollset_remove (apr_pollset_t *pollset, const apr_pollfd_t *descriptor)
apr_status_t	apr_pollset_poll (apr_pollset_t *pollset, apr_interval_time_t timeout, apr_int32_t *num, const apr_pollfd_t **descriptors)
apr_status_t	apr_pollset_wakeup (apr_pollset_t *pollset)
apr_status_t	apr_poll (apr_pollfd_t *aprset, apr_int32_t numsock, apr_int32_t *nsds, apr_interval_time_t timeout)
const char *	apr_pollset_method_name (apr_pollset_t *pollset)
const char *	apr_poll_method_defname (void)
apr_status_t	apr_pollcb_create (apr_pollcb_t **pollcb, apr_uint32_t size, apr_pool_t *p, apr_uint32_t flags)
apr_status_t	apr_pollcb_create_ex (apr_pollcb_t **pollcb, apr_uint32_t size, apr_pool_t *p, apr_uint32_t flags, apr_pollset_method_e method)
apr_status_t	apr_pollcb_add (apr_pollcb_t *pollcb, apr_pollfd_t *descriptor)
apr_status_t	apr_pollcb_remove (apr_pollcb_t *pollcb, apr_pollfd_t *descriptor)
apr_status_t	apr_pollcb_poll (apr_pollcb_t *pollcb, apr_interval_time_t timeout, apr_pollcb_cb_t func, void *baton)
apr_status_t	apr_pollcb_wakeup (apr_pollcb_t *pollcb)
const char *	apr_pollcb_method_name (apr_pollcb_t *pollcb)

Detailed Description

Typedef Documentation

apr_pollcb_cb_t

typedef apr_status_t(* apr_pollcb_cb_t) (void *baton, apr_pollfd_t *descriptor)

Function prototype for pollcb handlers

Parameters

baton	Opaque baton passed into apr_pollcb_poll()
descriptor	Contains the notification for an active descriptor. The rtnevents member describes which events were triggered for this descriptor.

Remarks

If the pollcb handler does not return APR_SUCCESS, the apr_pollcb_poll() call returns with the handler's return value.

apr_pollcb_t

typedef struct apr_pollcb_t apr_pollcb_t

Opaque structure used for pollcb API

apr_pollfd_t

typedef struct apr_pollfd_t apr_pollfd_t

See also

apr_pollfd_t

apr_pollset_t

typedef struct apr_pollset_t apr_pollset_t

Opaque structure used for pollset API

Enumeration Type Documentation

apr_datatype_e

enum apr_datatype_e

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

apr_pollset_method_e

enum apr_pollset_method_e

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
APR_POLLSET_AIO_MSGQ	Poll uses z/OS asio method

Function Documentation

apr_poll()

apr_status_t apr_poll	(	apr_pollfd_t *	aprset,
		apr_int32_t	numsock,
		apr_int32_t *	nsds,
		apr_interval_time_t	timeout
	)

Poll the descriptors in the poll structure

Parameters

aprset	The poll structure we will be using.
numsock	The number of descriptors we are polling
nsds	The number of descriptors signalled (output parameter)
timeout	The 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.

apr_poll_method_defname()

const char* apr_poll_method_defname

(

void

)

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

apr_pollcb_add()

apr_status_t apr_pollcb_add	(	apr_pollcb_t *	pollcb,
		apr_pollfd_t *	descriptor
	)

Add a socket or file descriptor to a pollcb

Parameters

pollcb	The pollcb to which to add the descriptor
descriptor	The 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.

apr_pollcb_create()

apr_status_t apr_pollcb_create	(	apr_pollcb_t **	pollcb,
		apr_uint32_t	size,
		apr_pool_t *	p,
		apr_uint32_t	flags
	)

Set up a pollcb object

Parameters

pollcb	The pointer in which to return the newly created object
size	The maximum number of descriptors that a single _poll can return.
p	The pool from which to allocate the pollcb
flags	Optional flags to modify the operation of the pollcb.

Remarks

If flags contains APR_POLLSET_WAKEABLE, then a pollcb is created with an additional internal pipe object used for the apr_pollcb_wakeup() call. The actual size of pollcb is in that case size + 1.

Pollcb is only supported on some platforms; the apr_pollcb_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.

apr_pollcb_create_ex()

apr_status_t apr_pollcb_create_ex	(	apr_pollcb_t **	pollcb,
		apr_uint32_t	size,
		apr_pool_t *	p,
		apr_uint32_t	flags,
		apr_pollset_method_e	method
	)

Set up a pollcb object

Parameters

pollcb	The pointer in which to return the newly created object
size	The maximum number of descriptors that a single _poll can return.
p	The pool from which to allocate the pollcb
flags	Optional flags to modify the operation of the pollcb.
method	Poll 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_WAKEABLE, then a pollcb is created with an additional internal pipe object used for the apr_pollcb_wakeup() call. The actual size of pollcb is in that case size + 1.

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.

apr_pollcb_method_name()

const char* apr_pollcb_method_name

(

apr_pollcb_t *

pollcb

)

Return a printable representation of the pollcb method.

Parameters

pollcb

The pollcb to use

apr_pollcb_poll()

apr_status_t apr_pollcb_poll	(	apr_pollcb_t *	pollcb,
		apr_interval_time_t	timeout,
		apr_pollcb_cb_t	func,
		void *	baton
	)

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

Parameters

pollcb	The pollcb to use
timeout	The 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_pollcb_wakeup() has been called.
func	Callback function to call for each active descriptor.
baton	Opaque 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.

APR_EINTR will be returned if the pollset has been created with APR_POLLSET_WAKEABLE and apr_pollcb_wakeup() has been called while waiting for activity.

apr_pollcb_remove()

apr_status_t apr_pollcb_remove	(	apr_pollcb_t *	pollcb,
		apr_pollfd_t *	descriptor
	)

Remove a descriptor from a pollcb

Parameters

pollcb	The pollcb from which to remove the descriptor
descriptor	The descriptor to remove

Remarks

If the descriptor is not found, APR_NOTFOUND is returned.

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.

apr_pollcb_wakeup()

apr_status_t apr_pollcb_wakeup

(

apr_pollcb_t *

pollcb

)

Interrupt the blocked apr_pollcb_poll() call.

Parameters

pollcb

The pollcb to use

Remarks

If the pollcb was not created with APR_POLLSET_WAKEABLE the return value is APR_EINIT.

apr_pollset_add()

apr_status_t apr_pollset_add	(	apr_pollset_t *	pollset,
		const apr_pollfd_t *	descriptor
	)

Add a socket or file descriptor to a pollset

Parameters

pollset	The pollset to which to add the descriptor
descriptor	The 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.

apr_pollset_create()

apr_status_t apr_pollset_create	(	apr_pollset_t **	pollset,
		apr_uint32_t	size,
		apr_pool_t *	p,
		apr_uint32_t	flags
	)

Set up a pollset object

Parameters

pollset	The pointer in which to return the newly created object
size	The maximum number of descriptors that this pollset can hold
p	The pool from which to allocate the pollset
flags	Optional 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().

apr_pollset_create_ex()

apr_status_t apr_pollset_create_ex	(	apr_pollset_t **	pollset,
		apr_uint32_t	size,
		apr_pool_t *	p,
		apr_uint32_t	flags,
		apr_pollset_method_e	method
	)

Set up a pollset object

Parameters

pollset	The pointer in which to return the newly created object
size	The maximum number of descriptors that this pollset can hold
p	The pool from which to allocate the pollset
flags	Optional flags to modify the operation of the pollset.
method	Poll 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().

apr_pollset_destroy()

apr_status_t apr_pollset_destroy

(

apr_pollset_t *

pollset

)

Destroy a pollset object

Parameters

pollset

The pollset to destroy

apr_pollset_method_name()

const char* apr_pollset_method_name

(

apr_pollset_t *

pollset

)

Return a printable representation of the pollset method.

Parameters

pollset

The pollset to use

apr_pollset_poll()

apr_status_t apr_pollset_poll	(	apr_pollset_t *	pollset,
		apr_interval_time_t	timeout,
		apr_int32_t *	num,
		const apr_pollfd_t **	descriptors
	)

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

Parameters

pollset	The pollset to use
timeout	The 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.
num	Number of signalled descriptors (output parameter)
descriptors	Array 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.

apr_pollset_remove()

apr_status_t apr_pollset_remove	(	apr_pollset_t *	pollset,
		const apr_pollfd_t *	descriptor
	)

Remove a descriptor from a pollset

Parameters

pollset	The pollset from which to remove the descriptor
descriptor	The descriptor to remove

Remarks

If the descriptor is not found, APR_NOTFOUND is returned.

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.

apr_pollset_wakeup()

apr_status_t apr_pollset_wakeup

(

apr_pollset_t *

pollset

)

Interrupt the blocked apr_pollset_poll() call.

Parameters

pollset

The pollset to use

Remarks

If the pollset was not created with APR_POLLSET_WAKEABLE the return value is APR_EINIT.