Skip to main content

QueueFn

osal_rs::os

Trait QueueFn 

Source 
pub trait QueueFn {
    // Required methods
    fn fetch(&self, buffer: &mut [u8], time: TickType) -> Result<()>;
    fn fetch_from_isr(&self, buffer: &mut [u8]) -> Result<()>;
    fn post(&self, item: &[u8], time: TickType) -> Result<()>;
    fn post_from_isr(&self, item: &[u8]) -> Result<()>;
    fn delete(&mut self);
}
Expand description

Raw byte-oriented queue for inter-task message passing.

This trait defines a FIFO queue that works with raw byte arrays, suitable for variable-sized messages or when type safety is not required.

§Memory Layout

The queue capacity is fixed at creation time. Each message slot can hold up to the maximum message size specified during creation.

§Thread Safety

All methods are thread-safe. Multiple producers and consumers can safely access the same queue concurrently.

§Performance

Messages are copied into and out of the queue. For large messages, consider using a queue of pointers or references instead.

§Examples

ⓘ
use osal_rs::os::Queue;
 
// Create queue: 10 slots, 32 bytes per message
let queue = Queue::new(10, 32).unwrap();
 
// Producer sends data
let data = [1, 2, 3, 4];
queue.post(&data, 100).unwrap();
 
// Consumer receives data
let mut buffer = [0u8; 32];
queue.fetch(&mut buffer, 100).unwrap();
assert_eq!(&buffer[..4], &[1, 2, 3, 4]);

Required Methods§

Source

fn fetch(&self, buffer: &mut [u8], time: TickType) -> Result<()>

Fetches a message from the queue (blocking).

Removes and retrieves the oldest message from the queue (FIFO order). Blocks the calling task if the queue is empty.

§Parameters
  • buffer - Buffer to receive the message data (should match queue message size)
  • time - Maximum ticks to wait for a message:
    • 0: Return immediately if empty
    • n: Wait up to n ticks
    • TickType::MAX: Wait forever
§Returns
  • Ok(()) - Message received successfully
  • Err(Error::Timeout) - Queue was empty for entire timeout period
  • Err(Error) - Other error occurred
§Examples
ⓘ
let mut buffer = [0u8; 16];
 
// Wait up to 1000 ticks
match queue.fetch(&mut buffer, 1000) {
    Ok(()) => println!("Received: {:?}", buffer),
    Err(_) => println!("Timeout - no message available"),
}
Source

fn fetch_from_isr(&self, buffer: &mut [u8]) -> Result<()>

Fetches a message from ISR context (non-blocking).

ISR-safe version of fetch(). Returns immediately without blocking. Must only be called from interrupt context.

§Parameters
  • buffer - Buffer to receive the message data
§Returns
  • Ok(()) - Message received successfully
  • Err(Error) - Queue is empty
§Examples
ⓘ
// In interrupt handler
let mut buffer = [0u8; 16];
if queue.fetch_from_isr(&mut buffer).is_ok() {
    // Process message quickly
}
Source

fn post(&self, item: &[u8], time: TickType) -> Result<()>

Posts a message to the queue (blocking).

Adds a new message to the end of the queue (FIFO order). Blocks the calling task if the queue is full.

§Parameters
  • item - The message data to send (must not exceed queue message size)
  • time - Maximum ticks to wait if queue is full:
    • 0: Return immediately if full
    • n: Wait up to n ticks for space
    • TickType::MAX: Wait forever
§Returns
  • Ok(()) - Message sent successfully
  • Err(Error::Timeout) - Queue was full for entire timeout period
  • Err(Error) - Other error occurred
§Examples
ⓘ
let data = [1, 2, 3, 4];
 
// Try to send, wait up to 1000 ticks if full
match queue.post(&data, 1000) {
    Ok(()) => println!("Sent successfully"),
    Err(_) => println!("Queue full, couldn't send"),
}
Source

fn post_from_isr(&self, item: &[u8]) -> Result<()>

Posts a message from ISR context (non-blocking).

ISR-safe version of post(). Returns immediately without blocking. Must only be called from interrupt context.

§Parameters
  • item - The message data to send
§Returns
  • Ok(()) - Message sent successfully
  • Err(Error) - Queue is full
§Examples
ⓘ
// In interrupt handler
let data = [0x42, 0x13];
if queue.post_from_isr(&data).is_err() {
    // Queue full, message dropped
}
Source

fn delete(&mut self)

Deletes the queue and frees its resources.

§Safety

Ensure no tasks are blocked on this queue before deletion. Calling this while tasks are waiting may cause undefined behavior.

§Examples
ⓘ
let mut queue = Queue::new(10, 16).unwrap();
// Use queue...
queue.delete();

Implementors§