osal_rs/traits/
queue.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//! Queue traits for inter-task communication.
21//!
22//! Provides both raw byte-based queues and type-safe streamed queues
23//! for message passing between tasks.
24
25use crate::os::ToBytes;
26use crate::os::types::{UBaseType, TickType};
27use crate::utils::Result;
28
29/// Raw byte-oriented queue for inter-task message passing.
30///
31/// This trait defines a FIFO queue that works with raw byte arrays,
32/// suitable for variable-sized messages or when type safety is not required.
33///
34/// # Examples
35///
36/// ```ignore
37/// use osal_rs::os::{Queue, QueueFn};
38/// 
39/// let queue = Queue::new(10, 32).unwrap();  // 10 messages, 32 bytes each
40/// 
41/// let data = [1, 2, 3, 4];
42/// queue.post(&data, 100).unwrap();
43/// 
44/// let mut buffer = [0u8; 32];
45/// queue.fetch(&mut buffer, 100).unwrap();
46/// ```
47pub trait Queue {
48    /// Creates a new queue.
49    ///
50    /// # Parameters
51    ///
52    /// * `size` - Maximum number of messages the queue can hold
53    /// * `message_size` - Size in bytes of each message
54    ///
55    /// # Returns
56    ///
57    /// * `Ok(Self)` - Successfully created queue
58    /// * `Err(Error)` - Creation failed (insufficient memory, etc.)
59    ///
60    /// # Examples
61    ///
62    /// ```ignore
63    /// use osal_rs::os::{Queue, QueueFn};
64    /// 
65    /// // Queue for 5 messages of 16 bytes each
66    /// let queue = Queue::new(5, 16).unwrap();
67    /// ```
68    fn new (size: UBaseType, message_size: UBaseType) -> Result<Self>
69    where 
70        Self: Sized;
71
72    /// Fetches a message from the queue (blocking).
73    ///
74    /// Removes and retrieves the oldest message from the queue.
75    ///
76    /// # Parameters
77    ///
78    /// * `buffer` - Buffer to receive the message data
79    /// * `time` - Maximum ticks to wait for a message
80    ///
81    /// # Returns
82    ///
83    /// * `Ok(())` - Message received successfully
84    /// * `Err(Error)` - Timeout or other error occurred
85    ///
86    /// # Examples
87    ///
88    /// ```ignore
89    /// let mut buffer = [0u8; 16];
90    /// queue.fetch(&mut buffer, 1000).unwrap();
91    /// ```
92    fn fetch(&self, buffer: &mut [u8], time: TickType) -> Result<()>;
93
94    /// Fetches a message from ISR context (non-blocking).
95    ///
96    /// ISR-safe version of `fetch()`. Does not block.
97    ///
98    /// # Parameters
99    ///
100    /// * `buffer` - Buffer to receive the message data
101    ///
102    /// # Returns
103    ///
104    /// * `Ok(())` - Message received
105    /// * `Err(Error)` - Queue empty or error
106    fn fetch_from_isr(&self, buffer: &mut [u8]) -> Result<()>;
107    
108    /// Posts a message to the queue (blocking).
109    ///
110    /// Adds a new message to the end of the queue.
111    ///
112    /// # Parameters
113    ///
114    /// * `item` - The message data to send
115    /// * `time` - Maximum ticks to wait if queue is full
116    ///
117    /// # Returns
118    ///
119    /// * `Ok(())` - Message sent successfully
120    /// * `Err(Error)` - Timeout or error occurred
121    ///
122    /// # Examples
123    ///
124    /// ```ignore
125    /// let data = [1, 2, 3, 4];
126    /// queue.post(&data, 1000).unwrap();
127    /// ```
128    fn post(&self, item: &[u8], time: TickType) -> Result<()>;
129    
130    /// Posts a message from ISR context (non-blocking).
131    ///
132    /// ISR-safe version of `post()`. Does not block.
133    ///
134    /// # Parameters
135    ///
136    /// * `item` - The message data to send
137    ///
138    /// # Returns
139    ///
140    /// * `Ok(())` - Message sent
141    /// * `Err(Error)` - Queue full or error
142    fn post_from_isr(&self, item: &[u8]) -> Result<()>;
143
144    /// Deletes the queue and frees its resources.
145    ///
146    /// # Safety
147    ///
148    /// Ensure no tasks are blocked on this queue before deletion.
149    fn delete(&mut self);
150}
151
152/// Type-safe queue for structured message passing.
153///
154/// This trait provides a queue that works with specific types,
155/// offering compile-time type safety for queue operations.
156///
157/// # Type Parameters
158///
159/// * `T` - The message type (must implement `ToBytes`)
160///
161/// # Examples
162///
163/// ```ignore
164/// use osal_rs::os::{QueueStreamed, QueueStreamedFn, ToBytes};
165/// 
166/// struct Message {
167///     id: u32,
168///     value: i16,
169/// }
170/// 
171/// let queue = QueueStreamed::<Message>::new(10, size_of::<Message>()).unwrap();
172/// 
173/// let msg = Message { id: 1, value: 42 };
174/// queue.post(&msg, 100).unwrap();
175/// 
176/// let mut received = Message { id: 0, value: 0 };
177/// queue.fetch(&mut received, 100).unwrap();
178/// ```
179pub trait QueueStreamed<T> 
180where 
181    T: ToBytes + Sized {
182
183    /// Creates a new type-safe queue.
184    ///
185    /// # Parameters
186    ///
187    /// * `size` - Maximum number of messages
188    /// * `message_size` - Size of each message (typically `size_of::<T>()`)
189    ///
190    /// # Returns
191    ///
192    /// * `Ok(Self)` - Successfully created queue
193    /// * `Err(Error)` - Creation failed
194    fn new (size: UBaseType, message_size: UBaseType) -> Result<Self>
195    where 
196        Self: Sized;
197
198    /// Fetches a typed message from the queue (blocking).
199    ///
200    /// # Parameters
201    ///
202    /// * `buffer` - Mutable reference to receive the message
203    /// * `time` - Maximum ticks to wait
204    ///
205    /// # Returns
206    ///
207    /// * `Ok(())` - Message received
208    /// * `Err(Error)` - Timeout or error
209    fn fetch(&self, buffer: &mut T, time: TickType) -> Result<()>;
210
211    /// Fetches a typed message from ISR context (non-blocking).
212    ///
213    /// # Parameters
214    ///
215    /// * `buffer` - Mutable reference to receive the message
216    ///
217    /// # Returns
218    ///
219    /// * `Ok(())` - Message received
220    /// * `Err(Error)` - Queue empty or error
221    fn fetch_from_isr(&self, buffer: &mut T) -> Result<()>;
222    
223    /// Posts a typed message to the queue (blocking).
224    ///
225    /// # Parameters
226    ///
227    /// * `item` - Reference to the message to send
228    /// * `time` - Maximum ticks to wait if full
229    ///
230    /// # Returns
231    ///
232    /// * `Ok(())` - Message sent
233    /// * `Err(Error)` - Timeout or error
234    fn post(&self, item: &T, time: TickType) -> Result<()>;
235
236    /// Posts a typed message from ISR context (non-blocking).
237    ///
238    /// # Parameters
239    ///
240    /// * `item` - Reference to the message to send
241    ///
242    /// # Returns
243    ///
244    /// * `Ok(())` - Message sent
245    /// * `Err(Error)` - Queue full or error
246    fn post_from_isr(&self, item: &T) -> Result<()>;
247
248    /// Deletes the queue and frees its resources.
249    ///
250    /// # Safety
251    ///
252    /// Ensure no tasks are blocked on this queue before deletion.
253    fn delete(&mut self);
254}
osal_rs/traits/queue.rs

osal_rs/traits/
queue.rs
