dfx::FdWatch::EPollPoller Class Reference

epoll-based implementation of Poller. More...

#include <dfx-fdwatch/EPollPoller.hpp>

Inheritance diagram for dfx::FdWatch::EPollPoller:

Collaboration diagram for dfx::FdWatch::EPollPoller:

Public Member Functions
	EPollPoller ()
	Constructs the poller and initializes underlying kernel resources.
	DFX_DISABLE_COPY_AND_MOVE (EPollPoller)
	Non-copyable, non-movable.
void	registerFd (Utils::BorrowedFd fd, EventInterests events, FdCallback cb) override
	Registers a file descriptor with the poller.
void	deregisterFd (Utils::BorrowedFd fd) noexcept override
	Deregisters a file descriptor from the poller.
void	updateFdEvents (Utils::BorrowedFd fd, EventInterests events) override
	Update the list of event that this fd is attached to.
void	deferCall (Callback cb) override
	Defer the call to the callback to the next time the event loop is reached.
void	exec ()
	Runs the event loop until stopping is requested.
void	exec (std::stop_token stopToken)
	Runs the event loop until stopToken.stop_requested() returns true.
void	requestStop () noexcept
	Requests the event loop to stop (non-blocking).
void	stop ()
	Stops the event loop.
void	wake ()
	Wakes the event loop. Useful when a stop has been requested while the loop is blocked in epoll_wait().
bool	isRunning () const noexcept
	Returns whether the event loop is currently running.
Public Member Functions inherited from dfx::FdWatch::Poller
virtual	~Poller ()=default
	Virtual destructor for interface.

Detailed Description

epoll-based implementation of Poller.

EPollPoller is the concrete event loop used by dfx to monitor file descriptors and dispatch callbacks when I/O readiness events occur.

It implements the Poller interface:

• registerFd() / deregisterFd() manage watched FDs and their callbacks.
• deferCall() schedules callbacks to run in the poller thread.

The main loop is driven by exec(). It blocks waiting for events and invokes the registered callbacks when events are received.

Internally, it uses an epoll instance FD and a wakeup FD (commonly eventfd) to interrupt epoll_wait() when work is deferred or when stopping is requested.

Note

This class is not thread-safe and is not meant to be used with multiple threads at once. This mean that only the thread that calls exec() is allowed to call registerFd(), deregisterFd(), deferCall() or any other functions.

See also

Poller

Constructor & Destructor Documentation

EPollPoller()

dfx::FdWatch::EPollPoller::EPollPoller

(

)

Constructs the poller and initializes underlying kernel resources.

Creates the epoll instance and the wakeup FD used by wake() and deferCall().

Member Function Documentation

deferCall()

void dfx::FdWatch::EPollPoller::deferCall ( Callback cb )

overridevirtual

Defer the call to the callback to the next time the event loop is reached.

The callback will be invoked as soon as all currently pending event in the event loop have been processed.

Parameters

cb	Callback to be invoked later.

Implements dfx::FdWatch::Poller.

deregisterFd()

void dfx::FdWatch::EPollPoller::deregisterFd ( Utils::BorrowedFd fd )

overridevirtualnoexcept

Deregisters a file descriptor from the poller.

After this call, the poller will no longer monitor the FD and no callbacks will be triggered for it.

Parameters

fd	Borrowed file descriptor to remove.

Note

Deregistering an FD that is not registered is allowed

Implements dfx::FdWatch::Poller.

DFX_DISABLE_COPY_AND_MOVE()

dfx::FdWatch::EPollPoller::DFX_DISABLE_COPY_AND_MOVE

(

EPollPoller

)

Non-copyable, non-movable.

The poller owns kernel resources and maintains registrations that cannot be safely duplicated or transferred.

exec() [1/2]

void dfx::FdWatch::EPollPoller::exec

(

)

Runs the event loop until stopping is requested.

This call blocks, processing registered FD events and executing deferred callbacks until requestStop() or stop() is used.

Note

This function is expected to be called from a single thread. Also this function cannot be called recursively.

exec() [2/2]

void dfx::FdWatch::EPollPoller::exec

(

std::stop_token

stopToken

)

Runs the event loop until stopToken.stop_requested() returns true.

This call blocks, processing registered FD events and executing deferred callbacks until the associated stop source request a stop.

Warning

When using this exec, the requestStop and stop function does nothing

isRunning()

bool dfx::FdWatch::EPollPoller::isRunning ( ) const

inlinenoexcept

Returns whether the event loop is currently running.

registerFd()

void dfx::FdWatch::EPollPoller::registerFd ( Utils::BorrowedFd fd, EventInterests events, FdCallback cb )

overridevirtual

Registers a file descriptor with the poller.

Once registered, the poller will monitor fd for the specified events and invoke cb when they occur.

Parameters

fd	Borrowed file descriptor to monitor.
events	Events of interest.
cb	Callback invoked when events occur.

Precondition

fd must refer to a valid, open file descriptor.

Note

Registering the same FD more than once is a no-op. If you want to change the events monitored of the callback, then the FD must be deregistered first

Implements dfx::FdWatch::Poller.

requestStop()

void dfx::FdWatch::EPollPoller::requestStop ( )

noexcept

Requests the event loop to stop (non-blocking).

This function only works for the case where exec has been called without a stop_token parameter.

stop()

void dfx::FdWatch::EPollPoller::stop

(

)

Stops the event loop.

Perform the requestStop and wake operation in sequence.

This function only works for the case where exec has been called without stop_token parameter. Note that calling it while a stop_token has been passed to exec will not request a stop, it will still wake up the event loop.

updateFdEvents()

void dfx::FdWatch::EPollPoller::updateFdEvents ( Utils::BorrowedFd fd, EventInterests events )

overridevirtual

Update the list of event that this fd is attached to.

Parameters

fd	Borrowed file descriptor to update.
events	The new list of event to listen for.

Implements dfx::FdWatch::Poller.

wake()

void dfx::FdWatch::EPollPoller::wake

(

)

Wakes the event loop. Useful when a stop has been requested while the loop is blocked in epoll_wait().

This function will work regardless of which exec function is used.

---

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

• lib/dfx-fdwatch/EPollPoller.hpp