idfxx::event_group< E > Class Template Reference

Type-safe inter-task event group for bit-level synchronization. More...

Classes
struct	isr_set_result
	Result of setting event bits from ISR context. More...

Public Member Functions
	event_group ()
	Creates an event group.
	~event_group ()
	Destroys the event group and releases all resources.
	event_group (const event_group &)=delete
event_group &	operator= (const event_group &)=delete
	event_group (event_group &&)=delete
event_group &	operator= (event_group &&)=delete
flags< E >	set (flags< E > bits) noexcept
	Sets event bits in the event group.
flags< E >	clear (flags< E > bits) noexcept
	Clears event bits in the event group.
flags< E >	get () const noexcept
	Returns the current event bits.
flags< E >	wait (flags< E > bits, wait_mode mode, bool clear_on_exit=true)
	Waits for event bits to be set, blocking indefinitely.
template<typename Rep , typename Period >
flags< E >	wait (flags< E > bits, wait_mode mode, const std::chrono::duration< Rep, Period > &timeout, bool clear_on_exit=true)
	Waits for event bits to be set, with a timeout.
template<typename Clock , typename Duration >
flags< E >	wait_until (flags< E > bits, wait_mode mode, const std::chrono::time_point< Clock, Duration > &deadline, bool clear_on_exit=true)
	Waits for event bits to be set, with a deadline.
result< flags< E > >	try_wait (flags< E > bits, wait_mode mode, bool clear_on_exit=true)
	Waits for event bits to be set, blocking indefinitely.
template<typename Rep , typename Period >
result< flags< E > >	try_wait (flags< E > bits, wait_mode mode, const std::chrono::duration< Rep, Period > &timeout, bool clear_on_exit=true)
	Waits for event bits to be set, with a timeout.
template<typename Clock , typename Duration >
result< flags< E > >	try_wait_until (flags< E > bits, wait_mode mode, const std::chrono::time_point< Clock, Duration > &deadline, bool clear_on_exit=true)
	Waits for event bits to be set, with a deadline.
flags< E >	sync (flags< E > set_bits, flags< E > wait_bits)
	Atomically sets bits and waits for other bits, blocking indefinitely.
template<typename Rep , typename Period >
flags< E >	sync (flags< E > set_bits, flags< E > wait_bits, const std::chrono::duration< Rep, Period > &timeout)
	Atomically sets bits and waits for other bits, with a timeout.
template<typename Clock , typename Duration >
flags< E >	sync_until (flags< E > set_bits, flags< E > wait_bits, const std::chrono::time_point< Clock, Duration > &deadline)
	Atomically sets bits and waits for other bits, with a deadline.
result< flags< E > >	try_sync (flags< E > set_bits, flags< E > wait_bits)
	Atomically sets bits and waits for other bits, blocking indefinitely.
template<typename Rep , typename Period >
result< flags< E > >	try_sync (flags< E > set_bits, flags< E > wait_bits, const std::chrono::duration< Rep, Period > &timeout)
	Atomically sets bits and waits for other bits, with a timeout.
template<typename Clock , typename Duration >
result< flags< E > >	try_sync_until (flags< E > set_bits, flags< E > wait_bits, const std::chrono::time_point< Clock, Duration > &deadline)
	Atomically sets bits and waits for other bits, with a deadline.
isr_set_result IRAM_ATTR	set_from_isr (flags< E > bits) noexcept
	Sets event bits from ISR context.
flags< E > IRAM_ATTR	clear_from_isr (flags< E > bits) noexcept
	Clears event bits from ISR context.
flags< E > IRAM_ATTR	get_from_isr () const noexcept
	Returns the current event bits from ISR context.
EventGroupHandle_t	idf_handle () const noexcept
	Returns the underlying FreeRTOS event group handle.

Static Public Member Functions
static result< std::unique_ptr< event_group > >	make ()
	Creates an event group.

Detailed Description

template<flag_enum E>
requires (sizeof(std::underlying_type_t<E>) <= sizeof(EventBits_t))
class idfxx::event_group< E >

Type-safe inter-task event group for bit-level synchronization.

A fixed set of event bits that can be set, cleared, and waited upon across tasks and ISRs. Event bits are represented as a flags<E> value, providing full type safety.

Event groups are non-copyable and non-movable. Use the factory method make() for result-based construction or the throwing constructor when exceptions are enabled.

Template Parameters

E	The flag enum type (must satisfy flag_enum concept). The underlying type must fit within EventBits_t.

enum class my_event : uint32_t {
    data_ready = 1u << 0,
    timeout    = 1u << 1,
    error      = 1u << 2,
};
template<> inline constexpr bool idfxx::enable_flags_operators<my_event> = true;
 
// Create an event group
idfxx::event_group<my_event> eg;
 
// Set bits from one task
eg.set(my_event::data_ready);
 
// Wait for bits in another task
auto bits = eg.wait(my_event::data_ready, idfxx::wait_mode::any);

Definition at line 80 of file event_group.hpp.

Constructor & Destructor Documentation

event_group() [1/3]

template<flag_enum E>

idfxx::event_group< E >::event_group ( )

inline

Creates an event group.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

with idfxx::errc::no_mem if memory allocation fails.

Definition at line 89 of file event_group.hpp.

References idfxx::no_mem.

~event_group()

template<flag_enum E>

idfxx::event_group< E >::~event_group ( )

inline

Destroys the event group and releases all resources.

Any tasks blocked waiting on this event group are unblocked and receive a return value of zero.

Definition at line 117 of file event_group.hpp.

event_group() [2/3]

template<flag_enum E>

idfxx::event_group< E >::event_group ( const event_group< E > &  )

delete

event_group() [3/3]

template<flag_enum E>

idfxx::event_group< E >::event_group ( event_group< E > &&  )

delete

Member Function Documentation

clear()

template<flag_enum E>

flags< E > idfxx::event_group< E >::clear ( flags< E >  bits )

inlinenoexcept

Clears event bits in the event group.

Clears the specified bits. This operation always succeeds and never blocks.

Parameters

bits	The bits to clear.

Returns

The event group bits before clearing.

Definition at line 161 of file event_group.hpp.

References idfxx::flags< E >::from_raw().

clear_from_isr()

template<flag_enum E>

flags< E > IRAM_ATTR idfxx::event_group< E >::clear_from_isr ( flags< E >  bits )

inlinenoexcept

Clears event bits from ISR context.

Clearing bits from an ISR is deferred via xEventGroupClearBitsFromISR. The returned value is the bits before the deferred clear takes effect.

Parameters

bits	The bits to clear.

Returns

The event group bits before the clear was requested.

Note

The clear is deferred to the timer daemon task. The bits may not be cleared immediately.

Definition at line 496 of file event_group.hpp.

References idfxx::flags< E >::from_raw().

get()

template<flag_enum E>

flags< E > idfxx::event_group< E >::get ( ) const

inlinenoexcept

Returns the current event bits.

Returns

The current event group bits.

Definition at line 174 of file event_group.hpp.

References idfxx::flags< E >::from_raw().

get_from_isr()

template<flag_enum E>

flags< E > IRAM_ATTR idfxx::event_group< E >::get_from_isr ( ) const

inlinenoexcept

Returns the current event bits from ISR context.

Returns

The current event group bits.

Definition at line 507 of file event_group.hpp.

References idfxx::flags< E >::from_raw().

idf_handle()

template<flag_enum E>

EventGroupHandle_t idfxx::event_group< E >::idf_handle ( ) const

inlinenoexcept

Returns the underlying FreeRTOS event group handle.

Provides access to the raw handle for interoperability with ESP-IDF APIs that require an EventGroupHandle_t.

Returns

The EventGroupHandle_t.

Definition at line 523 of file event_group.hpp.

make()

template<flag_enum E>

static result< std::unique_ptr< event_group > > idfxx::event_group< E >::make ( )

inlinestatic

Creates an event group.

Returns

The new event group, or an error.

Return values

no_mem

Memory allocation failed.

Definition at line 103 of file event_group.hpp.

References idfxx::error(), and idfxx::no_mem.

operator=() [1/2]

template<flag_enum E>

event_group & idfxx::event_group< E >::operator= ( const event_group< E > &  )

delete

operator=() [2/2]

template<flag_enum E>

event_group & idfxx::event_group< E >::operator= ( event_group< E > &&  )

delete

set()

template<flag_enum E>

flags< E > idfxx::event_group< E >::set ( flags< E >  bits )

inlinenoexcept

Sets event bits in the event group.

Sets the specified bits. Any tasks waiting for these bits are unblocked if their wait condition is now satisfied.

This operation always succeeds and never blocks.

Parameters

bits	The bits to set.

Returns

The event group bits at the time this call returns. The returned value may have bits cleared by tasks that were unblocked.

Definition at line 145 of file event_group.hpp.

References idfxx::flags< E >::from_raw().

set_from_isr()

template<flag_enum E>

isr_set_result IRAM_ATTR idfxx::event_group< E >::set_from_isr ( flags< E >  bits )

inlinenoexcept

Sets event bits from ISR context.

Setting bits from an ISR is deferred to the timer daemon task via xEventGroupSetBitsFromISR. The operation may fail if the timer command queue is full.

Parameters

bits	The bits to set.

Returns

Result containing success status and whether a context switch should be requested.

Note

Pass the yield field to idfxx::yield_from_isr() to perform the context switch if needed.

void IRAM_ATTR my_isr() {
    auto [success, yield] = eg->set_from_isr(my_event::data_ready);
    idfxx::yield_from_isr(yield);
}

Definition at line 478 of file event_group.hpp.

sync() [1/2]

template<flag_enum E>

flags< E > idfxx::event_group< E >::sync ( flags< E >  set_bits, flags< E >  wait_bits  )

inline

Atomically sets bits and waits for other bits, blocking indefinitely.

Sets the specified bits and then waits for all of the wait bits to be set. This is used for task rendezvous — multiple tasks each set their own bit and wait for all bits to be set.

The bits set by this call and the bits waited for are automatically cleared before the function returns.

Parameters

set_bits	The bits to set before waiting.
wait_bits	The bits to wait for (all must be set).

Returns

The event group bits at the time all wait bits were set (before clearing).

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

with idfxx::errc::timeout if the wait condition is not satisfied.

Definition at line 338 of file event_group.hpp.

References idfxx::unwrap().

sync() [2/2]

template<flag_enum E>

template<typename Rep , typename Period >

flags< E > idfxx::event_group< E >::sync ( flags< E >  set_bits, flags< E >  wait_bits, const std::chrono::duration< Rep, Period > &  timeout  )

inline

Atomically sets bits and waits for other bits, with a timeout.

Sets the specified bits and then waits for all of the wait bits to be set.

Template Parameters

Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

set_bits	The bits to set before waiting.
wait_bits	The bits to wait for (all must be set).
timeout	Maximum time to wait.

Returns

The event group bits at the time all wait bits were set (before clearing).

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

with idfxx::errc::timeout if the wait condition is not satisfied within the timeout.

Definition at line 357 of file event_group.hpp.

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

sync_until()

template<flag_enum E>

template<typename Clock , typename Duration >

flags< E > idfxx::event_group< E >::sync_until ( flags< E >  set_bits, flags< E >  wait_bits, const std::chrono::time_point< Clock, Duration > &  deadline  )

inline

Atomically sets bits and waits for other bits, with a deadline.

Sets the specified bits and then waits for all of the wait bits to be set.

Template Parameters

Clock	The clock type.
Duration	The duration type of the time point.

Parameters

set_bits	The bits to set before waiting.
wait_bits	The bits to wait for (all must be set).
deadline	The time point at which to stop waiting.

Returns

The event group bits at the time all wait bits were set (before clearing).

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

with idfxx::errc::timeout if the wait condition is not satisfied before the deadline.

Definition at line 378 of file event_group.hpp.

References idfxx::unwrap().

try_sync() [1/2]

template<flag_enum E>

result< flags< E > > idfxx::event_group< E >::try_sync ( flags< E >  set_bits, flags< E >  wait_bits  )

inline

Atomically sets bits and waits for other bits, blocking indefinitely.

Sets the specified bits and then waits for all of the wait bits to be set. This is used for task rendezvous — multiple tasks each set their own bit and wait for all bits to be set.

The bits set by this call and the bits waited for are automatically cleared before the function returns.

Parameters

set_bits	The bits to set before waiting.
wait_bits	The bits to wait for (all must be set).

Returns

The event group bits at the time all wait bits were set (before clearing), or an error.

Return values

timeout

The wait condition was not satisfied.

Definition at line 398 of file event_group.hpp.

try_sync() [2/2]

template<flag_enum E>

template<typename Rep , typename Period >

result< flags< E > > idfxx::event_group< E >::try_sync ( flags< E >  set_bits, flags< E >  wait_bits, const std::chrono::duration< Rep, Period > &  timeout  )

inline

Atomically sets bits and waits for other bits, with a timeout.

Sets the specified bits and then waits for all of the wait bits to be set.

Template Parameters

Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

set_bits	The bits to set before waiting.
wait_bits	The bits to wait for (all must be set).
timeout	Maximum time to wait.

Returns

The event group bits at the time all wait bits were set (before clearing), or an error.

Return values

timeout

The wait condition was not satisfied within the timeout.

Definition at line 417 of file event_group.hpp.

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

try_sync_until()

template<flag_enum E>

template<typename Clock , typename Duration >

result< flags< E > > idfxx::event_group< E >::try_sync_until ( flags< E >  set_bits, flags< E >  wait_bits, const std::chrono::time_point< Clock, Duration > &  deadline  )

inline

Atomically sets bits and waits for other bits, with a deadline.

Sets the specified bits and then waits for all of the wait bits to be set.

Template Parameters

Clock	The clock type.
Duration	The duration type of the time point.

Parameters

set_bits	The bits to set before waiting.
wait_bits	The bits to wait for (all must be set).
deadline	The time point at which to stop waiting.

Returns

The event group bits at the time all wait bits were set (before clearing), or an error.

Return values

timeout

The wait condition was not satisfied before the deadline.

Definition at line 436 of file event_group.hpp.

References idfxx::chrono::ticks().

try_wait() [1/2]

template<flag_enum E>

result< flags< E > > idfxx::event_group< E >::try_wait ( flags< E >  bits, wait_mode  mode, bool  clear_on_exit = true  )

inline

Waits for event bits to be set, blocking indefinitely.

Blocks until the wait condition is satisfied.

Parameters

bits	The bits to wait for.
mode	Whether to wait for any or all of the specified bits.
clear_on_exit	If true, the waited-for bits are cleared before returning.

Returns

The event group bits at the time the wait condition was satisfied, or an error.

Return values

timeout

The wait condition was not satisfied.

Definition at line 260 of file event_group.hpp.

try_wait() [2/2]

template<flag_enum E>

template<typename Rep , typename Period >

result< flags< E > > idfxx::event_group< E >::try_wait ( flags< E >  bits, wait_mode  mode, const std::chrono::duration< Rep, Period > &  timeout, bool  clear_on_exit = true  )

inline

Waits for event bits to be set, with a timeout.

Blocks until the wait condition is satisfied or the timeout expires.

Template Parameters

Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

bits	The bits to wait for.
mode	Whether to wait for any or all of the specified bits.
timeout	Maximum time to wait.
clear_on_exit	If true, the waited-for bits are cleared before returning.

Returns

The event group bits at the time the wait condition was satisfied, or an error.

Return values

timeout

The wait condition was not satisfied within the timeout.

Definition at line 279 of file event_group.hpp.

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

try_wait_until()

template<flag_enum E>

template<typename Clock , typename Duration >

result< flags< E > > idfxx::event_group< E >::try_wait_until ( flags< E >  bits, wait_mode  mode, const std::chrono::time_point< Clock, Duration > &  deadline, bool  clear_on_exit = true  )

inline

Waits for event bits to be set, with a deadline.

Blocks until the wait condition is satisfied or the deadline is reached.

Template Parameters

Clock	The clock type.
Duration	The duration type of the time point.

Parameters

bits	The bits to wait for.
mode	Whether to wait for any or all of the specified bits.
deadline	The time point at which to stop waiting.
clear_on_exit	If true, the waited-for bits are cleared before returning.

Returns

The event group bits at the time the wait condition was satisfied, or an error.

Return values

timeout

The wait condition was not satisfied before the deadline.

Definition at line 303 of file event_group.hpp.

References idfxx::chrono::ticks().

wait() [1/2]

template<flag_enum E>

flags< E > idfxx::event_group< E >::wait ( flags< E >  bits, wait_mode  mode, bool  clear_on_exit = true  )

inline

Waits for event bits to be set, blocking indefinitely.

Blocks until the wait condition is satisfied.

Parameters

bits	The bits to wait for.
mode	Whether to wait for any or all of the specified bits.
clear_on_exit	If true, the waited-for bits are cleared before returning.

Returns

The event group bits at the time the wait condition was satisfied.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

with idfxx::errc::timeout if the wait condition is not satisfied.

Definition at line 196 of file event_group.hpp.

References idfxx::unwrap().

wait() [2/2]

template<flag_enum E>

template<typename Rep , typename Period >

flags< E > idfxx::event_group< E >::wait ( flags< E >  bits, wait_mode  mode, const std::chrono::duration< Rep, Period > &  timeout, bool  clear_on_exit = true  )

inline

Waits for event bits to be set, with a timeout.

Blocks until the wait condition is satisfied or the timeout expires.

Template Parameters

Rep	The representation type of the duration.
Period	The period type of the duration.

Parameters

bits	The bits to wait for.
mode	Whether to wait for any or all of the specified bits.
timeout	Maximum time to wait.
clear_on_exit	If true, the waited-for bits are cleared before returning.

Returns

The event group bits at the time the wait condition was satisfied.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

with idfxx::errc::timeout if the wait condition is not satisfied within the timeout.

Definition at line 218 of file event_group.hpp.

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

wait_until()

template<flag_enum E>

template<typename Clock , typename Duration >

flags< E > idfxx::event_group< E >::wait_until ( flags< E >  bits, wait_mode  mode, const std::chrono::time_point< Clock, Duration > &  deadline, bool  clear_on_exit = true  )

inline

Waits for event bits to be set, with a deadline.

Blocks until the wait condition is satisfied or the deadline is reached.

Template Parameters

Clock	The clock type.
Duration	The duration type of the time point.

Parameters

bits	The bits to wait for.
mode	Whether to wait for any or all of the specified bits.
deadline	The time point at which to stop waiting.
clear_on_exit	If true, the waited-for bits are cleared before returning.

Returns

The event group bits at the time the wait condition was satisfied.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

with idfxx::errc::timeout if the wait condition is not satisfied before the deadline.

Definition at line 239 of file event_group.hpp.

References idfxx::unwrap().

---

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

• idfxx_event_group/include/idfxx/event_group.hpp