flux_pollevents(3)

SYNOPSIS

#include <flux/core.h>

int flux_pollfd (flux_t *h);

int flux_pollevents (flux_t *h);

Link with -lflux-core.

DESCRIPTION

flux_pollfd() and flux_pollevents() are used together to integrate a flux_t handle into an event loop.

flux_pollfd() obtains a file descriptor that becomes readable when handle h needs attention. It is suitable for monitoring using poll(2) or equivalent. The signaling is edge-triggered, meaning that POLLIN is raised when the handle becomes ready for reading or writing, but is not re-raised if those conditions are still true when poll() is re-entered. The file descriptor is created on the first call to flux_pollfd() or flux_pollevents(). It is used for signaling purposes only, must not be read, written, or closed.

flux_pollevents() is normally called after a POLLIN event on flux_pollfd(). It returns a bitmask of poll flags for handle h and clears the pending flux_pollfd() POLLIN event, if any.

Valid poll flags are:

FLUX_POLLIN

Handle is ready for reading.

FLUX_POLLOUT

Handle is ready for writing.

FLUX_POLLERR

Handle has experienced an error.

As indicated above, the event loop must process all events on the handle before returning to sleep, due to edge triggering. When processing an edge-triggered event source, it is a best practice to maintain fairness by allowing other event sources to receive attention while working through pending I/O on the edge-triggered source. This can be accomplished in the Flux reactor by combining prep, check, and idle watchers into a composite watcher for the edge triggered source. Other event loops such as libev and libuv have similar concepts. For a Flux example, refer to the source code for flux_handle_watcher_create(3).

It is possible for the flux_pollfd() to raise POLLIN and then for flux_pollevents() to return zero. Spurious wake-ups are to be expected from time to time with edge-triggered event sources and should not be treated as errors.

RETURN VALUE

flux_pollevents() returns flags on success. On error, -1 is returned, and errno is set.

flux_pollfd() returns a file descriptor on success. On error, -1 is returned, and errno is set.

ERRORS

EINVAL

Some arguments were invalid.

RESOURCES

Flux: http://flux-framework.org

Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc

Issue Tracker: https://github.com/flux-framework/flux-core/issues

SEE ALSO

flux_open(3)