Struct EventGroup 

pub struct EventGroup(/* private fields */);

Event group synchronization primitives. A set of event flags for thread synchronization.

Event groups contain multiple event bits (typically 24 bits) that can be manipulated independently. Threads can wait for specific combinations of bits to be set, making them ideal for complex synchronization scenarios.

Examples

Basic event signaling

use osal_rs::os::{EventGroup, EventGroupFn};
use core::time::Duration;
 
const EVENT_A: u32 = 0b0001;
const EVENT_B: u32 = 0b0010;
const EVENT_C: u32 = 0b0100;
 
let events = EventGroup::new().unwrap();
 
// Set event A
events.set(EVENT_A);
 
// Check if event A is set
let current = events.get();
if current & EVENT_A != 0 {
    println!("Event A is set");
}
 
// Clear event A
events.clear(EVENT_A);

Waiting for multiple events

use osal_rs::os::{EventGroup, EventGroupFn, Thread};
use alloc::sync::Arc;
use core::time::Duration;
 
const READY: u32 = 0b0001;
const DATA_AVAILABLE: u32 = 0b0010;
const STOP: u32 = 0b0100;
 
let events = Arc::new(EventGroup::new().unwrap());
let events_clone = events.clone();
 
// Worker thread waits for events
let worker = Thread::new("worker", 2048, 5, move || {
    loop {
        // Wait for either READY or STOP
        let bits = events_clone.wait_with_to_tick(
            READY | STOP,
            Duration::from_secs(1)
        );
         
        if bits & STOP != 0 {
            println!("Stopping...");
            break;
        }
         
        if bits & READY != 0 {
            println!("Ready to work!");
        }
    }
}).unwrap();
 
worker.start().unwrap();
 
// Signal events
events.set(READY);
Duration::from_secs(2).sleep();
events.set(STOP);

State machine synchronization

use osal_rs::os::{EventGroup, EventGroupFn};
use core::time::Duration;
 
const INIT_COMPLETE: u32 = 1 << 0;
const CONFIG_LOADED: u32 = 1 << 1;
const NETWORK_UP: u32 = 1 << 2;
const READY_TO_RUN: u32 = INIT_COMPLETE | CONFIG_LOADED | NETWORK_UP;
 
let state = EventGroup::new().unwrap();
 
// Different subsystems set their bits
state.set(INIT_COMPLETE);
state.set(CONFIG_LOADED);
state.set(NETWORK_UP);
 
// Wait for all systems to be ready
let current = state.wait_with_to_tick(READY_TO_RUN, Duration::from_secs(5));
 
if (current & READY_TO_RUN) == READY_TO_RUN {
    println!("All systems ready!");
}

ISR to thread signaling

use osal_rs::os::{EventGroup, EventGroupFn, Thread};
use alloc::sync::Arc;
 
const IRQ_EVENT: u32 = 1 << 0;
 
let events = Arc::new(EventGroup::new().unwrap());
let events_isr = events.clone();
 
// In interrupt handler:
// events_isr.set_from_isr(IRQ_EVENT).ok();
 
// Handler thread
let handler = Thread::new("handler", 2048, 5, move || {
    loop {
        let bits = events.wait(IRQ_EVENT, 1000);
        if bits & IRQ_EVENT != 0 {
            println!("Handling interrupt event");
            events.clear(IRQ_EVENT);
        }
    }
}).unwrap();

Implementations

impl EventGroup

pub const MAX_MASK: EventBits

Maximum usable event bits mask. FreeRTOS reserves the top 8 bits for internal use:

• For u32 (TickType): 0x00FFFFFF (24 bits usable)
• For u64 (TickType): 0x00FFFFFFFFFFFFFF (56 bits usable)

pub fn wait_with_to_tick( &self, mask: EventBits, timeout_ticks: impl ToTick, ) -> EventBits

Waits for specified event bits to be set with a timeout in ticks. This is a convenience method that converts a ToTick type to ticks and calls wait.

Examples

use osal_rs::os::{EventGroup, EventGroupFn};
use core::time::Duration;
let events = EventGroup::new().unwrap();
let bits = events.wait_with_to_tick(0b0001, Duration::from_secs(1));

impl EventGroup

pub fn new() -> Result<Self>

Creates a new event group.

Returns

• Ok(Self) - Successfully created event group
• Err(Error) - Creation failed (out of memory, etc.)

Examples

use osal_rs::os::{EventGroup, EventGroupFn};
 
let events = EventGroup::new().unwrap();

Trait Implementations

impl Debug for EventGroup

Formats the event group for debugging purposes.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for EventGroup

Allows dereferencing to the underlying FreeRTOS event group handle.

type Target = *const c_void

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for EventGroup

Formats the event group for display purposes.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for EventGroup

Automatically deletes the event group when it goes out of scope.

This ensures proper cleanup of FreeRTOS resources.

fn drop(&mut self)

Executes the destructor for this type.

impl EventGroup for EventGroup

fn set(&self, bits: EventBits) -> EventBits

Sets specified event bits.

This function sets (raises) the specified event bits in the event group. Any threads waiting for these bits may be unblocked.

Arguments

• bits - The event bits to set (bitwise OR to set multiple bits)

Returns

The event bits value after the set operation.

Examples

use osal_rs::os::{EventGroup, EventGroupFn};
 
let events = EventGroup::new().unwrap();
events.set(0b0001);  // Set bit 0
events.set(0b0110);  // Set bits 1 and 2

fn set_from_isr(&self, bits: EventBits) -> Result<()>

Sets specified event bits from an interrupt service routine (ISR).

This is the ISR-safe version of set(). It can be called from interrupt context and will trigger a context switch if a higher priority thread is unblocked by the bit setting.

Arguments

• bits - The event bits to set

Returns

• Ok(()) - Bits were successfully set
• Err(Error::QueueFull) - Operation failed

Examples

// In interrupt handler
use osal_rs::os::{EventGroup, EventGroupFn};
 
fn interrupt_handler(events: &EventGroup) {
    events.set_from_isr(0b0001).ok();
}

fn get(&self) -> EventBits

Gets the current value of event bits.

Returns the current state of all event bits in the event group. This is a non-blocking operation.

Returns

The current event bits value.

Examples

use osal_rs::os::{EventGroup, EventGroupFn};
 
let events = EventGroup::new().unwrap();
events.set(0b0101);
let current = events.get();
assert_eq!(current & 0b0101, 0b0101);

fn get_from_isr(&self) -> EventBits

Gets the current value of event bits from an ISR.

This is the ISR-safe version of get(). It can be called from interrupt context to read the current event bits.

Returns

The current event bits value.

Examples

// In interrupt handler
use osal_rs::os::{EventGroup, EventGroupFn};
 
fn interrupt_handler(events: &EventGroup) {
    let current = events.get_from_isr();
}

fn clear(&self, bits: EventBits) -> EventBits

Clears specified event bits.

This function clears (lowers) the specified event bits in the event group.

Arguments

• bits - The event bits to clear (bitwise OR to clear multiple bits)

Returns

The event bits value before the clear operation.

Examples

use osal_rs::os::{EventGroup, EventGroupFn};
 
let events = EventGroup::new().unwrap();
events.set(0b1111);
events.clear(0b0011);  // Clear bits 0 and 1
let current = events.get();
assert_eq!(current & 0b1111, 0b1100);

fn clear_from_isr(&self, bits: EventBits) -> Result<()>

Clears specified event bits from an ISR.

This is the ISR-safe version of clear(). It can be called from interrupt context to clear event bits.

Arguments

• bits - The event bits to clear

Returns

• Ok(()) - Bits were successfully cleared
• Err(Error::QueueFull) - Operation failed

Examples

// In interrupt handler
use osal_rs::os::{EventGroup, EventGroupFn};
 
fn interrupt_handler(events: &EventGroup) {
    events.clear_from_isr(0b0001).ok();
}

fn wait(&self, mask: EventBits, timeout_ticks: TickType) -> EventBits

Waits for specified event bits to be set.

Blocks the calling thread until any of the specified bits are set, or until the timeout expires. The bits are not cleared automatically.

Arguments

• mask - The event bits to wait for (bitwise OR for multiple bits)
• timeout_ticks - Maximum time to wait in system ticks (0 = no wait, MAX = wait forever)

Returns

The event bits value when the function returns. Check if the desired bits are set to determine if the wait succeeded or timed out.

Examples

use osal_rs::os::{EventGroup, EventGroupFn};
 
let events = EventGroup::new().unwrap();
 
// Wait for bit 0 or bit 1, timeout after 1000 ticks
let result = events.wait(0b0011, 1000);
if result & 0b0011 != 0 {
    println!("At least one bit was set");
}

fn delete(&mut self)

Deletes the event group and frees its resources.

This function destroys the event group and releases any memory allocated for it. After calling this, the event group should not be used. The handle is set to null after deletion.

Safety

Ensure no threads are waiting on this event group before deleting it.

Examples

use osal_rs::os::{EventGroup, EventGroupFn};
 
let mut events = EventGroup::new().unwrap();
// Use the event group...
events.delete();

impl Send for EventGroup

impl Sync for EventGroup