Conversion from/to raw handle

freertos-rust/src/isr.rs

@@ -17,7 +17,7 @@ impl InterruptContext {
         }
     }
 
-    pub unsafe fn get_task_field_mut(&self) -> FreeRtosBaseTypeMutPtr {
+    pub fn get_task_field_mut(&self) -> FreeRtosBaseTypeMutPtr {
         self.x_higher_priority_task_woken as *mut _
     }
 }

freertos-rust/src/mutex.rs

@@ -26,30 +26,15 @@ where
     }
 }
 
-impl<T> MutexImpl<T, MutexNormal> {
-    /// Create a new mutex with the given inner value
-    pub fn new(t: T) -> Result<Self, FreeRtosError> {
-        Ok(MutexImpl {
-            mutex: MutexNormal::create()?,
-            data: UnsafeCell::new(t),
-        })
-    }
-}
-
-impl<T> MutexImpl<T, MutexRecursive> {
-    /// Create a new recursive mutex with the given inner value
-    pub fn new(t: T) -> Result<Self, FreeRtosError> {
-        Ok(MutexImpl {
-            mutex: MutexRecursive::create()?,
-            data: UnsafeCell::new(t),
-        })
-    }
-}
-
 impl<T, M> MutexImpl<T, M>
 where
     M: MutexInnerImpl,
 {
+    /// Create a new mutex with the given inner value
+    pub fn new(value: T) -> Result<Self, FreeRtosError> {
+        Ok(Self::from_parts(M::create()?, value))
+    }
+
     /// Try to obtain a lock and mutable access to our inner value
     pub fn lock<D: DurationTicks>(&self, max_wait: D) -> Result<MutexGuard<T, M>, FreeRtosError> {
         self.mutex.take(max_wait)?;
@@ -62,23 +47,35 @@ where
 
     /// Consume the mutex and return its inner value
     pub fn into_inner(self) -> T {
-        // Manually deconstruct the structure, because it implements Drop
-        // and we cannot move the data value out of it.
-        unsafe {
-            let (mutex, data) = {
-                let Self {
-                    ref mutex,
-                    ref data,
-                } = self;
-                (ptr::read(mutex), ptr::read(data))
-            };
-            mem::forget(self);
-
-            drop(mutex);
-
-            data.into_inner()
+        self.into_parts().1
+    }
+
+    /// Get mutable reference to inner value.
+    ///
+    /// This method does not lock the mutex because mutable reference guarantees exclusive access.
+    pub fn get_mut(&mut self) -> &mut T {
+        self.data.get_mut()
+    }
+
+    /// Create owning mutex from non-owning mutex and inner value.
+    ///
+    /// It is safe to pass an already locked `mutex` although it is not recommended.
+    pub fn from_parts(mutex: M, value: T) -> Self {
+        Self {
+            mutex,
+            data: UnsafeCell::new(value),
         }
     }
+
+    /// Split owning mutex into non-owning mutex and inner value.
+    pub fn into_parts(self) -> (M, T) {
+        (self.mutex, self.data.into_inner())
+    }
+
+    /// Get mutable reference to inner non-owning mutex.
+    pub fn inner_mutex_mut(&mut self) -> &mut M {
+        &mut self.mutex
+    }
 }
 
 /// Holds the mutex until we are dropped
@@ -126,6 +123,15 @@ where
     fn create() -> Result<Self, FreeRtosError>;
     fn take<D: DurationTicks>(&self, max_wait: D) -> Result<(), FreeRtosError>;
     fn give(&self);
+
+    /// # Safety
+    ///
+    /// `handle` must be a valid FreeRTOS mutex handle.
+    ///
+    /// The type of `handle` (normal or recursive mutex) must match the type
+    /// of instance being created ([`MutexNormal`] or [`MutexRecursive`] respectively).
+    unsafe fn from_raw_handle(handle: FreeRtosSemaphoreHandle) -> Self;
+    fn raw_handle(&self) -> FreeRtosSemaphoreHandle;
 }
 
 pub struct MutexNormal(FreeRtosSemaphoreHandle);
@@ -154,6 +160,16 @@ impl MutexInnerImpl for MutexNormal {
             freertos_rs_give_semaphore(self.0);
         }
     }
+
+    #[inline]
+    unsafe fn from_raw_handle(handle: FreeRtosSemaphoreHandle) -> Self {
+        Self(handle)
+    }
+
+    #[inline]
+    fn raw_handle(&self) -> FreeRtosSemaphoreHandle {
+        self.0
+    }
 }
 
 impl Drop for MutexNormal {
@@ -194,6 +210,16 @@ impl MutexInnerImpl for MutexRecursive {
             freertos_rs_give_recursive_semaphore(self.0);
         }
     }
+
+    #[inline]
+    unsafe fn from_raw_handle(handle: FreeRtosSemaphoreHandle) -> Self {
+        Self(handle)
+    }
+
+    #[inline]
+    fn raw_handle(&self) -> FreeRtosSemaphoreHandle {
+        self.0
+    }
 }
 
 impl Drop for MutexRecursive {

freertos-rust/src/queue.rs

@@ -31,13 +31,22 @@ impl<T: Sized + Copy> Queue<T> {
         })
     }
 
+    /// # Safety
+    ///
+    /// `handle` must be a valid FreeRTOS regular queue handle (not semaphore or mutex).
+    ///
+    /// The item size of the queue must match the size of `T`.
     #[inline]
     pub unsafe fn from_raw_handle(handle: FreeRtosQueueHandle) -> Self {
         Self {
             queue: handle,
             item_type: PhantomData,
         }
     }
+    #[inline]
+    pub fn raw_handle(&self) -> FreeRtosQueueHandle {
+        self.queue
+    }
 
     /// Send an item to the end of the queue. Wait for the queue to have empty space for it.
     pub fn send<D: DurationTicks>(&self, item: T, max_wait: D) -> Result<(), FreeRtosError> {

freertos-rust/src/semaphore.rs

@@ -34,10 +34,20 @@ impl Semaphore {
         }
     }
 
+    /// # Safety
+    ///
+    /// `handle` must be a valid FreeRTOS semaphore handle.
+    ///
+    /// Only binary or counting semaphore is expected here.
+    /// To create mutex from raw handle use [`crate::mutex::MutexInnerImpl::from_raw_handle`].
     #[inline]
     pub unsafe fn from_raw_handle(handle: FreeRtosSemaphoreHandle) -> Self {
         Self { semaphore: handle }
     }
+    #[inline]
+    pub fn raw_handle(&self) -> FreeRtosSemaphoreHandle {
+        self.semaphore
+    }
 
     /// Lock this semaphore in a RAII fashion
     pub fn lock<D: DurationTicks>(&self, max_wait: D) -> Result<SemaphoreGuard, FreeRtosError> {

freertos-rust/src/task.rs

@@ -105,10 +105,17 @@ impl Task {
         }
     }
 
+    /// # Safety
+    ///
+    /// `handle` must be a valid FreeRTOS task handle.
     #[inline]
     pub unsafe fn from_raw_handle(handle: FreeRtosTaskHandle) -> Self {
         Self { task_handle: handle }
     }
+    #[inline]
+    pub fn raw_handle(&self) -> FreeRtosTaskHandle {
+        self.task_handle
+    }
 
     pub fn suspend_all() {
       unsafe {

freertos-rust/src/timers.rs

@@ -14,7 +14,6 @@ unsafe impl Sync for Timer {}
 /// for that queue to get unblocked.
 pub struct Timer {
     handle: FreeRtosTimerHandle,
-    detached: bool,
 }
 
 /// Helper builder for a new software timer.
@@ -71,8 +70,17 @@ impl Timer {
     }
 
     /// Create a timer from a raw handle.
+    ///
+    /// # Safety
+    ///
+    /// `handle` must be a valid FreeRTOS timer handle.
+    #[inline]
     pub unsafe fn from_raw_handle(handle: FreeRtosTimerHandle) -> Self {
-        Self { handle, detached: false }
+        Self { handle }
+    }
+    #[inline]
+    pub fn raw_handle(&self) -> FreeRtosTimerHandle {
+        self.handle
     }
 
     unsafe fn spawn_inner<'a>(
@@ -109,10 +117,7 @@ impl Timer {
         extern "C" fn timer_callback(handle: FreeRtosTimerHandle) -> () {
             unsafe {
                 {
-                    let timer = Timer {
-                        handle: handle,
-                        detached: true,
-                    };
+                    let timer = Timer { handle };
                     if let Ok(callback_ptr) = timer.get_id() {
                         let b = Box::from_raw(callback_ptr as *mut Box<dyn Fn(Timer)>);
                         b(timer);
@@ -124,7 +129,6 @@ impl Timer {
 
         Ok(Timer {
             handle: timer_handle as *const _,
-            detached: false,
         })
     }
 
@@ -198,8 +202,10 @@ impl Timer {
     /// will consume the memory.
     ///
     /// Can be used for timers that will never be changed and don't need to stay in scope.
-    pub unsafe fn detach(mut self) {
-        self.detached = true;
+    ///
+    /// This method is safe because resource leak is safe in Rust.
+    pub fn detach(self) {
+        mem::forget(self);
     }
 
     fn get_id(&self) -> Result<FreeRtosVoidPtr, FreeRtosError> {
@@ -210,10 +216,6 @@ impl Timer {
 impl Drop for Timer {
     #[allow(unused_must_use)]
     fn drop(&mut self) {
-        if self.detached == true {
-            return;
-        }
-
         unsafe {
             if let Ok(callback_ptr) = self.get_id() {
                 // free the memory

freertos-rust/src/utils.rs

@@ -50,6 +50,9 @@ pub fn shim_sanity_check() -> Result<(), TypeSizeError> {
     Ok(())
 }
 
+/// # Safety
+///
+/// `str` must be a pointer to the beginning of nul-terminated sequence of bytes.
 #[cfg(any(feature = "time", feature = "hooks", feature = "sync"))]
 pub unsafe fn str_from_c_string(str: *const u8) -> Result<String, FreeRtosError> {
     let mut buf = Vec::new();