Add comments for ArcFlexMut

Cargo.toml

@@ -51,7 +51,7 @@ strum_macros = "0.24"
 sysinfo = "0.29"
 
 parking_lot = { version = "0.12", features = [] }
-peace-lock = { git = "https://github.com/qinsoon/peace-lock.git", rev = "b91104c295ff60f815a931c670a69858dfdafbe5" }
+peace-lock = "0.1.3"
 # peace-lock = { path = "../peace-lock" }
 
 [dev-dependencies]
@@ -76,8 +76,8 @@ perf_counter = ["pfm"]
 # Do not modify the following line - ci-common.sh matches it
 # -- Non mutually exclusive features --
 
-# Turn on checks in peace-lock to check race conditions
-peace_lock_race_check = ["peace-lock/check"]
+# Turn on checks for the type ArcFlexMut (we use peace-lock for the type so just turn on check for peace-lock).
+check_flex_mut = ["peace-lock/check"]
 
 # spaces with different semantics
 
@@ -136,7 +136,7 @@ nogc_no_zeroing = ["nogc_lock_free"]
 single_worker = []
 
 # To run expensive comprehensive runtime checks, such as checking duplicate edges
-extreme_assertions = []
+extreme_assertions = ["check_flex_mut"]
 
 # Enable multiple spaces for NoGC, each allocator maps to an individual ImmortalSpace.
 nogc_multi_space = []

src/util/rust_util/flex_mut.rs

@@ -13,6 +13,17 @@ macro_rules! to_trait_object {
     }};
 }
 
+/// `ArcFlexMut` is a replacement for `UnsafeCell` for a shared reference in situations where 1.
+/// their mutability is managed by the programmer, 2. mutability is hard to reason about statically,
+/// 3. using locks or `RefCell`/`AtomicRefCell` is not plausible for the sake of performance, and
+/// 4. the shared reference could be both statically typed and a dyn ref to a trait object, depending
+/// on where it is used.
+/// `ArcFlexMut` does not guarantee thread safety, and it does not provide any actual locking.
+/// It provides methods for acquiring a read or write guard, and can optionally check if there is
+/// any possible data race. Without the checks, in a release build, `ArcFlexMut` should perform
+/// as efficient as `UnsafeCell`.
+/// We currently use this type for [`crate::policy::space::Space`]s.
+#[repr(transparent)]
 pub struct ArcFlexMut<T>
 where
     T: ?Sized,
@@ -21,42 +32,54 @@ where
 }
 
 impl<T> ArcFlexMut<T> {
+    /// Create a shared reference to the object.
     pub fn new(v: T) -> Self {
         Self {
             inner: Arc::new(peace_lock::RwLock::new(v)),
         }
     }
 }
 
-impl<T> ArcFlexMut<T> {
-    pub fn into_dyn_space<VM: VMBinding>(self) -> ArcFlexMut<dyn Space<VM>>
-    where
-        T: 'static + Space<VM>,
-    {
-        to_trait_object!(self, dyn Space<VM>)
-    }
-}
-
 impl<T: ?Sized> ArcFlexMut<T> {
+    /// Acquire a read guard to get immutable access to the data. It is allowed to have a reader when there is no writer.
+    /// If the feature `check_flex_mut` is enabled, the method will panic if the rule is violated.
     pub fn read(&self) -> ArcFlexMutReadGuard<'_, T> {
         ArcFlexMutReadGuard {
             inner: self.inner.read(),
         }
     }
 
+    /// Acquire a write guard to get mutable access to the data. It is allowed to have a writer when there is no other writer or reader.
+    /// If the feature `check_flex_mut` is enabled, the method will panic if the rule is violated.
     pub fn write(&self) -> ArcFlexMutWriteGuard<'_, T> {
         ArcFlexMutWriteGuard {
             inner: self.inner.write(),
         }
     }
 }
 
+impl<T> Clone for ArcFlexMut<T>
+where
+    T: ?Sized,
+{
+    fn clone(&self) -> Self {
+        Self {
+            inner: self.inner.clone(),
+        }
+    }
+}
+
+// For types that implements `Downcast`, we can turn the shared reference into a reference of a concrete type.
+
 impl<T: 'static + Downcast + ?Sized> ArcFlexMut<T> {
+    /// Is it allowed to downcast to the given type?
     fn can_downcast<S: 'static>(&self) -> bool {
         let lock = self.inner.read();
         (*lock).as_any().downcast_ref::<S>().is_some()
     }
 
+    /// Downcast the shared reference into a shared reference of a concrete type. The new reference share
+    /// the count and the lock with the old consumed reference.
     pub fn downcast<S: 'static>(self) -> ArcFlexMut<S> {
         if self.can_downcast::<S>() {
             let raw = Arc::into_raw(self.inner);
@@ -68,17 +91,21 @@ impl<T: 'static + Downcast + ?Sized> ArcFlexMut<T> {
     }
 }
 
-impl<T> Clone for ArcFlexMut<T>
-where
-    T: ?Sized,
-{
-    fn clone(&self) -> Self {
-        Self {
-            inner: self.inner.clone(),
-        }
+// Methods to turn the shared reference into a shared reference of a trait object.
+// The references points to the same object with the same count.
+// This impl block is a workaround to implement the functionality specifically for
+// `dyn Space`, as I can't find a way to implement this using generics.
+
+impl<T> ArcFlexMut<T> {
+    pub fn into_dyn_space<VM: VMBinding>(self) -> ArcFlexMut<dyn Space<VM>>
+    where
+        T: 'static + Space<VM>,
+    {
+        to_trait_object!(self, dyn Space<VM>)
     }
 }
 
+/// Read guard for ArcFlexMut
 pub struct ArcFlexMutReadGuard<'a, T>
 where
     T: ?Sized,
@@ -98,6 +125,7 @@ where
     }
 }
 
+/// Write guard for ArcFlexMut
 pub struct ArcFlexMutWriteGuard<'a, T>
 where
     T: ?Sized,