Class BaseEventLoop

Inheritance Relationships

Base Type

  • public std::enable_shared_from_this< BaseEventLoop >

Derived Types

Class Documentation

class BaseEventLoop : public std::enable_shared_from_this<BaseEventLoop>

The BaseEventLoop class is an interface for event loops.

The BaseEventLoop class is an interface for event loops. It provides functionality to register and remove file descriptors and to run the event loop.

It implements functionality to create and remove signals and timers using the register_fd and remove_fd functionalities provided by the derived classes.

The event loop contains an instance that registers events. When an event is triggered, the event loop will pick it up and execute the callback associated with the event. The event loop is inherently single-threaded. Functions interacting with the event loop have to be thread safe.

Subclassed by netio3::AsioEventLoop, netio3::EpollEventLoop

Public Functions

BaseEventLoop() = default
virtual ~BaseEventLoop() = default
BaseEventLoop(const BaseEventLoop &other) = delete
BaseEventLoop &operator=(const BaseEventLoop &other) = delete
BaseEventLoop(BaseEventLoop &&other) = delete
BaseEventLoop &operator=(BaseEventLoop &&other) = delete
virtual void register_fd(const EventContext &ctx) = 0

Registers an event with the event loop.

This function is used to register a file descriptor with the event loop. The registered file descriptor will be monitored for read events.

Parameters:

ctx – The event context to register

virtual void remove_fd(int fd, bool close_fd = false, bool wait = false) = 0

Removes an event from the event loop.

This function is used to remove a file descriptor from the event loop. The file descriptor will no longer be monitored for events.

If close_fd is true, the file descriptor is closed. Otherwise, it is only removed from the event loop.

Parameters:

  • fd – The file descriptor to remove

  • close_fd – Whether to close the file descriptor

  • wait – Whether to wait for outstanding events to finish

virtual void run() = 0

Runs the event loop.

The event loop is executed in the caling thread. The function blocks until the event loop is stopped.

The on_init callback is executed before the event loop starts.

virtual void run_for(std::uint64_t sec) = 0

Runs the event loop for a given time.

The event loop is executed in the calling thread. The function blocks until the event loop is stopped or the given time has passed.

Parameters:

sec – The time to run the event loop in seconds

virtual void stop() = 0

Stops the event loop.

virtual bool is_running() const = 0

Checks if the event loop is running.

Returns:

True if the event loop is running, false otherwise

inline std::optional<std::thread::id> get_thread_id() const

Get the thread id of the event loop.

Returns:

The thread id of the event loop

EventSignalHandle create_signal(const std::function<void(int)> &cb, bool useSemaphore)

Creates a signal.

A signal is a user defined event that can be fired by the user. The callback takes the corresponding file descriptor as argument. If the callback does not need it, it can be ignored.

A signal not using semaphore logic will only be executed once even if it is fired multiple times before the callback is executed. A signal using semaphore logic will be executed for every time it is fired.

Parameters:

  • cb – The callback to execute when the signal is fired

  • useSemaphore – Whether to use a semaphore for the signal

Returns:

The handle to the signal

void remove_signal(const EventSignalHandle &handle)

Removes a signal.

Outstanding events are guaranteed to be executed within a timeout before the signal is removed. If the timeout expires while events are still outstanding, a warning is issued. The event might still be handled but it is not guaranteed.

Parameters:

handle – The handle to the signal to remove

EventTimerHandle create_timer(const std::function<void(int)> &cb)

Creates a timer.

A timer is a user defined event that is executed periodically with a given frequency. The first execution happens after the time has elapsed once (so not immediately). The callback takes the corresponding file descriptor as argument. If the callback does not need it, it can be ignored.

Parameters:

cb – The callback to execute when the timer expires

Returns:

The handle to the timer

void remove_timer(const EventTimerHandle &handle)

Removes a timer.

Outstanding events might be skipped.

Parameters:

handle – The handle to the timer to remove

Protected Functions

inline void set_thread_id(std::thread::id id)

Sets the thread id of the event loop.

Parameters:

id – The thread id to set

inline void reset_thread_id()

Resets the thread id of the event loop.

void wait_for_fd(int fd, std::chrono::milliseconds timeout, const std::function<void()> &finish_function) const

Waits until a file descriptor is no longer readable.

Used to check if all outstanding events on signals have been handled before removing the signal. If executed in the same thread as the event loop, the finish_function is executed, otherwise the function waits for the file descriptor to become unreadable. If the timeout expires, the function returns and issues a warning.

Parameters:

  • fd – The file descriptor to wait for

  • timeout – The timeout to wait for the file descriptor

  • finish_function – The function to execute if called on event loop thread

Protected Static Functions

static void update_flags(int fd, int new_flags)

Updates the flags of a file descriptor.

Issues an error if the update fails. Does not remove old flags.

Parameters:

  • fd – The file descriptor to update

  • new_flags – The new flags to set

static bool check_fd(int fd)

Checks if a file descriptor has outstanding events.

Parameters:

fd – The file descriptor to check

Returns:

True if the file descriptor has outstanding events, false otherwise