pollset_create, pollset_ctl, pollset_destroy, pollset_poll, pollset_query, pollset_ctl_ext, pollset_poll_ext, pollset_query_ext, and pollset_ext Subroutines

Purpose

Check I/O status of multiple file descriptors.

Library

Standard C Library (libc.a)

Syntax

#include <sys/poll.h>
#include <sys/pollset.h>
#include <sys/fcntl.h>

pollset_t ps = pollset_create(int maxfd)
int rc = pollset_destroy(pollset_t ps)
int rc = pollset_ctl(pollset_t ps, struct poll_ctl *pollctl_array,
                             int array_length)
int rc = pollset_query(pollset_t ps, struct pollfd *pollfd_query)
int nfound = pollset_poll(pollset_t ps,
                                    struct pollfd *polldata_array,
                                    int array_length, int timeout)
int rc = pollset_ctl_ext(pollset_t ps, struct poll_ctl_ext* pollctl_array,
                             int array_length)
int rc = pollset_query_ext(pollset_t ps, struct pollfd_ext *pollfd_query)
int nfound = pollset_poll_ext(pollset_t ps,
                                    struct pollfd_ext *polldata_array,
                                    int array_length, int timeout)
int pollset_ext(void) 

Description

The pollset application programming interface (API) efficiently poll a large file descriptor set. This interface is best used when the file descriptor set is not frequently updated. The pollset subroutine can provide a significant performance enhancement over traditional select and poll APIs. Improvements are most visible when the number of events returned per poll operation is small in relation to the number of file descriptors polled.

The pollset API uses system calls to accomplish polling. A file descriptor set (or pollset) is established with a successful call to pollset_create. File descriptors and poll events are added, removed, or updated using the pollset_ctl subroutine. The pollset_poll subroutine is called to perform the poll operation. A pollset_query subroutine is called to query if a file descriptor is contained in the current poll set. Extended versions of the control, poll, and query subroutines exist to ease consumption for applications that desire to use features only present with the extended pollset formats.

       typedef int pollset_t

The pollset ID must not be altered by the application. The pollset API verifies that the ID is not -1. In addition, the process ID of the application must match the process ID stored at pollset creation time.

A pollset is destroyed with a successful call to pollset_destroy. Upon success, this system call returns 0. Upon failure, the pollset_destroy subroutine returns -1 with errno set to the appropriate code. An errno of EINVAL indicates an invalid pollset ID.

File descriptors must be added to the pollset with the pollset_ctl subroutine or pollset_ctl_ext subroutine before they can be monitored. A heterogeneous array of poll_ctl structures and/or poll_ctl_ext structures is passed to pollset_ctl or pollset_ctl_ext through pollctl_array. The array_length parameter indicates the number of distinct poll_ctl or poll_ctl_ext elements in the array.

Each poll_ctl poll control structure contains a version, command, fd, and events field. This structure is backwards compatible with the definition from previous releases of AIX when the version field is set to 0. An extended poll control structure, poll_ctl_ext, adds an additional field to store user-specified data when the version field is set to 1. The fd field defines the file descriptor that is the target of the command. The events field contains events of interest. When the is PS_ADD, the pollset_ctl or pollset_ctl_ext call adds a valid open file descriptor to the pollset. If a file descriptor is already in the pollset, PS_ADD causes pollset_ctl or pollset_ctl_ext to return an error. When the command is PS_MOD and the file descriptor is already in the pollset, bits in the events field are added (ORed) to the monitored events. If the file descriptor is not already in the pollset, the PS_MOD behavior is equivalent to PS_ADD, and adds a valid open file descriptor to the pollset.

Poll events and user-specified data can be refreshed for a file descriptor that is currently resident in the pollset with the PS_REPLACE command. When command is PS_DELETE and the file descriptor is already in the pollset, pollset_ctl or pollset_ctl_ext removes the file descriptor from the pollset. If the file descriptor is not already in the pollset, then PS_DELETE causes pollset_ctl or pollset_ctl_ext to return an error.

The pollset_query or pollset_query_ext interface can be used to determine information about a file descriptor with respect to the pollset. When the file descriptor is in the pollset, pollset_query or pollset_query_ext returns 1 and events is set to the currently monitored events. When present, user-specified data for the file descriptor is also returned and indicated by the presence of the POLLEXT event.

The pollset_poll or pollset_poll_ext subroutine determines which file descriptors in the pollset that have events pending. The polldata_array parameter contains a buffer address where pollfd or pollfd_ext structures are returned for file descriptors that have pending events. The number of events returned by a poll is limited by array_length. The timeout parameter specifies the amount of time to wait if no events are pending. Setting timeout to 0 guarantees that the pollset_poll or pollset_poll_ext subroutine returns immediately. Setting timeout to -1 specifies an infinite timeout. Other nonzero positive values specify the time to wait in milliseconds.

When events are returned from a pollset_poll or pollset_poll_ext operation, each pollfd or pollfd_ext structure contains an fd field with the file descriptor set, an events field with the requested events, and a revents field with the events that have occurred. Pollset events which contain user-specified data will return it in the data field of the pollfd_ext structure and indicate its presence with the POLLEXT event in the events field.

A single pollset can be accessed by multiple threads in a multithreaded process. When multiple threads are polling one pollset and an event occurs for a file descriptor, only one thread might be prompted to receive the event. After a file descriptor is returned to a thread, new events will not be generated until the next pollset_poll or pollset_poll_ext call. This behavior prevents all threads from being prompted on each event. Multiple threads can perform pollset_poll or control operations concurrently. If a user wishes to have serialized pollset modifications, environment variable PS_CTL_BLOCKING should be set to yes to have pollset_ctl or pollset_ctl_ext calls block until all running threads in pollset_poll or pollset_poll_ext have exited. A thread calling pollset_destroy is blocked until all threads have left the pollset poll, control, and query system calls.

A process can call fork after calling pollset_create. The child process will already have a pollset ID per pollset, but pollset_destroy, pollset_ctl, pollset_ctl_ext, pollset_query, pollset_query_ext, pollset_poll, and pollset_poll_ext operations will fail with an errno value of EACCES.

After a file descriptor is added to a pollset, the file descriptor will not be removed until a pollset_ctl or a pollset_ctl_ext call along with the PS_DELETE command is run. The file descriptor remains in the pollset even if the file descriptor is closed. A pollset_poll or pollset_poll_ext operation on a pollset containing a closed file descriptor returns a POLLNVAL event for that file descriptor. If the file descriptor is later allocated to a new object, the new object will be polled on future pollset_poll or pollset_poll_ext calls.

Applications may use pollset_ext to support operation in AIX versions that do not support extended pollset features. A return value of true (1) indicates extended pollsets are supported, while a return value of false (0) indicates that only the legacy pollset structures and APIs are supported.

Parameters

Return Values

Upon success, the pollset_destroy subroutine returns 0. Upon failure, the pollset_destroy subroutine returns -1 with errno set to the appropriate code.

Upon success, the pollset_create subroutine returns a pollset ID of type pollset_t. Upon failure, this system call returns -1 with errno set appropriately.

Upon success, pollset_ctl or pollset_ctl_ext returns 0. Upon failure, pollset_ctl or pollset_ctl_exit returns the 0-based problem element number of the pollctl_array (for example, 2 is returned for element 3). If the first element is the problem element, or some other error occurs prior to processing the array of elements, -1 is returned and errno is set to the appropriate code. The calling application must acknowledge that elements in the array prior to the problem element were successfully processed and should attempt to call pollset_ctl or pollset_ctl_ext again with the elements of pollctl_array beyond the problematic element.

If a file descriptor is not a member of the pollset, pollset_query or pollset_query_ext returns 0. If the file descriptor is in the pollset, pollset_query or pollset_query_ext returns 1, events is set to the currently monitored events, and when present, the data field is set to the user-specified data. If an error occurs after there is an attempt to determine if the file descriptor is a member of the pollset, then pollset_query or pollset_query_ext returns -1 with errno set to the appropriate return code.

The pollset_poll or pollset_poll_ext subroutine returns the number of file descriptors on which requested events occurred. When no requested events occurred on any of the file descriptors, 0 is returned. A value of -1 is returned when an error occurs and errno is set to the appropriate code.

Error Codes

Item	Description
EACCES	Process does not have permission to access a pollset.
EAGAIN	System resource temporarily not available.
EFAULT	Address supplied was not valid.
EINTR	A signal was received during the system call.
EINVAL	Invalid parameter.
ENOMEM	Insufficient system memory available.
ENOSPC	Maximum number of pollsets in use.
EPERM	Process does not have permission to create a pollset.
ENOTSUP	Device does not support the event combination requested.