Mastering Event Flag Groups: Utility Services & Data Structures in Nucleus RTOS/SE

View the RTOS Revealed series

This article continues the look at event flag groups.

Event Flag Group Utility Services

Nucleus RTOS provides three dedicated API calls that streamline interaction with event flag groups: retrieving detailed group information, obtaining the total count of groups, and accessing pointers to all groups within an application. The first two functions are fully supported in Nucleus SE.

Event Flag Group Information

This service call delivers key data about a specified event flag group. In Nucleus SE the interface is trimmed – object naming and suspend ordering are omitted, and task suspend information is returned only when the feature is enabled.

Nucleus RTOS API Call for Event Group Information

Service call prototype:

STATUS NU_Event_Group_Information(NU_EVENT_GROUP *group,
CHAR *name, UNSIGNED *event_flags, UNSIGNED *tasks_waiting,
NU_TASK **first_task);

Parameters:

group – pointer to the user‑supplied event flag group control block

name – 8‑character buffer for the group’s name (including null terminator)

event_flags – pointer to a variable that will receive the current flag value

tasks_waiting – pointer to a variable that will receive the number of tasks suspended on this group

first_task – pointer to a NU_TASK variable that will receive a pointer to the first suspended task

Returns:

NU_SUCCESS – call completed successfully

NU_INVALID_GROUP – supplied group pointer is invalid

Nucleus SE API Call for Event Group Information

This API provides the same core functionality as its RTOS counterpart.

Service call prototype:

STATUS NUSE_Event_Group_Information(NUSE_EVENT_GROUP group,
U8 *event_flags, U8 *tasks_waiting, NUSE_TASK *first_task);

Parameters:

group – index of the event flag group

event_flags – pointer to receive the current flag value

tasks_waiting – pointer to receive the number of suspended tasks (0 if task suspend is disabled)

first_task – pointer to receive the index of the first suspended task (0 if task suspend is disabled)

Returns:

NUSE_SUCCESS – call completed successfully

NUSE_INVALID_GROUP – group index is invalid

Nucleus SE Implementation of Event Group Information

The implementation is straightforward: the current flag value is read, and if blocking APIs are enabled, the waiting‑task count and first‑task index are computed; otherwise both are set to 0.

*event_flags = NUSE_Event_Group_Data[group];#if NUSE_BLOCKING_ENABLE *tasks_waiting = NUSE_Event_Group_Blocking_Count[group]; if (NUSE_Event_Group_Blocking_Count[group] != 0) { U8 index; for (index=0; index  
Obtaining the Number of Event Flag Groups
  
In Nucleus RTOS, the number of groups can change dynamically; the call returns the current count.  In Nucleus SE, the count is fixed at build time.
  
Nucleus RTOS API Call for Event Flag Group Count
  
Service call prototype:
  
  
UNSIGNED NU_Established_Event_Groups(VOID);
  
  
Returns:
  
  
The current number of created event flag groups in the application
  
  
Nucleus SE API Call for Event Flag Group Count
  
Service call prototype:
  
  
U8 NUSE_Event_Group_Count(void);
  
  
Returns:
  
  
The number of configured event flag groups in the application
  
  
Nucleus SE Implementation of Event Flag Group Count
  
The function simply returns the value of the compile‑time constant NUSE_EVENT_GROUP_NUMBER.
  

            


            

               Semaphores in Nucleus SE: Overview, Configuration, and API Essentials        
                Event Flag Groups in Nucleus SE: An Introductory Guide to Configuration and API Usage