tokenparts, mutex: Add and use ValueInThread wrapper

This allows locking a mutex without the overhead of a check whether code
is running in thread mode.

Contributes-To: #18

Author: chrysn

src/mutex.rs

@@ -42,14 +42,10 @@ impl<T> Mutex<T> {
     /// Get an accessor to the mutex when the mutex is available
     #[doc(alias = "mutex_lock")]
     pub fn lock(&self) -> MutexGuard<T> {
-        assert!(
-            crate::interrupt::irq_is_in() == false,
-            "Mutex::lock may only be called outside of interrupt contexts.",
-        );
-        // unsafe: All preconditions of the C function are met (not-NULL through taking a &self,
-        // being initialized through RAII guarantees, thread context was checked before).
-        unsafe { riot_sys::mutex_lock(crate::inline_cast_mut(self.mutex.get())) };
-        MutexGuard { mutex: &self }
+        crate::thread::InThread::new()
+            .expect("Mutex::lock may only be called outside of interrupt contexts")
+            .promote(&self)
+            .lock()
     }
 
     /// Get an accessor to the mutex if the mutex is available
@@ -93,6 +89,20 @@ impl<T> Mutex<T> {
     }
 }
 
+impl<T> crate::thread::ValueInThread<&Mutex<T>> {
+    /// Get an accessor to the mutex when the mutex is available
+    ///
+    /// Through the [crate::thread::ValueInThread], this is already guaranteed to run in a thread
+    /// context, so no additional check is performed.
+    #[doc(alias = "mutex_lock")]
+    pub fn lock(&self) -> MutexGuard<T> {
+        // unsafe: All preconditions of the C function are met (not-NULL through taking a &self,
+        // being initialized through RAII guarantees, thread context is in the InThread).
+        unsafe { riot_sys::mutex_lock(crate::inline_cast_mut(self.mutex.get())) };
+        MutexGuard { mutex: &self }
+    }
+}
+
 unsafe impl<T: Send> Send for Mutex<T> {}
 unsafe impl<T: Send> Sync for Mutex<T> {}
 

src/thread.rs

@@ -23,7 +23,7 @@ pub use riot_c::*;
 mod tokenparts;
 #[cfg(doc)]
 pub use tokenparts::TokenParts;
-pub use tokenparts::{InIrq, InThread, StartToken, TerminationToken};
+pub use tokenparts::{InIrq, InThread, StartToken, TerminationToken, ValueInThread};
 
 mod stack_stats;
 pub use stack_stats::{StackStats, StackStatsError};

src/thread/tokenparts.rs

@@ -185,13 +185,13 @@ impl<const MQ: bool> TokenParts<true, MQ, true> {
 }
 
 /// Zero-size statement that the current code is not running in an interrupt
-#[derive(Copy, Clone)]
+#[derive(Copy, Clone, Debug)]
 pub struct InThread {
     _not_send: PhantomData<*const ()>,
 }
 
 /// Zero-size statement that the current code is running in an interrupt
-#[derive(Copy, Clone)]
+#[derive(Copy, Clone, Debug)]
 pub struct InIrq {
     _not_send: PhantomData<*const ()>,
 }
@@ -213,6 +213,15 @@ impl InThread {
             false => Ok(unsafe { InThread::new_unchecked() }),
         }
     }
+
+    /// Wrap a `value` in a [`ValueInThread`]. This makes it non-Send, but may make additional
+    /// (safe) methods on it, using the knowledge that it is still being used inside a thread.
+    pub fn promote<T>(self, value: T) -> ValueInThread<T> {
+        ValueInThread {
+            value,
+            in_thread: self,
+        }
+    }
 }
 
 impl InIrq {
@@ -230,3 +239,36 @@ impl InIrq {
         }
     }
 }
+
+/// A value combined with an [`InThread`'] marker
+///
+/// This does barely implement anything on its own, but the module implementing `T` might provide
+/// extra methods.
+pub struct ValueInThread<T> {
+    value: T,
+    in_thread: InThread,
+}
+
+impl<T> ValueInThread<T> {
+    /// Extract the wrapped value
+    ///
+    /// This does not produce the original `in_thread` value; these are easy enough to re-obtain or
+    /// to keep a copy of around.
+    pub fn into_inner(self) -> T {
+        self.value
+    }
+}
+
+impl<T> core::ops::Deref for ValueInThread<T> {
+    type Target = T;
+
+    fn deref(&self) -> &T {
+        &self.value
+    }
+}
+
+impl<T> core::ops::DerefMut for ValueInThread<T> {
+    fn deref_mut(&mut self) -> &mut T {
+        &mut self.value
+    }
+}