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 &&other) noexcept
	Move constructor.
event_group &	operator= (event_group &&other) noexcept
	Move assignment.
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.

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.

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.

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.

Exceptions

std::bad_alloc

if memory allocation fails.

Definition at line 87 of file event_group.hpp.

~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 100 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 > &&  other )

inlinenoexcept

Move constructor.

Transfers event group ownership.

Definition at line 110 of file event_group.hpp.

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 159 of file event_group.hpp.

References idfxx::to_underlying().

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 503 of file event_group.hpp.

References idfxx::to_underlying().

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 175 of file event_group.hpp.

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 515 of file event_group.hpp.

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 534 of file event_group.hpp.

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 > &&  other )

inlinenoexcept

Move assignment.

Transfers event group ownership.

Definition at line 114 of file event_group.hpp.

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 140 of file event_group.hpp.

References idfxx::to_underlying().

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 482 of file event_group.hpp.

References idfxx::to_underlying().

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 342 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 361 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 382 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 402 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 421 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 440 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 264 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 283 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 307 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 200 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 222 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 243 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