Efficient file descriptor I/O event polling. More...

#include <Poller.hxx>

Classes
struct	PollEvent
	A single poll event as returned by wait(). More...

Public Types
enum class	MonitorFlag : uint32_t { INPUT = EPOLLIN , OUTPUT = EPOLLOUT , SOCKET_HANGUP = EPOLLRDHUP , EXCEPTIONS = EPOLLPRI , EDGE_TRIGGERED = EPOLLET , ONESHOT = EPOLLONESHOT , STAY_AWAKE = EPOLLWAKEUP }
	Flags used to declare interest in specific events and options in addFD() and modFD(). More...

enum class	Event : uint32_t { INPUT_READY = EPOLLIN , OUTPUT_READY = EPOLLOUT , SOCKET_HANGUP = EPOLLRDHUP , EXCEPTION_OCCURED = EPOLLPRI , ERROR_OCCURED = EPOLLERR , HANGUP_OCCURED = EPOLLHUP }
	Flags found in PollEvent that indicate the events that occurred on a file descriptor. More...

using	MonitorFlags = BitMask<MonitorFlag>

using	EventMask = BitMask<Event>

Public Member Functions
	Poller ()
	Creates a yet invalid Poller instance.

	Poller (size_t max_events)
	Creates a Poller instance ready for use.

	~Poller ()
	Calls close()

	Poller (const Poller &)=delete
	Avoid copying due to the file descriptor member.

Poller &	operator= (const Poller &)=delete

void	create (size_t max_events=16)
	Actually create the poll file descriptor backing this object.

void	close ()
	Closes a previously create()'d poll file descriptor again.

bool	valid () const
	Returns whether currently a valid poll file descriptor exists.

void	addFD (const FileDescriptor fd, const MonitorFlags flags)
	Start monitoring the given file descriptor using the given settings.

void	modFD (const FileDescriptor fd, const MonitorFlags flags)
	Modify monitoring settings for an already monitored descriptor.

void	delFD (const FileDescriptor fd)
	Remove a file descriptor from the set of monitored files.

std::vector< PollEvent >	wait (const std::optional< IntervalTime > timeout={})
	Wait for one of the monitored events to be ready.

Protected Member Functions
int	rawPollFD () const

Protected Attributes
FileDescriptor	m_poll_fd

std::vector< PollEvent >	m_events

Detailed Description

Efficient file descriptor I/O event polling.

This class provides a wrapper around the epoll() Linux specific file descriptor monitoring API. The API operates on a file descriptor of its own that references a set of monitored file descriptors.

A peculiarity of the API is that it can operate in a level triggered or an edge triggered fashion. The level triggered mode is the one known from classical APIs like select(). It means that a file descriptor will always be signaled as ready if currently one of the monitoring conditions is fulfilled. Edge triggered instead means that the condition is only signaled once for a single event and afterwards only triggered again if additional events occur, regardless of whether data was actually read/written to the monitored file descriptors or not.

The edge triggered approach can be more efficient as it requires less system calls on high I/O load. However, it also requires more care taken by the implementation of the userspace application. The general recommendation is that all monitored file descriptors should be operated in non-blocking mode in this case and once an event is signaled the respective file descriptor should be read from / written to until an EAGAIN result is encountered. Only then should the poll API be consulted again for waiting for further events.

Special care also is required when file descriptors that are monitored are closed within the application. The kernel monitors open file descriptions here, not only open file descriptors. This means if there exist copies of a file descriptor then closing one of the involved file descriptors will not end monitoring of the still open file description.

File descriptors signaled as being ready for non-blocking I/O could still be blocking for example in case of networking sockets, e.g. if a received packet has an invalid checksum and therefore nothing to return to userspace. To avoid such scenarios the application should use non-blocking file descriptors and react to EAGAIN results upon read/write.

The Poller FD is created, as usual, with the O_CLOEXEC flag set. Explicitly re-enable the flag should you require inheritance to unrelated sub processes.

Definition at line 58 of file Poller.hxx.

Member Typedef Documentation

◆ EventMask

using cosmos::Poller::EventMask = BitMask<Event>

Definition at line 97 of file Poller.hxx.

◆ MonitorFlags

using cosmos::Poller::MonitorFlags = BitMask<MonitorFlag>

Definition at line 79 of file Poller.hxx.

Member Enumeration Documentation

◆ Event

enum class cosmos::Poller::Event : uint32_t

strong

Flags found in PollEvent that indicate the events that occurred on a file descriptor.

Enumerator
INPUT_READY	See also MonitorFlag::INPUT
OUTPUT_READY	See also MonitorFlag::OUTPUT
SOCKET_HANGUP	See also MonitorFlag::SOCKET_HANGUP
EXCEPTION_OCCURED	See also MonitorFlag::EXCEPTIONS
ERROR_OCCURED	An error condition occurred on the file descriptor (this is also reported for the write end of a pipe, if the read end is closed). This event is always reported independently of MonitorFlag.
HANGUP_OCCURED	Socket or pipe peer has hung up. Data may still be pending though. This event is always reported independently of MonitorFlags.

Definition at line 82 of file Poller.hxx.

                         : uint32_t {
                INPUT_READY       = EPOLLIN,
                OUTPUT_READY      = EPOLLOUT,
                SOCKET_HANGUP     = EPOLLRDHUP,
                EXCEPTION_OCCURED = EPOLLPRI,
                ERROR_OCCURED     = EPOLLERR,
                HANGUP_OCCURED    = EPOLLHUP
        };

◆ MonitorFlag

enum class cosmos::Poller::MonitorFlag : uint32_t

strong

Flags used to declare interest in specific events and options in addFD() and modFD().

Enumerator
INPUT	Monitor for read() operation becoming possible.
OUTPUT	Monitor for write() operation becoming possible.
SOCKET_HANGUP	Monitor for stream socket peer closed or shut down the write half of the connection (data may still be pending)
EXCEPTIONS	Monitor for exceptional conditions occuring on the file descriptor, depending on the actual file type.
EDGE_TRIGGERED	Operate in edge triggered mode instead of level triggered (which is the default)
ONESHOT	Only report events once, then disable monitoring until this flag is set again using modFD()
STAY_AWAKE	If the process has the CAP_BLOCK_SUSPEND capability then the system won't enter a suspend state until the process that received this event calls wait() again.

Definition at line 62 of file Poller.hxx.

                               : uint32_t {
                INPUT          = EPOLLIN,
                OUTPUT         = EPOLLOUT,
                SOCKET_HANGUP  = EPOLLRDHUP,
                EXCEPTIONS     = EPOLLPRI,
                EDGE_TRIGGERED = EPOLLET,
                ONESHOT        = EPOLLONESHOT,
                STAY_AWAKE     = EPOLLWAKEUP
        };

Constructor & Destructor Documentation

◆ Poller() [1/2]

cosmos::Poller::Poller ( )

inline

Creates a yet invalid Poller instance.

Definition at line 113 of file Poller.hxx.

113{}

◆ Poller() [2/2]

cosmos::Poller::Poller ( size_t max_events )

inlineexplicit

Creates a Poller instance ready for use.

See also: create()

Definition at line 119 of file Poller.hxx.

                                           {
                create(max_events);
        }

◆ ~Poller()

cosmos::Poller::~Poller ( )

Calls close()

Definition at line 15 of file Poller.cxx.

                {
        try {
                close();
        } catch (const std::exception &ex) {
                noncritical_error(
                        sprintf("%s: failed to close()", __FUNCTION__),
                        ex);
        }
}

Member Function Documentation

◆ addFD()

void cosmos::Poller::addFD	(	const FileDescriptor	fd,
		const MonitorFlags	flags )

Start monitoring the given file descriptor using the given settings.

If currently no valid poll FD exists then this will throw an ApiError exception.

Adding the same file descriptor twice also causes an error. Use modFD() to modify monitoring settings for FDs already monitored.

Definition at line 63 of file Poller.cxx.

                                                                    {
        control(rawPollFD(), to_integral(fd.raw()), EPOLL_CTL_ADD, flags.raw());
}

◆ close()

void cosmos::Poller::close ( )

Closes a previously create()'d poll file descriptor again.

Any monitoring that was setup previously will be dropped. A future call to create() can reestablish the Poller functionality.

In the (rare) case that closing fails then an ApiError is thrown.

If currently no valid poll file descriptor exist then this function does nothing.

Definition at line 43 of file Poller.cxx.

                   {
        if (!valid())
                return;
 
        m_poll_fd.close();
        m_events.clear();
}

◆ create()

void cosmos::Poller::create ( size_t max_events = 16 )

Actually create the poll file descriptor backing this object.

If the file descriptor already exists this does nothing.

If the creation fails then an ApiError is thrown.

Parameters

[in] max_events Maximum number of events that can be reported with a single call to wait().

Definition at line 29 of file Poller.cxx.

                                     {
        if (valid())
                return;
 
        auto pfd = epoll_create1(EPOLL_CLOEXEC);
 
        if (pfd < 0) {
                cosmos_throw (ApiError("epoll_create1()"));
        }
 
        m_poll_fd.setFD(FileNum{pfd});
        m_events.resize(max_events);
}

◆ delFD()

void cosmos::Poller::delFD ( const FileDescriptor fd )

Remove a file descriptor from the set of monitored files.

If the given file descriptor is not currently monitored then this will throw an ApiError.

Definition at line 71 of file Poller.cxx.

                                          {
        if (epoll_ctl(rawPollFD(), EPOLL_CTL_DEL, to_integral(fd.raw()), nullptr) < 0) {
                cosmos_throw (ApiError("epoll_ctl(EPOLL_CTL_DEL)"));
        }
}

◆ modFD()

void cosmos::Poller::modFD	(	const FileDescriptor	fd,
		const MonitorFlags	flags )

Modify monitoring settings for an already monitored descriptor.

If currently no valid poll FD exists then this will throw an ApiError exception.

Definition at line 67 of file Poller.cxx.

                                                                    {
        control(rawPollFD(), to_integral(fd.raw()), EPOLL_CTL_MOD, flags.raw());
}

◆ rawPollFD()

int cosmos::Poller::rawPollFD ( ) const

protected

Definition at line 25 of file Poller.cxx.

                            {
        return to_integral(m_poll_fd.raw());
}

◆ valid()

bool cosmos::Poller::valid ( ) const

inline

Returns whether currently a valid poll file descriptor exists.

Definition at line 154 of file Poller.hxx.

154{ return m_poll_fd.valid(); }

cosmos::FileDescriptor::valid

bool valid() const

Returns whether currently a valid file descriptor number is assigned.

Definition FileDescriptor.hxx:195

◆ wait()

std::vector< Poller::PollEvent > cosmos::Poller::wait ( const std::optional< IntervalTime > timeout = {} )

Wait for one of the monitored events to be ready.

Parameters

[in] timeout An optional timeout interval to apply after which the call will return even if no events are ready. An empty vector is returned in the timeout case. A timeout of zero achieves a polling operation that will not block at all. This is a relative timeout specification which means that completing the timeout after an interruption is not possible.

Returns: The range of events that occurred, or an empty vector if the timeout occurred.

Definition at line 77 of file Poller.cxx.

                                                                               {
        while (true) {
                const auto num_events = epoll_pwait2(
                        rawPollFD(), m_events.data(), m_events.size(), timeout ? &*timeout : nullptr, nullptr);
 
                if (num_events < 0) {
                        if (auto_restart_syscalls && get_errno() == Errno::INTERRUPTED)
                                // transparent restart
                                continue;
                        cosmos_throw (ApiError("epoll_wait()"));
                }
 
                return std::vector<PollEvent>(m_events.begin(), m_events.begin() + num_events);
        }
}

Member Data Documentation

◆ m_events

std::vector<PollEvent> cosmos::Poller::m_events

protected

Definition at line 201 of file Poller.hxx.

◆ m_poll_fd

FileDescriptor cosmos::Poller::m_poll_fd

protected

Definition at line 200 of file Poller.hxx.

The documentation for this class was generated from the following files:

include/io/Poller.hxx
src/io/Poller.cxx

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ EventMask

◆ MonitorFlags

Member Enumeration Documentation

◆ Event

◆ MonitorFlag

Constructor & Destructor Documentation

◆ Poller() [1/2]

◆ Poller() [2/2]

◆ ~Poller()

Member Function Documentation

◆ addFD()

◆ close()

◆ create()

◆ delFD()

◆ modFD()

◆ rawPollFD()

◆ valid()

◆ wait()

Member Data Documentation

◆ m_events

◆ m_poll_fd