Event Loop Component

Type-safe event loop management. More...

Namespaces
namespace	idfxx

Concepts
concept	idfxx::receivable_event_data
	Concept for types that can be received as event data.
concept	idfxx::event_data
	Concept for types that can be both received and posted as event data.

Classes
class	idfxx::event_base< IdEnum >
	Typed event base template. More...
struct	idfxx::event< IdEnum, DataType >
	A typed event that pairs an event ID with its data type. More...
class	idfxx::event_loop
	Base class for event loops. More...
class	idfxx::event_loop::listener_handle
	Handle to a registered event listener. More...
class	idfxx::event_loop::unique_listener_handle
	RAII handle for event listener registration. More...
class	idfxx::user_event_loop
	User-created event loop with manual dispatch. More...

Macros
#define	IDFXX_EVENT_DEFINE_BASE(name, id_enum)
	Defines an event base.

Typedefs
template<typename DataType >
using	idfxx::event_handler = typename event_handler_traits< DataType >::type
	Handler type for typed event listeners.
template<typename IdEnum >
using	idfxx::opaque_event_handler = std::move_only_function< void(event_base< IdEnum > base, IdEnum id, void *event_data) const >
	Callback type for wildcard event listeners.

Functions
template<typename IdEnum , typename DataType >
listener_handle	idfxx::event_loop::listener_add (event< IdEnum, DataType > event, event_handler< DataType > callback)
	Registers a type-safe listener for a specific event.
template<typename IdEnum >
listener_handle	idfxx::event_loop::listener_add (event_base< IdEnum > base, opaque_event_handler< std::type_identity_t< IdEnum > > callback)
	Registers a listener for any event from a base.
void	idfxx::event_loop::listener_remove (listener_handle handle)
	Removes a listener by handle.
template<typename IdEnum , typename DataType >
result< listener_handle >	idfxx::event_loop::try_listener_add (event< IdEnum, DataType > event, event_handler< DataType > callback)
	Registers a type-safe listener for a specific event.
template<typename IdEnum >
result< listener_handle >	idfxx::event_loop::try_listener_add (event_base< IdEnum > base, opaque_event_handler< std::type_identity_t< IdEnum > > callback)
	Registers a listener for any event from a base.

Detailed Description

Type-safe event loop management.

Provides event loops for posting and subscribing to events with type-safe event bases and IDs.

Depends on Core Utilities for error handling.

Macro Definition Documentation

IDFXX_EVENT_DEFINE_BASE

#define IDFXX_EVENT_DEFINE_BASE	(		name,
			id_enum
	)

Value:

    inline constexpr char _##name##_base[] = #name;                                                                    \
    inline constexpr ::idfxx::event_base<id_enum> name{_##name##_base};                                                \
    constexpr ::idfxx::event_base<id_enum> idfxx_get_event_base(id_enum*) {                                            \
        return name;                                                                                                   \
    }

Defines an event base.

Creates an event_base with the given name and enum type. The event base name string is automatically derived from the variable name.

Parameters

name	The variable name for the event base.
id_enum	The enum class for event IDs within this base.

Only one event base may be defined for a given enum type. Defining a second base for the same enum will cause a compilation error (duplicate definition of the ADL lookup function).

// Define event IDs
enum class app_event_id { started, stopped };
 
// Define the event base (typically in a header)
IDFXX_EVENT_DEFINE_BASE(app_events, app_event_id);
 
// Define typed events
inline constexpr idfxx::event<app_event_id> started{app_event_id::started};
 
// Use it
loop.post(started);

Definition at line 58 of file event.hpp.

Typedef Documentation

event_handler

template<typename DataType >

using idfxx::event_handler = typedef typename event_handler_traits<DataType>::type

Handler type for typed event listeners.

For events with data (DataType is not void), the handler receives a const reference to the data type. For events without data (DataType is void), the handler takes no arguments.

Template Parameters

DataType

The event data type, or void for events without data.

Definition at line 257 of file event.hpp.

opaque_event_handler

template<typename IdEnum >

using idfxx::opaque_event_handler = typedef std::move_only_function<void(event_base<IdEnum> base, IdEnum id, void* event_data) const>

Callback type for wildcard event listeners.

Used with the wildcard listener overload that receives all events from a base. The callback receives the event base, ID, and raw event data pointer.

Template Parameters

IdEnum

The event ID enum type.

Definition at line 269 of file event.hpp.

Function Documentation

listener_add() [1/2]

template<typename IdEnum , typename DataType >

event_loop::listener_handle idfxx::event_loop::listener_add	(	event< IdEnum, DataType >	event,
		event_handler< DataType >	callback
	)

Registers a type-safe listener for a specific event.

The callback receives the event data directly as its correct type, rather than as a raw void pointer. For events without data, the callback takes no arguments.

Template Parameters

IdEnum	The event ID enum type.
DataType	The event data type (or void for events without data).

Parameters

event	The typed event to listen for.
callback	Function called when the event occurs. Takes ownership of the callback.

Returns

A listener handle for the registered listener.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

loop.listener_add(wifi::sta_disconnected,
    [](const wifi::disconnected_event_data& info) {
        log::warn("wifi", "Disconnected: {}", static_cast<int>(info.reason));
    });
 
loop.listener_add(wifi::sta_start, []() {
    log::info("wifi", "Station started");
});

Definition at line 932 of file event.hpp.

References idfxx::unwrap().

listener_add() [2/2]

template<typename IdEnum >

event_loop::listener_handle idfxx::event_loop::listener_add	(	event_base< IdEnum >	base,
		opaque_event_handler< std::type_identity_t< IdEnum > >	callback
	)

Registers a listener for any event from a base.

The callback receives the event base, ID, and raw event data pointer. This overload is intended for wildcard listeners where the data type cannot be known at compile time.

Template Parameters

IdEnum

The event ID enum type.

Parameters

base	The event base.
callback	Function called when any event from this base occurs. Takes ownership of the callback.

Returns

A listener handle for the registered listener.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

Definition at line 938 of file event.hpp.

References idfxx::base, and idfxx::unwrap().

listener_remove()

void idfxx::event_loop::listener_remove ( listener_handle  handle )

inline

Removes a listener by handle.

Parameters

handle

The listener handle to remove.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

Definition at line 942 of file event.hpp.

References idfxx::unwrap().

try_listener_add() [1/2]

template<typename IdEnum , typename DataType >

result< event_loop::listener_handle > idfxx::event_loop::try_listener_add	(	event< IdEnum, DataType >	event,
		event_handler< DataType >	callback
	)

Registers a type-safe listener for a specific event.

The callback receives the event data directly as its correct type, rather than as a raw void pointer. For events without data, the callback takes no arguments.

Template Parameters

IdEnum	The event ID enum type.
DataType	The event data type (or void for events without data).

Parameters

event	The typed event to listen for.
callback	Function called when the event occurs. Takes ownership of the callback.

Returns

A listener handle, or an error.

Definition at line 961 of file event.hpp.

References idfxx::error(), idfxx::event< IdEnum, DataType >::id, and idfxx::invalid_state.

try_listener_add() [2/2]

template<typename IdEnum >

result< event_loop::listener_handle > idfxx::event_loop::try_listener_add	(	event_base< IdEnum >	base,
		opaque_event_handler< std::type_identity_t< IdEnum > >	callback
	)

Registers a listener for any event from a base.

The callback receives the event base, ID, and raw event data pointer. This overload is intended for wildcard listeners where the data type cannot be known at compile time.

Template Parameters

IdEnum

The event ID enum type.

Parameters

base	The event base.
callback	Function called when any event from this base occurs. Takes ownership of the callback.

Returns

A listener handle, or an error.

Definition at line 984 of file event.hpp.

References idfxx::base, idfxx::error(), and idfxx::invalid_state.