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, StackType, TickType, UBaseType};
28use crate::utils::{Result, ConstPtr, 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 new(name: &str, stack_depth: StackType, priority: UBaseType) -> Self 
98    where
99        Self: Sized;
100
101    fn new_with_handle(handle: ConstPtr, name: &str, stack_depth: StackType, priority: UBaseType) -> Result<Self>  
102    where 
103        Self: Sized;
104
105    fn spawn<F>(&mut self, param: Option<ThreadParam>, callback: F) -> Result<Self>
106    where 
107        F: Fn(Box<dyn Thread>, Option<ThreadParam>) -> Result<ThreadParam>,
108        F: Send + Sync + 'static,
109        Self: Sized;
110
111    fn spawn_simple<F>(&mut self, callback: F) -> Result<Self>
112    where
113        F: Fn() + Send + Sync + 'static,
114        Self: Sized;
115
116    fn delete(&self);
117
118    fn suspend(&self);
119
120    fn resume(&self);
121
122    fn join(&self, retval: DoublePtr) -> Result<i32>;
123
124    fn get_metadata(&self) -> ThreadMetadata;
125
126    fn get_current() -> Self
127    where 
128        Self: Sized;
129
130    fn notify(&self, notification: ThreadNotification) -> Result<()>;
131
132    fn notify_from_isr(&self, notification: ThreadNotification, higher_priority_task_woken: &mut BaseType) -> Result<()>;
133
134    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
135
136
137}
138
139pub trait ToPriority {
140    fn to_priority(&self) -> UBaseType;
141}
osal_rs/traits/thread.rs

osal_rs/traits/
thread.rs
