qb::io::async::listener Class Reference

Central event loop manager for asynchronous IO operations. More...

#include <listener.h>

Collaboration diagram for qb::io::async::listener:

Classes
class	RegisteredKernelEvent
	Template wrapper for concrete event handlers and their associated libev watchers. More...

Public Member Functions
	listener ()
	Constructor.
void	clear ()
	Clear all registered events from this listener.
	~listener () noexcept
	Destructor.
template<typename EV_EVENT>
void	on (EV_EVENT &event, int revents)
	Generic event callback handler invoked by libev for any active watcher.
template<typename _Event, typename _Actor, typename... _Args>
_Event &	registerEvent (_Actor &actor, _Args &&...args)
	Register an event handler (actor/object) for a specific asynchronous event type.
void	unregisterEvent (IRegisteredKernelEvent *kevent)
	Unregister an event handler and its associated libev watcher.
ev::loop_ref	loop () const
	Get a reference to the underlying libev event loop.
void	run (int flag=0)
	Run the event loop to process pending events.
void	break_one ()
	Request the event loop to break out of its current run() cycle.
std::size_t	nb_invoked_event () const
	Get the number of events invoked during the last call to run().
std::size_t	size () const
	Get the number of currently registered event handlers.

Static Public Attributes
static thread_local listener	current
	Thread-local instance of the listener.

Detailed Description

Central event loop manager for asynchronous IO operations.

The listener class is the core of the asynchronous event system. It manages an event loop (based on libev) that handles all asynchronous events (IO, timer, signal, etc.) and dispatches them to registered handlers.

Each thread has its own listener instance accessible via the thread_local static member 'current'.

Constructor & Destructor Documentation

listener()

qb::io::async::listener::listener ( )

inline

Constructor.

Creates a new listener with a dynamic event loop using automatic detection of the best available backend (e.g., epoll, kqueue, select) via libev's EVFLAG_AUTO.

~listener()

qb::io::async::listener::~listener ( )

inlinenoexcept

Destructor.

Cleans up by calling clear() to remove all registered events and their watchers.

Member Function Documentation

clear()

void qb::io::async::listener::clear ( )

inline

Clear all registered events from this listener.

Removes and deletes all registered event handlers (IRegisteredKernelEvent instances). It also runs the event loop once with EVRUN_ONCE to process any pending libev events before fully clearing, which might be necessary for proper cleanup of some watchers.

Note

This is automatically called by the listener's destructor.

on()

template<typename EV_EVENT>

void qb::io::async::listener::on ( EV_EVENT & event, int revents )

inline

Generic event callback handler invoked by libev for any active watcher.

This method is the entry point for libev to notify of an event. It updates the custom event wrapper's _revents field and then invokes the stored IRegisteredKernelEvent::invoke() method, which in turn calls the user-defined on(SpecificEvent&) handler in the registered actor/object.

Template Parameters

EV_EVENT

The specific libev watcher type (e.g., ev::io, ev::timer).

Parameters

event	The libev watcher that was triggered.
revents	The bitmask of triggered event flags (e.g., EV_READ, EV_WRITE).

registerEvent()

template<typename _Event, typename _Actor, typename... _Args>

_Event & qb::io::async::listener::registerEvent ( _Actor & actor, _Args &&... args )

inline

Register an event handler (actor/object) for a specific asynchronous event type.

Creates a RegisteredKernelEvent wrapper for the given actor and event type, initializes the underlying libev watcher with the provided arguments, and registers it with this listener's event loop.

Template Parameters

_Event	The qb-io event type (e.g., qb::io::async::event::io, qb::io::async::event::timer). This type wraps a specific libev watcher.
_Actor	The type of the class that will handle the event (must have an on(_Event&) method).
_Args	Types of additional arguments for initializing the libev watcher (e.g., fd and event flags for ev::io).

Parameters

actor	Reference to the actor/object instance that will handle the event.
args	Additional arguments forwarded to the libev watcher's set() or equivalent initialization method.

Returns

Reference to the created _Event object (which is also the libev watcher). This reference can be used to later start() or stop() the watcher.

unregisterEvent()

void qb::io::async::listener::unregisterEvent ( IRegisteredKernelEvent * kevent )

inline

Unregister an event handler and its associated libev watcher.

Removes the specified IRegisteredKernelEvent from the listener's tracking and deletes the event handler object, which also stops and cleans up the underlying libev watcher via its destructor.

Parameters

kevent

Pointer to the IRegisteredKernelEvent to unregister. This pointer is typically obtained when the event was initially registered or stored within the libev watcher wrapper itself (e.g., _Event::_interface).

loop()

ev::loop_ref qb::io::async::listener::loop ( ) const

inlinenodiscard

Get a reference to the underlying libev event loop.

Returns

ev::loop_ref (a reference wrapper to ev_loop*) for this listener.

Useful for advanced direct interaction with libev if needed, though most operations are handled through the listener's API.

run()

void qb::io::async::listener::run ( int flag = 0 )

inline

Run the event loop to process pending events.

Executes the event loop with the specified libev run flag. This call blocks or returns based on the flag and event activity. It also resets the _nb_invoked_events counter before running.

Parameters

flag	The libev run flag (e.g., EVRUN_NOWAIT to check once and return, EVRUN_ONCE to wait for and process one event block, 0 for default blocking run). Default is 0, which means ev_run will block until ev_break is called or no active watchers remain.

break_one()

void qb::io::async::listener::break_one ( )

inline

Request the event loop to break out of its current run() cycle.

This signals the libev loop to stop processing further events in the current run() invocation. If run() was called with default blocking behavior, it will return after the current event (if any) is processed.

nb_invoked_event()

std::size_t qb::io::async::listener::nb_invoked_event ( ) const

inlinenodiscard

Get the number of events invoked during the last call to run().

Returns

The count of events that were processed and dispatched to handlers.

Note

This counter is reset at the beginning of each run() call.

size()

std::size_t qb::io::async::listener::size ( ) const

inlinenodiscard

Get the number of currently registered event handlers.

Returns

The total number of active event watchers managed by this listener.

Member Data Documentation

current

thread_local listener qb::io::async::listener::current

static

Thread-local instance of the listener.

Each thread has its own listener accessible through this static member. This provides a way to access the current thread's event loop without passing a reference explicitly.

Note

This is typically initialized automatically when qb::Main starts its VirtualCore threads, or by calling qb::io::async::init() for standalone qb-io usage.