|
| 1 | +//! Close-to-Zephyr channels |
| 2 | +//! |
| 3 | +//! This module attempts to provide a mechanism as close as possible to `crossbeam-channel` as we |
| 4 | +//! can get, directly using Zephyr primitives. |
| 5 | +//! |
| 6 | +//! The channels are built around `k_queue` in Zephyr. As is the case with most Zephyr types, |
| 7 | +//! these are typically statically allocated. Similar to the other close-to-zephyr primitives, |
| 8 | +//! this means that there is a constructor that can directly take one of these primitives. |
| 9 | +//! |
| 10 | +//! In other words, `zephyr::sys::Queue` is a Rust friendly implementation of `k_queue` in Zephyr. |
| 11 | +//! This module provides `Sender` and `Receiver`, which can be cloned and behave as if they had an |
| 12 | +//! internal `Arc` inside them, but without the overhead of an actual Arc. |
| 13 | +
|
| 14 | +extern crate alloc; |
| 15 | + |
| 16 | +use alloc::boxed::Box; |
| 17 | + |
| 18 | +use core::ffi::c_void; |
| 19 | +use core::fmt; |
| 20 | +use core::marker::PhantomData; |
| 21 | + |
| 22 | +use crate::sys::queue::Queue; |
| 23 | + |
| 24 | +mod counter; |
| 25 | + |
| 26 | +// The zephyr queue does not allocate or manage the data of the messages, so we need to handle |
| 27 | +// allocation as such as well. However, we don't need to manage anything, so it is sufficient to |
| 28 | +// simply Box the message, leak it out of the box, and give it to Zephyr, and then on receipt, wrap |
| 29 | +// it back into a Box, and give it to the recipient. |
| 30 | + |
| 31 | +/// Create a multi-producer multi-consumer channel of unbounded capacity. The messages are |
| 32 | +/// allocated individually as "Box", and the queue is managed by the underlying Zephyr queue. |
| 33 | +pub fn unbounded_from<T>(queue: Queue) -> (Sender<T>, Receiver<T>) { |
| 34 | + let (s, r) = counter::new(queue); |
| 35 | + let s = Sender { |
| 36 | + queue: s, |
| 37 | + _phantom: PhantomData, |
| 38 | + }; |
| 39 | + let r = Receiver { |
| 40 | + queue: r, |
| 41 | + _phantom: PhantomData, |
| 42 | + }; |
| 43 | + (s, r) |
| 44 | +} |
| 45 | + |
| 46 | +/// The underlying type for Messages through Zephyr's [`Queue`]. |
| 47 | +/// |
| 48 | +/// This wrapper is used internally to wrap user messages through the queue. It is not useful in |
| 49 | +/// safe code, but may be useful for implementing other types of message queues. |
| 50 | +#[repr(C)] |
| 51 | +pub struct Message<T> { |
| 52 | + /// The private data used by the kernel to enqueue messages and such. |
| 53 | + _private: usize, |
| 54 | + /// The actual data being transported. |
| 55 | + data: T, |
| 56 | +} |
| 57 | + |
| 58 | +impl<T> Message<T> { |
| 59 | + fn new(data: T) -> Message<T> { |
| 60 | + Message { |
| 61 | + _private: 0, |
| 62 | + data, |
| 63 | + } |
| 64 | + } |
| 65 | +} |
| 66 | + |
| 67 | +/// The sending side of a channel. |
| 68 | +pub struct Sender<T> { |
| 69 | + queue: counter::Sender<Queue>, |
| 70 | + _phantom: PhantomData<T>, |
| 71 | +} |
| 72 | + |
| 73 | +unsafe impl<T: Send> Send for Sender<T> {} |
| 74 | +unsafe impl<T: Send> Sync for Sender<T> {} |
| 75 | + |
| 76 | +impl<T> Sender<T> { |
| 77 | + /// Sends a message over the given channel. This will perform an alloc of the message, which |
| 78 | + /// will have an accompanied free on the recipient side. |
| 79 | + pub fn send(&self, msg: T) -> Result<(), SendError<T>> { |
| 80 | + let msg = Box::new(Message::new(msg)); |
| 81 | + let msg = Box::into_raw(msg); |
| 82 | + unsafe { |
| 83 | + self.queue.send(msg as *mut c_void); |
| 84 | + } |
| 85 | + Ok(()) |
| 86 | + } |
| 87 | +} |
| 88 | + |
| 89 | +impl<T> Drop for Sender<T> { |
| 90 | + fn drop(&mut self) { |
| 91 | + unsafe { |
| 92 | + self.queue.release(|_| { |
| 93 | + crate::printkln!("Release"); |
| 94 | + true |
| 95 | + }) |
| 96 | + } |
| 97 | + } |
| 98 | +} |
| 99 | + |
| 100 | +impl<T> Clone for Sender<T> { |
| 101 | + fn clone(&self) -> Self { |
| 102 | + Sender { |
| 103 | + queue: self.queue.acquire(), |
| 104 | + _phantom: PhantomData, |
| 105 | + } |
| 106 | + } |
| 107 | +} |
| 108 | + |
| 109 | +impl<T: fmt::Debug> fmt::Debug for Sender<T> { |
| 110 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 111 | + write!(f, "Sender {:?}", *self.queue) |
| 112 | + } |
| 113 | +} |
| 114 | + |
| 115 | +/// The receiving side of a channel. |
| 116 | +pub struct Receiver<T> { |
| 117 | + queue: counter::Receiver<Queue>, |
| 118 | + _phantom: PhantomData<T>, |
| 119 | +} |
| 120 | + |
| 121 | +unsafe impl<T: Send> Send for Receiver<T> {} |
| 122 | +unsafe impl<T: Send> Sync for Receiver<T> {} |
| 123 | + |
| 124 | +impl<T> Receiver<T> { |
| 125 | + /// Blocks the current thread until a message is received or the channel is empty and |
| 126 | + /// disconnected. |
| 127 | + /// |
| 128 | + /// If the channel is empty and not disconnected, this call will block until the receive |
| 129 | + /// operation can proceed. If the channel is empty and becomes disconnected, this call will |
| 130 | + /// wake up and return an error. |
| 131 | + pub fn recv(&self) -> Result<T, RecvError> { |
| 132 | + let msg = unsafe { |
| 133 | + self.queue.recv() |
| 134 | + }; |
| 135 | + let msg = msg as *mut Message<T>; |
| 136 | + let msg = unsafe { Box::from_raw(msg) }; |
| 137 | + Ok(msg.data) |
| 138 | + } |
| 139 | +} |
| 140 | + |
| 141 | +impl<T> Drop for Receiver<T> { |
| 142 | + fn drop(&mut self) { |
| 143 | + unsafe { |
| 144 | + self.queue.release(|_| { |
| 145 | + crate::printkln!("Release"); |
| 146 | + true |
| 147 | + }) |
| 148 | + } |
| 149 | + } |
| 150 | +} |
| 151 | + |
| 152 | +impl<T> Clone for Receiver<T> { |
| 153 | + fn clone(&self) -> Self { |
| 154 | + Receiver { |
| 155 | + queue: self.queue.acquire(), |
| 156 | + _phantom: PhantomData, |
| 157 | + } |
| 158 | + } |
| 159 | +} |
| 160 | + |
| 161 | +impl<T> fmt::Debug for Receiver<T> { |
| 162 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 163 | + write!(f, "Sender {:?}", *self.queue) |
| 164 | + } |
| 165 | +} |
| 166 | + |
| 167 | +// TODO: Move to err |
| 168 | + |
| 169 | +/// An error returned from the [`send`] method. |
| 170 | +/// |
| 171 | +/// The message could not be sent because the channel is disconnected. |
| 172 | +/// |
| 173 | +/// The error contains the message so it can be recovered. |
| 174 | +/// |
| 175 | +/// [`send`]: Sender::send |
| 176 | +#[derive(PartialEq, Eq, Clone, Copy)] |
| 177 | +pub struct SendError<T>(pub T); |
| 178 | + |
| 179 | +impl<T> fmt::Debug for SendError<T> { |
| 180 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 181 | + "SendError(..)".fmt(f) |
| 182 | + } |
| 183 | +} |
| 184 | + |
| 185 | +/// An error returned from the [`recv`] method. |
| 186 | +/// |
| 187 | +/// A message could not be received because the channel is empty and disconnected. |
| 188 | +/// |
| 189 | +/// [`recv`]: Receiver::recv |
| 190 | +#[derive(PartialEq, Eq, Clone, Copy, Debug)] |
| 191 | +pub struct RecvError; |
0 commit comments