osal_rs/traits/
thread.rs

1/***************************************************************************
2 *
3 * osal-rs
4 * Copyright (C) 2023/2026 Antonio Salsi <passy.linux@zresa.it>
5 *
6 * This program is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
17 *
18 ***************************************************************************/
19
20//! Thread-related traits and type definitions.
21
22use core::any::Any;
23use alloc::boxed::Box;
24use alloc::sync::Arc;
25
26use crate::os::{ThreadMetadata};
27use crate::os::types::{BaseType, TickType, UBaseType};
28use crate::utils::{Result, DoublePtr};
29
30/// Type-erased parameter that can be passed to thread callbacks.
31///
32/// Allows passing arbitrary data to thread functions in a thread-safe manner.
33/// The parameter can be downcast to its original type using `downcast_ref()`.
34pub type ThreadParam = Arc<dyn Any + Send + Sync>;
35
36/// Thread callback function pointer type.
37///
38/// Thread callbacks receive a boxed thread handle and optional parameter,
39/// and can return an updated parameter value.
40pub type ThreadFnPtr = dyn Fn(Box<dyn Thread>, Option<ThreadParam>) -> Result<ThreadParam> + Send + Sync + 'static;
41
42/// Simple thread function pointer type without parameters.
43///
44/// Used for basic thread functions that don't need access to the thread handle or parameters.
45pub type ThreadSimpleFnPtr = dyn Fn() + Send + Sync + 'static;
46
47/// Thread notification actions.
48///
49/// Defines different ways to notify a thread using the FreeRTOS task notification mechanism.
50/// Task notifications provide a lightweight alternative to semaphores and queues for
51/// simple signaling.
52///
53/// # Examples
54///
55/// ```ignore
56/// use osal_rs::os::{Thread, ThreadNotification};
57/// 
58/// let thread = Thread::current();
59/// 
60/// // Increment notification counter
61/// thread.notify_with_action(ThreadNotification::Increment);
62/// 
63/// // Set specific bits
64/// thread.notify_with_action(ThreadNotification::SetBits(0b1010));
65/// 
66/// // Set value, overwriting any existing value
67/// thread.notify_with_action(ThreadNotification::SetValueWithOverwrite(42));
68/// ```
69#[derive(Debug, Copy, Clone)]
70pub enum ThreadNotification {
71    /// Don't update the notification value
72    NoAction,
73    /// Bitwise OR the notification value with the specified bits
74    SetBits(u32),
75    /// Increment the notification value by one
76    Increment,
77    /// Set the notification value, overwriting any existing value
78    SetValueWithOverwrite(u32),
79    /// Set the notification value only if the receiving thread has no pending notifications
80    SetValueWithoutOverwrite(u32),
81}
82
83impl Into<(u32, u32)> for ThreadNotification {
84    fn into(self) -> (u32, u32) {
85        use ThreadNotification::*;
86        match self {
87            NoAction => (0, 0),
88            SetBits(bits) => (1, bits),
89            Increment => (2, 0),
90            SetValueWithOverwrite(value) => (3, value),
91            SetValueWithoutOverwrite(value) => (4, value),
92        }
93    }
94}
95
96pub trait Thread {
97    fn spawn<F>(&mut self, param: Option<ThreadParam>, callback: F) -> Result<Self>
98    where 
99        F: Fn(Box<dyn Thread>, Option<ThreadParam>) -> Result<ThreadParam>,
100        F: Send + Sync + 'static,
101        Self: Sized;
102
103    fn spawn_simple<F>(&mut self, callback: F) -> Result<Self>
104    where
105        F: Fn() + Send + Sync + 'static,
106        Self: Sized;
107
108    fn delete(&self);
109
110    fn suspend(&self);
111
112    fn resume(&self);
113
114    fn join(&self, retval: DoublePtr) -> Result<i32>;
115
116    fn get_metadata(&self) -> ThreadMetadata;
117
118    fn get_current() -> Self
119    where 
120        Self: Sized;
121
122    fn notify(&self, notification: ThreadNotification) -> Result<()>;
123
124    fn notify_from_isr(&self, notification: ThreadNotification, higher_priority_task_woken: &mut BaseType) -> Result<()>;
125
126    fn wait_notification(&self, bits_to_clear_on_entry: u32, bits_to_clear_on_exit: u32 , timeout_ticks: TickType) -> Result<u32>; //no ToTick here to maintain dynamic dispatch
127
128
129}
130
131pub trait ToPriority {
132    fn to_priority(&self) -> UBaseType;
133}
osal_rs/traits/thread.rs

osal_rs/traits/
thread.rs
