event_group (Event Groups)

Overview

Event group objects.

#include "etcpal/event_group.h"

An event group can be used to signal between different contexts that one or more events have occurred. Events in an event group are represented by bits in a bitfield, with the bitfield being of type etcpal_event_bits_t (which may be different sizes on different platforms but will always be at least the size of an int).

etcpal_event_group_t event_group;
#define EVENT_MESSAGE_RECEIVED (1 << 0)
#define EVENT_MESSAGE_ERROR (2 << 0)
 
bool keep_running;
 
void event_handler_thread(void* arg)
{
  while (keep_running)
  {
    etcpal_event_bits_t event = etcpal_event_group_wait(&event_group, EVENT_MESSAGE_RECEIVED | EVENT_MESSAGE_ERROR,
                                                        ETCPAL_EVENT_GROUP_AUTO_CLEAR);
    if (event & EVENT_MESSAGE_RECEIVED)
    {
      // Handle message received...
    }
    // Note: Depending on the user implementation, EVENT_MESSAGE_RECEIVED and EVENT_MESSAGE_ERROR
    // could be set at the same time.
    if (event & EVENT_MESSAGE_ERROR)
    {
      // Handle message error...
    }
 
    // Since we passed ETCPAL_EVENT_GROUP_AUTO_CLEAR above, the event bits do not need to be
    // explicitly cleared before the next iteration.
  }
}
 
void message_received_interrupt(void)
{
  // Handle/copy the message somehow...
  etcpal_event_group_set_bits_from_isr(&event_group, EVENT_MESSAGE_RECEIVED);
}
 
void message_error_interrupt(void)
{
  etcpal_event_group_set_bits_from_isr(&event_group, EVENT_MESSAGE_ERROR);
}
 
int main(void)
{
  etcpal_event_group_create(&event_group);
 
  EtcPalThreadParams thread_params = ETCPAL_THREAD_PARAMS_INIT;
  etcpal_thread_t handler_thread;
  keep_running = true;
  etcpal_thread_create(&handler_thread, &thread_params, event_handler_thread, NULL);
 
  // ...
}

NOTE: Due to platform differences, it's not recommended to have multiple threads that wait on the same event group. The behavior will not be predictable across platforms. See ETCPAL_EVENT_GROUP_WAKES_MULTIPLE_THREADS for more information.

etcpal_event_group implementations use different constructs under the hood on various platforms. Also, different platforms affect the behavior of certain functions.

Platform	Event Groups available	ETCPAL_EVENT_GROUP_HAS_TIMED_WAIT	ETCPAL_EVENT_GROUP_HAS_ISR_FUNCTIONS	ETCPAL_EVENT_GROUP_WAKES_MULTIPLE_THREADS	Underlying Type
FreeRTOS	Yes	Yes	Yes	Yes	Event Groups
Linux	Yes	No	No	No	pthread_cond
macOS	Yes	No	No	No	pthread_cond
MQX	No	N/A	N/A	N/A	N/A
Windows	Yes	No	No	No	Condition Variables
Zephyr	Yes	Yes	Yes	Yes	Condition Variables

Macros
#define	ETCPAL_EVENT_GROUP_HAS_TIMED_WAIT   /* platform-defined */
	Whether etcpal_event_group_timed_wait() is meaningful on this platform. More...
#define	ETCPAL_EVENT_GROUP_HAS_ISR_FUNCTIONS   /* platform-defined */
	Whether the etcpal_event_group_*_from_isr() functions are meaningful on this platform. More...
#define	ETCPAL_EVENT_GROUP_WAKES_MULTIPLE_THREADS   /* platform-defined */
	Whether etcpal_event_group_set_bits() wakes multiple threads waiting on the same event. More...
#define	ETCPAL_EVENT_GROUP_NUM_USABLE_BITS   /* platform-defined */
	How many bits in the etcpal_event_bits_t type are usable, starting from the LSB. More...

Typedefs
typedef PLATFORM_DEFINED	etcpal_event_group_t
	The event group identifier. More...
typedef PLATFORM_DEFINED	etcpal_event_bits_t
	The type that holds the event bitfield. More...

Functions
bool	etcpal_event_group_create (etcpal_event_group_t *id)
	Create a new event group. More...
etcpal_event_bits_t	etcpal_event_group_wait (etcpal_event_group_t *id, etcpal_event_bits_t bits, int flags)
	Wait for one or more bits in an event group. More...
etcpal_event_bits_t	etcpal_event_group_timed_wait (etcpal_event_group_t *id, etcpal_event_bits_t bits, int flags, int timeout_ms)
	Wait for one or more bits in an event group, giving up after a timeout. More...
void	etcpal_event_group_set_bits (etcpal_event_group_t *id, etcpal_event_bits_t bits_to_set)
	Set one or more bits in an event group. More...
etcpal_event_bits_t	etcpal_event_group_get_bits (etcpal_event_group_t *id)
	Get the current bitfield from an event group. More...
void	etcpal_event_group_clear_bits (etcpal_event_group_t *id, etcpal_event_bits_t bits_to_clear)
	Clear one or more bits in an event group. More...
void	etcpal_event_group_destroy (etcpal_event_group_t *id)
	Destroy an event group. More...
void	etcpal_event_group_set_bits_from_isr (etcpal_event_group_t *id, etcpal_event_bits_t bits_to_set)
	Set one or more bits in an event group from an interrupt context. More...
etcpal_event_bits_t	etcpal_event_group_get_bits_from_isr (etcpal_event_group_t *id)
	Get the current bitfield from an event group from an interrupt context. More...
void	etcpal_event_group_clear_bits_from_isr (etcpal_event_group_t *id, etcpal_event_bits_t bits_to_clear)
	Clear one or more bits in an event group from an interrupt context. More...

Flags for etcpal_event_group_wait() and etcpal_event_group_timed_wait().
#define	ETCPAL_EVENT_GROUP_AUTO_CLEAR   0x1
	Clear bits automatically when they are returned from a wait function. More...
#define	ETCPAL_EVENT_GROUP_WAIT_FOR_ALL   0x2
	Wait for all specified bits. More...

Macro Definition Documentation

ETCPAL_EVENT_GROUP_AUTO_CLEAR

#define ETCPAL_EVENT_GROUP_AUTO_CLEAR   0x1

Clear bits automatically when they are returned from a wait function.

If this flag is not specified, bits will remain set in an event group after the wait function returns. They can be cleared by waiting again with this flag specified, or explicitly cleared with etcpal_event_group_clear_bits().

ETCPAL_EVENT_GROUP_HAS_ISR_FUNCTIONS

#define ETCPAL_EVENT_GROUP_HAS_ISR_FUNCTIONS   /* platform-defined */

Whether the etcpal_event_group_*_from_isr() functions are meaningful on this platform.

Some platforms have a different method for interacting with events from an interrupt context. If defined to 0, the etcpal_event_group_*_from_isr() functions execute the equivalent of etcpal_event_group_*().

ETCPAL_EVENT_GROUP_HAS_TIMED_WAIT

#define ETCPAL_EVENT_GROUP_HAS_TIMED_WAIT   /* platform-defined */

Whether etcpal_event_group_timed_wait() is meaningful on this platform.

If defined to 0, etcpal_event_group_timed_wait() executes the equivalent of etcpal_event_group_wait() if given a nonzero timeout, or returns immediately with the status of the event group if given a timeout of 0.

ETCPAL_EVENT_GROUP_NUM_USABLE_BITS

#define ETCPAL_EVENT_GROUP_NUM_USABLE_BITS   /* platform-defined */

How many bits in the etcpal_event_bits_t type are usable, starting from the LSB.

Some platforms reserve event bits for internal implementation resources. At time of writing, FreeRTOS is the only platform that does this. On other platforms, this value will be defined to sizeof(etcpal_event_bits_t) * 8.

ETCPAL_EVENT_GROUP_WAIT_FOR_ALL

#define ETCPAL_EVENT_GROUP_WAIT_FOR_ALL   0x2

Wait for all specified bits.

Do not return from etcpal_event_group_wait() until all bits specified in the bits argument are received. Do not return from etcpal_event_group_timed_wait() until either all bits specified in the bits argument are received or the timeout occurs.

If this flag was not specified for an event group, etcpal_event_group_wait() and etcpal_event_group_timed_wait() will return when at least one bit in the bit mask is matched.

ETCPAL_EVENT_GROUP_WAKES_MULTIPLE_THREADS

#define ETCPAL_EVENT_GROUP_WAKES_MULTIPLE_THREADS   /* platform-defined */

Whether etcpal_event_group_set_bits() wakes multiple threads waiting on the same event.

Due to platform restrictions, there is currently no way to ensure predictable behavior across platforms when multiple threads wait on the same event. On RTOS platforms, generally, when an event bit that is being waited on by multiple threads is set, all threads are woken and the event state is delivered atomically to all of them. This behavior is difficult to replicate on desktop platforms, so they are typically implemented as waking only the first waiting thread.

Typedef Documentation

etcpal_event_bits_t

typedef PLATFORM_DEFINED etcpal_event_bits_t

The type that holds the event bitfield.

This is always an integer type of some kind. Depending on the platform, the number of usable bits in this type may be restricted. Use ETCPAL_EVENT_GROUP_NUM_USABLE_BITS to determine how many bits are usable.

etcpal_event_group_t

typedef PLATFORM_DEFINED etcpal_event_group_t

The event group identifier.

Depending on the platform, this could be a scalar type or a struct.

Function Documentation

etcpal_event_group_clear_bits()

void etcpal_event_group_clear_bits	(	etcpal_event_group_t *	id,
		etcpal_event_bits_t	bits_to_clear
	)

Clear one or more bits in an event group.

Parameters

id	Identifier for the event group in which to clear bits.
bits_to_clear	Mask of bits to clear.

etcpal_event_group_clear_bits_from_isr()

void etcpal_event_group_clear_bits_from_isr	(	etcpal_event_group_t *	id,
		etcpal_event_bits_t	bits_to_clear
	)

Clear one or more bits in an event group from an interrupt context.

This function is only meaningful on some platforms; namely, those which have a different method for interacting with event groups from an interrupt context. The value of ETCPAL_EVENT_GROUP_HAS_ISR_FUNCTIONS can be used to determine whether this function is meaningful on the current platform. If it is defined to 0, this function simply executes the equivalent of etcpal_event_group_get_bits().

Parameters

id	Identifier for the event group in which to clear bits.
bits_to_clear	Mask of bits to clear.

etcpal_event_group_create()

bool etcpal_event_group_create

(

etcpal_event_group_t *

id

)

Create a new event group.

At creation, none of the bits in the event group bitfield are set.

Parameters

[out]

id

Event identifier on which to create an event group. If this function returns true, id becomes valid for calls to other etcpal_event_group API functions.

Returns

true: The event group was created.

false: The event group was not created.

etcpal_event_group_destroy()

void etcpal_event_group_destroy

(

etcpal_event_group_t *

id

)

Destroy an event group.

Parameters

id	Identifier for the event group to destroy.

etcpal_event_group_get_bits()

etcpal_event_bits_t etcpal_event_group_get_bits

(

etcpal_event_group_t *

id

)

Get the current bitfield from an event group.

Parameters

id	Identifier for the event group from which to get the bits.

Returns

The bitfield (or 0 if an invalid argument was given).

etcpal_event_group_get_bits_from_isr()

etcpal_event_bits_t etcpal_event_group_get_bits_from_isr

(

etcpal_event_group_t *

id

)

Get the current bitfield from an event group from an interrupt context.

This function is only meaningful on some platforms; namely, those which have a different method for interacting with event groups from an interrupt context. The value of ETCPAL_EVENT_GROUP_HAS_ISR_FUNCTIONS can be used to determine whether this function is meaningful on the current platform. If it is defined to 0, this function simply executes the equivalent of etcpal_event_group_get_bits().

Parameters

id	Identifier for the event group from which to get the bits.

Returns

The bitfield (or 0 if an invalid argument was given).

etcpal_event_group_set_bits()

void etcpal_event_group_set_bits	(	etcpal_event_group_t *	id,
		etcpal_event_bits_t	bits_to_set
	)

Set one or more bits in an event group.

If one or more threads are waiting for the bits that were set, at least one of those threads will be woken up (whether it is one or all depends on ETCPAL_EVENT_GROUP_WAKES_MULTIPLE_THREADS). The bits will remain set until cleared, either through one of the etcpal_event_group_wait() functions called with the ETCPAL_EVENT_GROUP_AUTO_CLEAR flag, or explicitly using etcpal_event_group_clear_bits().

Parameters

id	Identifier for the event group in which to set bits.
bits_to_set	Mask of bits in the event group to set.

etcpal_event_group_set_bits_from_isr()

void etcpal_event_group_set_bits_from_isr	(	etcpal_event_group_t *	id,
		etcpal_event_bits_t	bits_to_set
	)

Set one or more bits in an event group from an interrupt context.

This function is only meaningful on some platforms; namely, those which have a different method for interacting with event groups from an interrupt context. The value of ETCPAL_EVENT_GROUP_HAS_ISR_FUNCTIONS can be used to determine whether this function is meaningful on the current platform. If it is defined to 0, this function simply executes the equivalent of etcpal_event_group_set_bits().

If one or more threads are waiting for the bits that were set, at least one of those threads will be woken up (whether it is one or all depends on ETCPAL_EVENT_GROUP_WAKES_MULTIPLE_THREADS). The bits will remain set until cleared, either through one of the etcpal_event_group_wait() functions on an event group that was created with the ETCPAL_EVENT_GROUP_AUTO_CLEAR flag, or explicitly using etcpal_event_group_clear_bits().

Parameters

id	Identifier for the event group in which to set bits.
bits_to_set	Mask of bits in the event group to set.

etcpal_event_group_timed_wait()

etcpal_event_bits_t etcpal_event_group_timed_wait	(	etcpal_event_group_t *	id,
		etcpal_event_bits_t	bits,
		int	flags,
		int	timeout_ms
	)

Wait for one or more bits in an event group, giving up after a timeout.

Pass a mask of bits to wait for. If ETCPAL_EVENT_GROUP_WAIT_FOR_ALL is given as a flag, blocks until either all bits are set or the timeout passes. Otherwise, blocks until any of the bits are set or the timeout passes. If ETCPAL_EVENT_GROUP_AUTO_CLEAR is given as a flag, any bits will be cleared automatically from the event's state before the function returns. Otherwise, etcpal_event_group_clear_bits() must be used to clear bits.

Parameters

id	Identifier for the event group for which to wait.
bits	Mask of bits in the event group to wait for.
flags	Flags that define waiting options.
timeout_ms	Maximum amount of time to wait for the event bits, in milliseconds. If ETCPAL_WAIT_FOREVER is given, the result is the same as if etcpal_event_group_wait() was called.

Returns

Bitmask representing the bits that were set at the time that either the requested condition was fulfilled or a timeout occurred (note that this could include other bits that were not requested).

etcpal_event_group_wait()

etcpal_event_bits_t etcpal_event_group_wait	(	etcpal_event_group_t *	id,
		etcpal_event_bits_t	bits,
		int	flags
	)

Wait for one or more bits in an event group.

Pass a mask of bits to wait for. If ETCPAL_EVENT_GROUP_WAIT_FOR_ALL is given as a flag, blocks until all bits are set. Otherwise, blocks until any of the bits are set. If ETCPAL_EVENT_GROUP_AUTO_CLEAR is given as a flag, any bits returned will be cleared automatically from the event's state before the function returns. Otherwise, etcpal_event_group_clear_bits() must be used to clear bits.

Parameters

id	Identifier for the event group for which to wait.
bits	Mask of bits in the event group to wait for.
flags	Flags that define waiting options.

Returns

Bitmask representing the bits that were set at the time the requested condition was fulfilled (note that this could include other bits that were not requested).