Struct Thread 

pub struct Thread { /* private fields */ }

Thread/task management and notification types. A FreeRTOS task/thread wrapper.

Provides a safe Rust interface for creating and managing FreeRTOS tasks. Threads can be created with closures or function pointers and support various synchronization primitives.

Examples

Creating a simple thread

use osal_rs::os::{Thread, ThreadPriority};
use core::time::Duration;
 
let thread = Thread::new(
    "worker",
    2048,  // stack size in words
    ThreadPriority::Normal,
    || {
        loop {
            println!("Working...");
            Duration::from_secs(1).sleep();
        }
    }
).unwrap();
 
thread.start().unwrap();

Using thread notifications

use osal_rs::os::{Thread, ThreadNotification};
use core::time::Duration;
 
let thread = Thread::new("notified", 2048, 5, || {
    loop {
        if let Some(value) = Thread::current().wait_notification(Duration::from_secs(1)) {
            println!("Received notification: {}", value);
        }
    }
}).unwrap();
 
thread.start().unwrap();
thread.notify(42).unwrap();  // Send notification

Implementations

impl Thread

pub fn new(name: &str, stack_depth: StackType, priority: UBaseType) -> Self

Creates a new uninitialized thread.

The thread must be started with spawn() or spawn_simple().

Examples

use osal_rs::os::{Thread, ThreadFn};
 
let thread = Thread::new("worker", 4096, 5);

pub fn new_with_handle( handle: ThreadHandle, name: &str, stack_depth: StackType, priority: UBaseType, ) -> Result<Self>

Creates a thread from an existing task handle.

Returns

• Err(Error::NullPtr) if handle is null

pub fn new_with_to_priority( name: &str, stack_depth: StackType, priority: impl ToPriority, ) -> Self

Creates a new thread with a priority that implements ToPriority.

This is a convenience constructor that allows using various priority types.

Parameters

• name - Thread name for debugging
• stack_depth - Stack size in words (not bytes)
• priority - Thread priority (any type implementing ToPriority)

Examples

use osal_rs::os::Thread;
 
let thread = Thread::new_with_to_priority("worker", 2048, 5);

pub fn new_with_handle_and_to_priority( handle: ThreadHandle, name: &str, stack_depth: StackType, priority: impl ToPriority, ) -> Result<Self>

Creates a thread from an existing FreeRTOS task handle.

Parameters

• handle - Valid FreeRTOS task handle
• name - Thread name
• stack_depth - Stack size
• priority - Thread priority

Returns

• Err(Error::NullPtr) if handle is null

Examples

use osal_rs::os::Thread;
 
// Get current task handle from FreeRTOS
let handle = get_task_handle();
let thread = Thread::new_with_handle_and_to_priority(handle, "existing", 2048, 5).unwrap();

pub fn get_metadata_from_handle(handle: ThreadHandle) -> ThreadMetadata

Retrieves metadata for a thread from its handle.

Parameters

• handle - FreeRTOS task handle

Returns

Thread metadata including state, priority, stack usage, etc.

Examples

use osal_rs::os::Thread;
 
let handle = get_some_task_handle();
let metadata = Thread::get_metadata_from_handle(handle);
println!("Thread '{}' state: {:?}", metadata.name, metadata.state);

pub fn get_metadata(thread: &Thread) -> ThreadMetadata

Retrieves metadata for a thread object.

Parameters

• thread - Thread reference

Returns

Thread metadata or default if handle is null

Examples

use osal_rs::os::Thread;
 
let thread = Thread::new("worker", 2048, 5);
let metadata = Thread::get_metadata(&thread);
println!("Stack high water mark: {}", metadata.stack_high_water_mark);

pub fn wait_notification_with_to_tick( &self, bits_to_clear_on_entry: u32, bits_to_clear_on_exit: u32, timeout_ticks: impl ToTick, ) -> Result<u32>

Waits for a thread notification with a timeout that implements ToTick.

Convenience method that accepts Duration or other tick-convertible types.

Parameters

• bits_to_clear_on_entry - Bits to clear before waiting
• bits_to_clear_on_exit - Bits to clear after receiving notification
• timeout_ticks - Maximum time to wait (convertible to ticks)

Returns

• Ok(u32) - Notification value received
• Err(Error::NullPtr) - Thread handle is null
• Err(Error::Timeout) - No notification received within timeout

Examples

use osal_rs::os::{Thread, ThreadFn};
use core::time::Duration;
 
let thread = Thread::current();
match thread.wait_notification_with_to_tick(0, 0xFF, Duration::from_secs(1)) {
    Ok(value) => println!("Received: {}", value),
    Err(_) => println!("Timeout"),
}

Trait Implementations

impl Clone for Thread

fn clone(&self) -> Thread

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Thread

Formats the thread for debugging purposes.

Includes handle, name, stack depth, priority, and callback status.

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

Formats the value using the given formatter.

impl Deref for Thread

Allows dereferencing to the underlying FreeRTOS thread handle.

This enables direct access to the handle when needed for low-level operations.

type Target = *const c_void

The resulting type after dereferencing.

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

Dereferences the value.

impl Display for Thread

Formats the thread for display purposes.

Shows a concise representation with handle, name, priority, and stack depth.

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

Formats the value using the given formatter.

impl Thread for Thread

fn spawn<F>(&mut self, param: Option<ThreadParam>, callback: F) -> Result<Self>

where F: Fn(Box<dyn ThreadFn>, Option<ThreadParam>) -> Result<ThreadParam> + Send + Sync + 'static,

Spawns a new thread with a callback.

Important

The callback must be 'static, which means it cannot borrow local variables. Use move in the closure to transfer ownership of any captured values:

let data = Arc::new(Mutex::new(0));
let thread = Thread::new("my_thread", 4096, 3, move |_thread, _param| {
    // Use 'move' to capture 'data' by value
    let mut guard = data.lock().unwrap();
    *guard += 1;
    Ok(Arc::new(()))
});
``

fn spawn_simple<F>(&mut self, callback: F) -> Result<Self>

where F: Fn() + Send + Sync + 'static,

Spawns a new thread with a simple closure, similar to std::thread::spawn. This is the recommended way to create threads for most use cases.

Example

let counter = Arc::new(Mutex::new(0));
let counter_clone = Arc::clone(&counter);
 
let handle = Thread::spawn_simple("worker", 4096, 3, move || {
    let mut num = counter_clone.lock().unwrap();
    *num += 1;
}).unwrap();
 
handle.join(core::ptr::null_mut());

fn delete(&self)

Deletes the thread and frees its resources.

Safety

After calling this, the thread handle becomes invalid.

Examples

use osal_rs::os::{Thread, ThreadFn};
 
let thread = Thread::new("temp", 2048, 5);
thread.delete();

fn suspend(&self)

Suspends the thread execution.

The thread remains suspended until resume() is called.

Examples

use osal_rs::os::{Thread, ThreadFn};
use core::time::Duration;
 
let thread = get_some_thread();
thread.suspend();
Duration::from_secs(1).sleep();
thread.resume();

fn resume(&self)

Resumes a previously suspended thread.

Examples

thread.resume();

fn join(&self, _retval: DoublePtr) -> Result<i32>

Waits for the thread to complete (currently deletes the thread).

Returns

Always returns Ok(0)

fn get_metadata(&self) -> ThreadMetadata

Retrieves this thread’s metadata.

Examples

use osal_rs::os::{Thread, ThreadFn};
 
let thread = Thread::current();
let meta = thread.get_metadata();
println!("Running thread: {}", meta.name);

fn get_current() -> Self

Returns a Thread object representing the currently executing thread.

Examples

use osal_rs::os::{Thread, ThreadFn};
 
let current = Thread::get_current();
println!("Current thread: {}", current.get_metadata().name);

fn notify(&self, notification: ThreadNotification) -> Result<()>

Sends a notification to this thread.

Parameters

• notification - Type of notification action to perform

Returns

• Ok(()) - Notification sent successfully
• Err(Error::NullPtr) - Thread handle is null
• Err(Error::QueueFull) - Notification failed

Examples

use osal_rs::os::{Thread, ThreadFn, ThreadNotification};
 
let thread = get_worker_thread();
thread.notify(ThreadNotification::SetValueWithOverwrite(42)).unwrap();

fn notify_from_isr( &self, notification: ThreadNotification, higher_priority_task_woken: &mut BaseType, ) -> Result<()>

Sends a notification to this thread from an ISR.

Parameters

• notification - Type of notification action
• higher_priority_task_woken - Set to pdTRUE if a higher priority task was woken

Returns

• Ok(()) - Notification sent successfully
• Err(Error::NullPtr) - Thread handle is null
• Err(Error::QueueFull) - Notification failed

Examples

// In ISR context:
let mut woken = pdFALSE;
thread.notify_from_isr(ThreadNotification::Increment, &mut woken).ok();

fn wait_notification( &self, bits_to_clear_on_entry: u32, bits_to_clear_on_exit: u32, timeout_ticks: TickType, ) -> Result<u32>

Waits for a thread notification.

Parameters

• bits_to_clear_on_entry - Bits to clear in notification value before waiting
• bits_to_clear_on_exit - Bits to clear after receiving notification
• timeout_ticks - Maximum ticks to wait

Returns

• Ok(u32) - Notification value received
• Err(Error::NullPtr) - Thread handle is null
• Err(Error::Timeout) - No notification within timeout

Examples

use osal_rs::os::{Thread, ThreadFn};
 
let thread = Thread::current();
match thread.wait_notification(0, 0xFFFFFFFF, 1000) {
    Ok(value) => println!("Received notification: {}", value),
    Err(_) => println!("Timeout waiting for notification"),
}

impl Send for Thread

impl Sync for Thread