Base class for event loops. More...

Inheritance diagram for idfxx::event_loop:

Classes
class	listener_handle
	Handle to a registered event listener. More...

struct	task_config
	Configuration for a dedicated event dispatch task. More...

class	unique_listener_handle
	RAII handle for event listener registration. More...

Public Member Functions
	event_loop (task_config task, size_t queue_size=32)
	Creates an event loop with a dedicated dispatch task.

template<typename IdEnum , typename DataType >
listener_handle	listener_add (event< IdEnum, DataType > event, event_handler< DataType > callback)
	Registers a type-safe listener for a specific event.

template<typename IdEnum >
listener_handle	listener_add (event_base< IdEnum > base, opaque_event_handler< std::type_identity_t< IdEnum > > callback)
	Registers a listener for any event from a base.

template<typename IdEnum , typename DataType >
result< listener_handle >	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 >	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.

void	listener_remove (listener_handle handle)
	Removes a listener by handle.

result< void >	try_listener_remove (listener_handle handle)
	Removes a listener by handle.

template<typename IdEnum >
void	post (event< IdEnum > evt)
	Posts an event without data, waiting indefinitely.

template<typename IdEnum , typename Rep , typename Period >
void	post (event< IdEnum > evt, const std::chrono::duration< Rep, Period > &timeout)
	Posts an event without data, with a timeout.

template<typename IdEnum , typename DataType > requires event_data<DataType>
void	post (event< IdEnum, DataType > evt, const DataType &data)
	Posts an event with data, waiting indefinitely.

template<typename IdEnum , typename DataType , typename Rep , typename Period > requires event_data<DataType>
void	post (event< IdEnum, DataType > evt, const DataType &data, const std::chrono::duration< Rep, Period > &timeout)
	Posts an event with data, with a timeout.

template<typename IdEnum >
result< void >	try_post (event< IdEnum > evt)
	Posts an event without data, waiting indefinitely.

template<typename IdEnum , typename Rep , typename Period >
result< void >	try_post (event< IdEnum > evt, const std::chrono::duration< Rep, Period > &timeout)
	Posts an event without data, with a timeout.

template<typename IdEnum , typename DataType > requires event_data<DataType>
result< void >	try_post (event< IdEnum, DataType > evt, const DataType &data)
	Posts an event with data, waiting indefinitely.

template<typename IdEnum , typename DataType , typename Rep , typename Period > requires event_data<DataType>
result< void >	try_post (event< IdEnum, DataType > evt, const DataType &data, const std::chrono::duration< Rep, Period > &timeout)
	Posts an event with data, with a timeout.

esp_event_loop_handle_t	idf_handle () const
	Returns the underlying ESP-IDF event loop handle.

	~event_loop ()

	event_loop (const event_loop &)=delete

event_loop &	operator= (const event_loop &)=delete

	event_loop (event_loop &&other) noexcept
	Move constructor.

event_loop &	operator= (event_loop &&other) noexcept
	Move assignment.

Static Public Member Functions
static void	create_system ()
	Creates the system (default) event loop.

static void	destroy_system ()
	Destroys the system (default) event loop.

static result< void >	try_create_system ()
	Creates the system (default) event loop.

static result< void >	try_destroy_system ()
	Destroys the system (default) event loop.

static event_loop &	system ()
	Returns a reference to the system (default) event loop.

static result< event_loop >	make (task_config task, size_t queue_size=32)
	Creates an event loop with a dedicated dispatch task.

Protected Member Functions
	event_loop ()=default

	event_loop (esp_event_loop_handle_t handle, bool system=false)
	Constructs an event_loop with the given handle.

Detailed Description

Base class for event loops.

Provides listener registration and event posting operations. This type is non-copyable and move-only. Result-returning methods on a moved-from object return errc::invalid_state. Simple accessors return default/null values.

// Define typed events
inline constexpr event<my_event> started{my_event::started};
 
void register_listeners(event_loop& loop) {
    loop.listener_add(started,
        []() { idfxx::log::info("event", "Event received"); });
}
 
// Use with user-created loop (with task)
auto loop = event_loop({.name = "events"});
register_listeners(loop);
 
// Use with system loop
event_loop::create_system();
register_listeners(event_loop::system());

Definition at line 300 of file event.hpp.

Constructor & Destructor Documentation

◆ event_loop() [1/5]

idfxx::event_loop::event_loop	(	task_config	task,
		size_t	queue_size = `32`
	)

explicit

Creates an event loop with a dedicated dispatch task.

The task automatically dispatches events from the queue.

Parameters

task	Configuration for the dedicated dispatch task.
queue_size	Maximum number of events in the queue.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

◆ ~event_loop()

idfxx::event_loop::~event_loop ( )

◆ event_loop() [2/5]

idfxx::event_loop::event_loop ( const event_loop & )

delete

◆ event_loop() [3/5]

idfxx::event_loop::event_loop ( event_loop && other )

noexcept

Move constructor.

Transfers ownership of the event loop.

◆ event_loop() [4/5]

idfxx::event_loop::event_loop ( )

protecteddefault

◆ event_loop() [5/5]

idfxx::event_loop::event_loop	(	esp_event_loop_handle_t	handle,
		bool	system = `false`
	)

inlineexplicitprotected

Constructs an event_loop with the given handle.

Parameters

handle	The ESP-IDF event loop handle, or nullptr for the system loop.
system	If true, this is the system event loop singleton.

Definition at line 685 of file event.hpp.

Member Function Documentation

◆ create_system()

static void idfxx::event_loop::create_system ( )

inlinestatic

Creates the system (default) event loop.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 316 of file event.hpp.

References idfxx::unwrap().

◆ destroy_system()

static void idfxx::event_loop::destroy_system ( )

inlinestatic

Destroys the system (default) event loop.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 324 of file event.hpp.

References idfxx::unwrap().

◆ idf_handle()

esp_event_loop_handle_t idfxx::event_loop::idf_handle ( ) const

inline

Returns the underlying ESP-IDF event loop handle.

Returns: The esp_event_loop_handle_t, or nullptr for the system loop.

Definition at line 664 of file event.hpp.

◆ make()

static result< event_loop > idfxx::event_loop::make	(	task_config	task,
		size_t	queue_size = `32`
	)

static

Creates an event loop with a dedicated dispatch task.

The task automatically dispatches events from the queue.

Parameters

task	Configuration for the dedicated dispatch task.
queue_size	Maximum number of events in the queue.

Returns: An event loop with automatic dispatch, or an error.

◆ operator=() [1/2]

event_loop & idfxx::event_loop::operator= ( const event_loop & )

delete

◆ operator=() [2/2]

event_loop & idfxx::event_loop::operator= ( event_loop && other )

noexcept

Move assignment.

Transfers ownership of the event loop.

◆ post() [1/4]

template<typename IdEnum >

void idfxx::event_loop::post ( event< IdEnum > evt )

inline

Posts an event without data, waiting indefinitely.

Template Parameters

IdEnum The event ID enum type.

Parameters

evt	The event to post.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

loop.post(started);

Definition at line 522 of file event.hpp.

References idfxx::unwrap().

◆ post() [2/4]

template<typename IdEnum , typename Rep , typename Period >

void idfxx::event_loop::post	(	event< IdEnum >	evt,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Posts an event without data, with a timeout.

Template Parameters

IdEnum	The event ID enum type.
Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

evt	The event to post.
timeout	Maximum time to wait for space in the event queue.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure or timeout.

Definition at line 539 of file event.hpp.

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

◆ post() [3/4]

template<typename IdEnum , typename DataType >
requires event_data<DataType>

void idfxx::event_loop::post	(	event< IdEnum, DataType >	evt,
		const DataType &	data
	)

inline

Posts an event with data, waiting indefinitely.

Template Parameters

IdEnum	The event ID enum type.
DataType	The event data type.

Parameters

evt	The event to post.
data	The event data.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

loop.post(data_ready, my_data{42});

Definition at line 560 of file event.hpp.

References idfxx::unwrap().

◆ post() [4/4]

template<typename IdEnum , typename DataType , typename Rep , typename Period >
requires event_data<DataType>

void idfxx::event_loop::post	(	event< IdEnum, DataType >	evt,
		const DataType &	data,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Posts an event with data, with a timeout.

Template Parameters

IdEnum	The event ID enum type.
DataType	The event data type (must satisfy event_data).
Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

evt	The event to post.
data	The event data.
timeout	Maximum time to wait for space in the event queue.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure or timeout.

Definition at line 580 of file event.hpp.

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

◆ system()

static event_loop & idfxx::event_loop::system ( )

static

Returns a reference to the system (default) event loop.

Returns: A reference to the event_loop representing the system event loop.

Note: The system loop must have been created via create_system() first.

◆ try_create_system()

static result< void > idfxx::event_loop::try_create_system ( )

static

Creates the system (default) event loop.

Returns: Success or an error if already created or on failure.

◆ try_destroy_system()

static result< void > idfxx::event_loop::try_destroy_system ( )

static

Destroys the system (default) event loop.

Returns: Success or an error.

◆ try_listener_remove()

result< void > idfxx::event_loop::try_listener_remove ( listener_handle handle )

Removes a listener by handle.

Parameters

handle The listener handle to remove.

Returns: Success or an error.

◆ try_post() [1/4]

template<typename IdEnum >

result< void > idfxx::event_loop::try_post ( event< IdEnum > evt )

inline

Posts an event without data, waiting indefinitely.

Template Parameters

IdEnum The event ID enum type.

Parameters

evt	The event to post.

Returns: Success or an error.

Definition at line 593 of file event.hpp.

◆ try_post() [2/4]

template<typename IdEnum , typename Rep , typename Period >

result< void > idfxx::event_loop::try_post	(	event< IdEnum >	evt,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Posts an event without data, with a timeout.

Template Parameters

IdEnum	The event ID enum type.
Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

evt	The event to post.
timeout	Maximum time to wait for space in the event queue.

Returns: Success or an error (e.g., timeout).

Definition at line 608 of file event.hpp.

References idfxx::chrono::ticks(), and idfxx::timeout.

◆ try_post() [3/4]

template<typename IdEnum , typename DataType >
requires event_data<DataType>

result< void > idfxx::event_loop::try_post	(	event< IdEnum, DataType >	evt,
		const DataType &	data
	)

inline

Posts an event with data, waiting indefinitely.

The data type must satisfy event_data (receivable and trivially copyable).

Template Parameters

IdEnum	The event ID enum type.
DataType	The event data type (must satisfy event_data).

Parameters

evt	The event to post.
data	The event data.

Returns: Success or an error.

Definition at line 627 of file event.hpp.

◆ try_post() [4/4]

template<typename IdEnum , typename DataType , typename Rep , typename Period >
requires event_data<DataType>

result< void > idfxx::event_loop::try_post	(	event< IdEnum, DataType >	evt,
		const DataType &	data,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Posts an event with data, with a timeout.

The data type must satisfy event_data (receivable and trivially copyable).

Template Parameters

IdEnum	The event ID enum type.
DataType	The event data type (must satisfy event_data).
Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

evt	The event to post.
data	The event data.
timeout	Maximum time to wait for space in the event queue.

Returns: Success or an error (e.g., timeout).

Definition at line 650 of file event.hpp.

References idfxx::chrono::ticks(), and idfxx::timeout.

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

idfxx_event/include/idfxx/event.hpp

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ event_loop() [1/5]

◆ ~event_loop()

◆ event_loop() [2/5]

◆ event_loop() [3/5]

◆ event_loop() [4/5]

◆ event_loop() [5/5]

Member Function Documentation

◆ create_system()

◆ destroy_system()

◆ idf_handle()

◆ make()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ post() [1/4]

◆ post() [2/4]

◆ post() [3/4]

◆ post() [4/4]

◆ system()

◆ try_create_system()

◆ try_destroy_system()

◆ try_listener_remove()

◆ try_post() [1/4]

◆ try_post() [2/4]

◆ try_post() [3/4]

◆ try_post() [4/4]