feat(sync): use bindings to provide a content storage for r3::sync::Mutex

> - `r3::sync::Mutex` is now backed by bindings (`Bind`). The default
>   value is now `<T as Default>::default()` instead of `<T as Init>::
>   INIT`. Additional options are available, which means you no longer
>   have to implement `Init` just to put a custom type in `Mutex`, and
>   that each `Mutex` can have a distinct initial value.

Author: yvt

examples/basic_wio_terminal/src/main.rs

@@ -698,23 +698,21 @@ mod queue {
         waiting_writer: Option<CryoRef<LocalTask<System>, AtomicLock>>,
     }
 
-    impl<System: SupportedSystem, T: Init> Init for QueueSt<System, T> {
-        const INIT: Self = Self {
-            buf: [T::INIT; CAP],
-            read_i: 0,
-            len: 0,
-            waiting_reader: None,
-            waiting_writer: None,
-        };
-    }
-
-    impl<System: SupportedSystem, T: Init + Copy + 'static> Queue<System, T> {
+    impl<System: SupportedSystem, T: Init + Copy + Send + 'static> Queue<System, T> {
         pub const fn new<C>(cfg: &mut Cfg<C>) -> Self
         where
             C: ~const traits::CfgBase<System = System> + ~const traits::CfgMutex,
         {
             Self {
-                st: StaticMutex::define().finish(cfg),
+                st: StaticMutex::define()
+                    .init(|| QueueSt {
+                        buf: [T::INIT; CAP],
+                        read_i: 0,
+                        len: 0,
+                        waiting_reader: None,
+                        waiting_writer: None,
+                    })
+                    .finish(cfg),
                 reader_lock: StaticMutex::define().finish(cfg),
                 writer_lock: StaticMutex::define().finish(cfg),
             }

src/r3/CHANGELOG.md

@@ -18,6 +18,7 @@ While much of the application-level API has retained its general shape, there ar
  - `r3::kernel::ResultCode::BadId` was renamed to `NoAccess` and covers general protection failures detected by a now-optional protection mechanism. This means that application and library code can't rely on `NoAccess` being returned reliably anymore (it can't anyway once owned handles are implemented), and that a kernel implementation may use this error code to indicate that a given kernel object ID might be valid, but the caller lacks the necessary privileges to access that object.
  - The `chrono` Cargo feature was renamed to `chrono_0p4`.
  - `r3::sync` is now gated by `cfg(feature = "sync")`.
+ - `r3::sync::Mutex` is now backed by bindings (`Bind`). The default value is now `<T as Default>::default()` instead of `<T as Init>::INIT`. Additional options are available, which means you no longer have to implement `Init` just to put a custom type in `Mutex`, and that each `Mutex` can have a distinct initial value.
 
 TODO
 

src/r3/src/lib.rs

@@ -1,4 +1,7 @@
 #![feature(arbitrary_enum_discriminant)]
+#![feature(type_changing_struct_update)]
+#![feature(const_precise_live_drops)]
+#![feature(const_fn_fn_ptr_basics)]
 #![feature(const_fn_trait_bound)]
 #![feature(const_trait_impl)]
 #![feature(const_mut_refs)]

src/r3/src/sync/mod.rs

@@ -1,4 +1,6 @@
 //! Safe synchronization primitives.
+#[macro_use]
+pub mod source;
 pub mod mutex;
 pub mod recursive_mutex;
 #[doc(no_inline)]

src/r3/src/sync/mutex.rs

@@ -2,21 +2,24 @@ use core::{
     cell::UnsafeCell,
     fmt,
     marker::PhantomData,
+    mem::MaybeUninit,
     ops::{Deref, DerefMut},
 };
 
 use crate::{
-    hunk::{DefaultInitTag, Hunk, HunkDefiner, HunkIniter},
+    hunk::Hunk,
     kernel::{
         mutex, prelude::*, traits, Cfg, LockMutexError, MarkConsistentMutexError, MutexProtocol,
         TryLockMutexError,
     },
+    sync::source::{DefaultSource, Source},
+    utils::Init,
 };
 
 /// The definer (static builder) for [`StaticMutex`][].
-pub struct Definer<System, T, InitTag> {
+pub struct Definer<System, Source> {
     mutex: mutex::MutexDefiner<System>,
-    hunk: HunkDefiner<System, UnsafeCell<T>, InitTag>,
+    source: Source,
 }
 
 /// A mutual exclusion primitive useful for protecting shared data from
@@ -73,7 +76,7 @@ pub struct GenericMutex<Cell, Mutex> {
 ///         .priority(1)
 ///         .finish(cfg);
 ///
-///     let mutex = StaticMutex::define().finish(cfg);
+///     let mutex = StaticMutex::define().init(|| 1).finish(cfg);
 ///
 ///     Objects { task2, mutex }
 /// }
@@ -85,31 +88,31 @@ pub struct GenericMutex<Cell, Mutex> {
 ///     // access `*guard` until `task1` releases the lock
 ///     COTTAGE.task2.activate().unwrap();
 ///
-///     assert_eq!(*guard, 0);
-///     *guard = 1;
+///     assert_eq!(*guard, 1);
+///     *guard = 2;
 /// }
 ///
 /// fn task2_body() {
 ///     let mut guard = COTTAGE.mutex.lock().unwrap();
-///     assert_eq!(*guard, 1);
-///     *guard = 2;
+///     assert_eq!(*guard, 2);
+///     *guard = 3;
 /// #   exit(0);
 /// }
 /// ```
 )]
 pub type StaticMutex<System, T> =
-    GenericMutex<Hunk<System, UnsafeCell<T>>, mutex::StaticMutex<System>>;
+    GenericMutex<Hunk<System, UnsafeCell<MaybeUninit<T>>>, mutex::StaticMutex<System>>;
 
 // TODO: Test the panicking behavior on invalid unlock order
 // TODO: Test the abandonment behavior
 // TODO: Owned version
 
 unsafe impl<Cell, Mutex, T: Send> Send for GenericMutex<Cell, Mutex> where
-    Cell: Deref<Target = UnsafeCell<T>>
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>
 {
 }
 unsafe impl<Cell, Mutex, T: Send> Sync for GenericMutex<Cell, Mutex> where
-    Cell: Deref<Target = UnsafeCell<T>>
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>
 {
 }
 
@@ -129,11 +132,11 @@ pub struct GenericMutexGuard<'a, Cell, Mutex: mutex::MutexHandle> {
 
 /// The specialization of [`GenericMutexGuard`] for [`StaticMutex`].
 pub type StaticMutexGuard<'a, System, T> =
-    GenericMutexGuard<'a, Hunk<System, UnsafeCell<T>>, mutex::MutexRef<'a, System>>;
+    GenericMutexGuard<'a, Hunk<System, UnsafeCell<MaybeUninit<T>>>, mutex::MutexRef<'a, System>>;
 
 unsafe impl<Cell, Mutex, T: Sync> Sync for GenericMutexGuard<'_, Cell, Mutex>
 where
-    Cell: Deref<Target = UnsafeCell<T>>,
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>,
     Mutex: mutex::MutexHandle,
 {
 }
@@ -233,17 +236,17 @@ where
 {
     /// Construct a `Definer` to define a mutex in [a configuration
     /// function](crate#static-configuration).
-    pub const fn define() -> Definer<System, T, DefaultInitTag> {
+    pub const fn define() -> Definer<System, DefaultSource<T>> {
         Definer {
             mutex: mutex::StaticMutex::define(),
-            hunk: Hunk::define(),
+            source: DefaultSource::INIT, // [ref:default_source_is_default]
         }
     }
 }
 
-impl<System, T: 'static, InitTag> Definer<System, T, InitTag>
+impl<System, Source> Definer<System, Source>
 where
-    System: traits::KernelMutex + traits::KernelStatic,
+    System: traits::KernelMutex,
 {
     /// Specify the mutex's protocol. Defaults to `None` when unspecified.
     pub const fn protocol(self, protocol: MutexProtocol) -> Self {
@@ -254,7 +257,13 @@ where
     }
 }
 
-impl<System, T: 'static, InitTag: HunkIniter<UnsafeCell<T>>> Definer<System, T, InitTag>
+// Define methods to set `Definer::source`
+impl_source_setter!(impl Definer<System, #Source>);
+
+/// # Finalization
+///
+/// The following method completes the definition of a mutex.
+impl<System, Source> Definer<System, Source>
 where
     System: traits::KernelMutex + traits::KernelStatic,
 {
@@ -263,17 +272,20 @@ where
     pub const fn finish<C: ~const traits::CfgMutex<System = System> + ~const traits::CfgBase>(
         self,
         cfg: &mut Cfg<C>,
-    ) -> StaticMutex<System, T> {
+    ) -> StaticMutex<System, Source::Target>
+    where
+        Source: ~const self::Source<System>,
+    {
         GenericMutex {
-            cell: self.hunk.finish(cfg),
+            cell: self.source.into_unsafe_cell_hunk(cfg),
             mutex: self.mutex.finish(cfg),
         }
     }
 }
 
 impl<Cell, Mutex, T> GenericMutex<Cell, Mutex>
 where
-    Cell: Deref<Target = UnsafeCell<T>>,
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>,
     Mutex: mutex::MutexHandle,
 {
     /// Acquire the mutex, blocking the current thread until it is able to do
@@ -327,13 +339,13 @@ where
     /// Get a raw pointer to the contained data.
     #[inline]
     pub fn get_ptr(&self) -> *mut T {
-        self.cell.get()
+        self.cell.get().cast()
     }
 }
 
 impl<Cell, Mutex, T: fmt::Debug> fmt::Debug for GenericMutex<Cell, Mutex>
 where
-    Cell: Deref<Target = UnsafeCell<T>>,
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>,
     Mutex: mutex::MutexHandle,
 {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
@@ -396,7 +408,7 @@ where
 
 impl<Cell, Mutex, T: fmt::Debug> fmt::Debug for GenericMutexGuard<'_, Cell, Mutex>
 where
-    Cell: Deref<Target = UnsafeCell<T>>,
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>,
     Mutex: mutex::MutexHandle,
 {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
@@ -406,7 +418,7 @@ where
 
 impl<Cell, Mutex, T: fmt::Display> fmt::Display for GenericMutexGuard<'_, Cell, Mutex>
 where
-    Cell: Deref<Target = UnsafeCell<T>>,
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>,
     Mutex: mutex::MutexHandle,
 {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
@@ -428,37 +440,47 @@ where
 
 impl<Cell, Mutex, T> Deref for GenericMutexGuard<'_, Cell, Mutex>
 where
-    Cell: Deref<Target = UnsafeCell<T>>,
+    // TODO: Currently `Cell` is always a `Hunk` given by `Source`, but in the
+    //       future, we might have other ways to provide `Cell`. For now we just
+    //       reference [ref:source_cell] when we're using its precondidtions
+    //       concerns memory safety. To support other variations of `Cell`, we
+    //       might need a better mechanism to express these preconditions than
+    //       to reference [ref:source_cell] whenever they are relevant.
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>,
     Mutex: mutex::MutexHandle,
 {
     type Target = T;
     #[inline]
     fn deref(&self) -> &Self::Target {
-        // Safety: `GenericMutexGuard` represents a permit acquired from the semaphore,
-        //         which grants the bearer an exclusive access to the underlying
-        //         data
-        unsafe { &*self.mutex.cell.get() }
+        // Safety: `GenericMutexGuard` represents a permit acquired from the
+        // semaphore, which grants the bearer an exclusive access to the
+        // underlying data. Since this `Hunk` was given by `Source`
+        // ([ref:source_cell]), we are authorized to enforce the runtime borrow
+        // rules on its contents.
+        //
+        // [ref:source_cell] says that the contents may be unavailable outside
+        // the context of an executable object. We are in the clear because
+        // `kernel::Mutex` can only be locked in a task context.
+        unsafe { (*self.mutex.cell.get()).assume_init_ref() }
     }
 }
 
 impl<Cell, Mutex, T> DerefMut for GenericMutexGuard<'_, Cell, Mutex>
 where
-    Cell: Deref<Target = UnsafeCell<T>>,
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>,
     Mutex: mutex::MutexHandle,
 {
     #[inline]
     fn deref_mut(&mut self) -> &mut Self::Target {
-        // Safety: `GenericMutexGuard` represents a permit acquired from the semaphore,
-        //         which grants the bearer an exclusive access to the underlying
-        //         data
-        unsafe { &mut *self.mutex.cell.get() }
+        // Safety: See the `deref` above.
+        unsafe { (*self.mutex.cell.get()).assume_init_mut() }
     }
 }
 
 // Safety: `MutexGuard::deref` provides a stable address
 unsafe impl<Cell, Mutex, T> stable_deref_trait::StableDeref for GenericMutexGuard<'_, Cell, Mutex>
 where
-    Cell: Deref<Target = UnsafeCell<T>>,
+    Cell: Deref<Target = UnsafeCell<MaybeUninit<T>>>,
     Mutex: mutex::MutexHandle,
 {
 }