Polling file descriptors
Waiting for events on file descriptors
Every EVL element is represented by a device file accessible in the /dev/evl file hierarchy, and requests can be sent to any of those elements by writing to common file descriptors obtained on the corresponding files. Conversely, information is returned to the caller by reading from those file descriptors. EVL applications can poll for out-of-band events occurring on a set of file descriptors opened on elements, just like in-band applications can use poll(2) with other files.
To access the out-of-band polling services, an application first needs to obtain a file descriptor on a new polling set by a call to evl_poll(). Such descriptor is an access point for registering other file descriptors to monitor, then sensing events occurring on them. evl_poll() or evl_timedpoll() fill an array of structures indicating which events have been received on each notified file descriptor. The type of this structure is as follows:
struct evl_poll_event {
int32_t fd;
int32_t events;
};
Applications can wait for any event which
poll(2) can
monitor such as POLLIN, POLLOUT, POLLRDNORM, POLLWRNORM and so
on. Which event can occur on a given file descriptor is defined by the
out-of-band driver managing the file it refers to.
| Pollable elements |
|---|
| Semaphore |
| Event flag group |
| Timer |
| Proxy |
| Cross-buffer |
Polling services
This call creates a polling set, returning a file descriptor representing the new object upon success. There is no arbitrary limit on the number of polling sets an application can create, which is only limited to the available system resources.
evl_new_poll() returns the file descriptor of the newly created
polling set on success. Otherwise, a negated error code is returned:
-
-EMFILE The per-process limit on the number of open file descriptors has been reached.
-
-ENFILE The system-wide limit on the total number of open files has been reached.
-
-ENOMEM No memory available.
-
-ENXIO The EVL library is not initialized for the current process. Such initialization happens implicitly when evl_attach_self() is called by any thread of your process, or by explicitly calling evl_init(). You have to bootstrap the library services in a way or another before creating an EVL polling set.
Adds a file descriptor to a polling set. This service registers the newfd file descriptor for being polled for events by the efd polling set.
The file descriptor of a polling set obtained by a previous call to evl_new_poll().
A file descriptor to monitor for events. Once newfd is added to the polling set, it becomes a source of events which is monitored when reading from efd. You can add as many file descriptor as you need to a polling set in order to perform synchronous I/O multiplexing over multiple data sources or sinks.
A bitmask representing the set of events to monitor for newfd. These
events are common to the in-band
poll(2)
interface. POLLERR and POLLHUP are always implicitly polled, even
if they are not mentioned in events. POLLNVAL cannot be awaited
for. Which event is meaningful in the context of the call depends on
the driver managing the file, which defines the logic for raising
them. For instance, if newfd refers to an EVL semaphore, you
could monitor POLLIN and POLLRDNORM, no other event would occur
for this type of file.
evl_add_pollfd() returns zero on success. Otherwise, a negated error
code is returned:
-
-EBADF efd is not a valid file descriptor referring to an EVL polling set.
-
-EBADF newfd is not a valid file descriptor to an EVL file. Note that you cannot register a file descriptor referring to a common file (i.e. managed by an in-band driver) into an EVL polling set. An EVL file is created by [out-of-band drivers] (/core/user-api/io/) for referring to resources which can be accessed from the [out-of-band execution] (/dovetail/kernel-api/altsched/) stage.
-
-ELOOP Adding newfd to the polling set would lead to a cyclic dependency (such as newfd referring to the polling set).
-
-ENOMEM No memory available.
Removes a file descriptor from a polling set. As a result, reading this polling set does not monitor delfd anymore. This change applies to subsequent calls to evl_poll() or evl_timedpoll() for such set; ongoing waits are not affected.
The file descriptor of a polling set obtained by a previous call to evl_new_poll().
The file descriptor to stop monitoring for events. This descriptor should have been registered by an earlier call to evl_add_pollfd().
evl_del_pollfd() returns zero on success. Otherwise, a negated error
code is returned:
-
-EBADF efd is not a valid file descriptor referring to an EVL polling set.
-
-ENOENT delfd is not a file descriptor present into the polling set referred to by efd.
Modifies the events being monitored for a file descriptor already registered in a polling set. This change applies to subsequent calls to evl_poll() or evl_timedpoll() for such set; ongoing waits are not affected.
The file descriptor of a polling set obtained by a previous call to evl_new_poll().
The file descriptor to update the event mask for. This descriptor should have been registered by an earlier call to evl_add_pollfd().
evl_mod_pollfd() returns zero on success. Otherwise, a negated error
code is returned:
-
-EBADF efd is not a valid file descriptor referring to an EVL polling set.
-
-ENOENT pollfd is not a file descriptor present into the polling set referred to by efd.
Waits for events on the file descriptors present in the polling set referred to by efd.
The file descriptor of a polling set obtained by a previous call to evl_new_poll().
The start of an array of structures of type evl_poll_event
containing the set of file descriptors which have received at least
one event when the call returns.
The number of structures in the pollset array. If zero, evl_poll() returns immediately with a zero count.
On success, evl_poll() returns the count of file descriptors from
the polling set for which an event is pending, each of them will
appear in a evl_poll_event entry in pollset. Otherwise, a negated
error code is returned:
-
-EBADF efd is not a valid file descriptor referring to an EVL polling set.
-
-EINVAL nrset is negative.
-
-EAGAIN fd is marked as non-blocking (O_NONBLOCK), and no file descriptor from the polling set has any event pending.
-
-EFAULT pollset points to invalid memory.
This call is a variant of evl_poll() which allows specifying a timeout on the polling operation, so that the caller is automatically unblocked if a time limit is reached.
The file descriptor of a polling set obtained by a previous call to evl_new_poll().
The start of an array of structures of type evl_poll_event
containing the set of file descriptors which have received at least
one event when the call returns.
The number of structures in the pollset array. If zero, evl_poll() returns immediately with a zero count.
A time limit to wait for any event to be notified before the call
returns on error. Timeouts are always based on the built-in
EVL_CLOCK_MONOTONIC clock. If both the
tv_sec and tv_nsec members of timeout are set to zero,
evl_timedpoll() behaves identically
to evl_poll().
On success, evl_timedpoll() returns the count of file descriptors
from the polling set for which an event is pending, each of them will
appear in a evl_poll_event entry in pollset. Otherwise, a negated
error code is returned:
-
-EBADF efd is not a valid file descriptor referring to an EVL polling set.
-
-EINVAL nrset is negative.
-
-EFAULT pollset or timeout point to invalid memory.
-
-EINVAL any of
tv_secortv_nsecin timeout is invalid. -
-ETIMEDOUT The timeout fired, after the amount of time specified by timeout.
