Implement std::thread-like wrappers around Furi Thread APIs

Author: str4d

crates/flipperzero/Cargo.toml

@@ -35,3 +35,7 @@ alloc = []
 [[example]]
 name = "dialog"
 required-features = ["alloc"]
+
+[[example]]
+name = "threads"
+required-features = ["alloc"]

crates/flipperzero/examples/threads.rs

@@ -0,0 +1,65 @@
+//! Demonstrates use of threads on the Flipper Zero.
+
+#![no_main]
+#![no_std]
+
+// Required for panic handler
+extern crate flipperzero_rt;
+
+// Required for allocator
+extern crate flipperzero_alloc;
+
+extern crate alloc;
+
+use alloc::borrow::ToOwned;
+use core::time::Duration;
+
+use flipperzero::{furi::thread, println};
+use flipperzero_rt::{entry, manifest};
+
+// Define the FAP Manifest for this application
+manifest!(name = "Threads example");
+
+// Define the entry function
+entry!(main);
+
+// Entry point
+fn main(_args: *mut u8) -> i32 {
+    println!("Main app started!");
+
+    let first = thread::spawn(|| {
+        println!("First thread started!");
+        thread::sleep(Duration::from_secs(5));
+        println!("First thread finished!");
+        0
+    });
+
+    thread::sleep(Duration::from_secs(1));
+
+    let second = thread::Builder::new()
+        .name("Flipper".to_owned())
+        .expect("name is valid")
+        .spawn(|| {
+            println!("Second thread started!");
+            thread::sleep(Duration::from_secs(2));
+            println!("Second thread finished!");
+            0
+        });
+
+    for (i, thread) in [&thread::current(), first.thread(), second.thread()]
+        .into_iter()
+        .enumerate()
+    {
+        if let Some(name) = thread.name() {
+            println!("Running thread {} ({})", i, name);
+        } else {
+            println!("Running unnamed thread {}", i);
+        }
+    }
+
+    first.join();
+    second.join();
+
+    println!("Main app finished!");
+    0
+}

crates/flipperzero/src/furi/thread.rs

@@ -1,7 +1,130 @@
 //! Furi Thread API.
 
+use core::{
+    ffi::{c_void, CStr},
+    fmt, str,
+};
+
+#[cfg(feature = "alloc")]
+use alloc::{
+    boxed::Box,
+    ffi::{CString, NulError},
+    string::String,
+};
+
 use flipperzero_sys as sys;
 
+const MIN_STACK_SIZE: usize = 1024;
+
+/// Thread factory, which can be used in order to configure the properties of a new thread.
+#[cfg(feature = "alloc")]
+pub struct Builder {
+    /// Guaranteed to be UTF-8.
+    name: Option<CString>,
+    stack_size: Option<usize>,
+}
+
+#[cfg(feature = "alloc")]
+impl Builder {
+    /// Generates the base configuration for spawning a thread, from which configuration
+    /// methods can be chained.
+    pub fn new() -> Self {
+        Self {
+            name: None,
+            stack_size: None,
+        }
+    }
+
+    /// Names the thread-to-be.
+    ///
+    /// Returns an error if the name contains null bytes (`\0`).
+    pub fn name(mut self, name: String) -> Result<Self, NulError> {
+        CString::new(name).map(|name| {
+            self.name = Some(name);
+            self
+        })
+    }
+
+    /// Sets the size of the stack (in bytes) for the new thread.
+    pub fn stack_size(mut self, size: usize) -> Self {
+        self.stack_size = Some(size);
+        self
+    }
+
+    /// Spawns a new thread by taking ownership of the `Builder`, and returns its
+    /// [`JoinHandle`].
+    pub fn spawn<F>(self, f: F) -> JoinHandle
+    where
+        F: FnOnce() -> i32,
+        F: Send + 'static,
+    {
+        let Builder { name, stack_size } = self;
+        let thread = Thread::new(name, stack_size);
+
+        // We need to box twice because trait objects are fat pointers, so we need the
+        // second box to obtain a thin pointer to use as the context.
+        type ThreadBody = Box<dyn FnOnce() -> i32>;
+        let thread_body: Box<ThreadBody> = Box::new(Box::new(f));
+        unsafe extern "C" fn run_thread_body(context: *mut c_void) -> i32 {
+            let thread_body = unsafe { Box::from_raw(context as *mut ThreadBody) };
+            thread_body()
+        }
+
+        let callback: sys::FuriThreadCallback = Some(run_thread_body);
+        let context = Box::into_raw(thread_body);
+        unsafe {
+            sys::furi_thread_set_callback(thread.thread, callback);
+            sys::furi_thread_set_context(thread.thread, context as *mut c_void);
+            sys::furi_thread_start(thread.thread);
+        }
+
+        JoinHandle(thread)
+    }
+}
+
+/// Spawns a new thread, returning a [`JoinHandle`] for it.
+///
+/// This call will create a thread using default parameters of [`Builder`]. If you want to
+/// specify the stack size or the name of the thread, use that API instead.
+#[cfg(feature = "alloc")]
+pub fn spawn<F>(f: F) -> JoinHandle
+where
+    F: FnOnce() -> i32,
+    F: Send + 'static,
+{
+    Builder::new().spawn(f)
+}
+
+/// Gets a handle to the thread that invokes it.
+#[cfg(feature = "alloc")]
+pub fn current() -> Thread {
+    use alloc::borrow::ToOwned;
+
+    let thread = unsafe { sys::furi_thread_get_current() };
+
+    let name = {
+        let name = unsafe { sys::furi_thread_get_name(sys::furi_thread_get_current_id()) };
+        (!name.is_null())
+            .then(|| {
+                // SAFETY: The Flipper Zero firmware ensures that all thread names have a
+                // null terminator.
+                unsafe { CStr::from_ptr(name) }.to_owned()
+            })
+            .and_then(|name| {
+                // Ensure that the name is valid UTF-8. This will be true for threads
+                // created via `Builder`, but may not be true for the current thread.
+                name.to_str().is_ok().then_some(name)
+            })
+    };
+
+    Thread { name, thread }
+}
+
+/// Cooperatively gives up a timeslice to the OS scheduler.
+pub fn yield_now() {
+    unsafe { sys::furi_thread_yield() };
+}
+
 /// Puts the current thread to sleep for at least the specified amount of time.
 pub fn sleep(duration: core::time::Duration) {
     unsafe {
@@ -13,3 +136,132 @@ pub fn sleep(duration: core::time::Duration) {
         }
     }
 }
+
+/// A unique identifier for a running thread.
+#[cfg(feature = "alloc")]
+pub struct ThreadId(sys::FuriThreadId);
+
+/// A handle to a thread.
+#[cfg(feature = "alloc")]
+pub struct Thread {
+    /// Guaranteed to be UTF-8.
+    name: Option<CString>,
+    thread: *mut sys::FuriThread,
+}
+
+#[cfg(feature = "alloc")]
+impl Drop for Thread {
+    fn drop(&mut self) {
+        // TODO: is this safe to do while the thread is running?
+        unsafe { sys::furi_thread_free(self.thread) };
+    }
+}
+
+#[cfg(feature = "alloc")]
+impl Thread {
+    fn new(name: Option<CString>, stack_size: Option<usize>) -> Self {
+        let stack_size = stack_size.unwrap_or(MIN_STACK_SIZE);
+
+        unsafe {
+            let thread = sys::furi_thread_alloc();
+            if let Some(name) = name.as_deref() {
+                sys::furi_thread_set_name(thread, name.as_ptr());
+            }
+            sys::furi_thread_set_stack_size(thread, stack_size);
+            Thread { name, thread }
+        }
+    }
+
+    /// Gets the thread's unique identifier.
+    ///
+    /// Returns `None` if the thread has terminated.
+    pub fn id(&self) -> Option<ThreadId> {
+        // TODO: The Rust stdlib generates its own unique IDs for threads that are valid
+        // even after a thread terminates.
+        let id = unsafe { sys::furi_thread_get_id(self.thread) };
+        if id.is_null() {
+            None
+        } else {
+            Some(ThreadId(id))
+        }
+    }
+
+    /// Gets the thread's name.
+    ///
+    /// Returns `None` if the thread has terminated, or is unnamed, or has a name that is
+    /// not valid UTF-8.
+    pub fn name(&self) -> Option<&str> {
+        self.cname()
+            .map(|s| unsafe { str::from_utf8_unchecked(s.to_bytes()) })
+    }
+
+    fn cname(&self) -> Option<&CStr> {
+        self.name.as_deref()
+    }
+}
+
+#[cfg(feature = "alloc")]
+impl fmt::Debug for Thread {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Thread")
+            .field("name", &self.name())
+            .finish_non_exhaustive()
+    }
+}
+
+#[cfg(feature = "alloc")]
+impl ufmt::uDebug for Thread {
+    fn fmt<W>(&self, f: &mut ufmt::Formatter<'_, W>) -> Result<(), W::Error>
+    where
+        W: ufmt::uWrite + ?Sized,
+    {
+        // TODO: ufmt doesn't provide an impl of uDebug for &str.
+        f.debug_struct("Thread")?.finish()
+    }
+}
+
+/// An owned permission to join on a thread (block on its termination).
+#[cfg(feature = "alloc")]
+pub struct JoinHandle(Thread);
+
+#[cfg(feature = "alloc")]
+impl JoinHandle {
+    /// Extracts a handle to the underlying thread.
+    pub fn thread(&self) -> &Thread {
+        &self.0
+    }
+
+    /// Waits for the associated thread to finish.
+    ///
+    /// This function will return immediately if the associated thread has already
+    /// finished.
+    pub fn join(self) -> i32 {
+        let JoinHandle(Thread { thread, .. }) = self;
+        unsafe {
+            sys::furi_thread_join(thread);
+            sys::furi_thread_get_return_code(thread)
+        }
+    }
+
+    /// Checks if the associated thread has finished running its main function.
+    pub fn is_finished(&self) -> bool {
+        self.0.id().is_none()
+    }
+}
+
+#[cfg(feature = "alloc")]
+impl fmt::Debug for JoinHandle {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("JoinHandle").finish_non_exhaustive()
+    }
+}
+
+#[cfg(feature = "alloc")]
+impl ufmt::uDebug for JoinHandle {
+    fn fmt<W>(&self, f: &mut ufmt::Formatter<'_, W>) -> Result<(), W::Error>
+    where
+        W: ufmt::uWrite + ?Sized,
+    {
+        f.debug_struct("JoinHandle")?.finish()
+    }
+}