cc: add weakref support

Similar to std::rc::Rc, add downgrade() -> Weak, upgrade() -> Option<Cc>
for weakref support.

Author: quark-zju

src/cc.rs

@@ -37,8 +37,6 @@ use std::ptr::NonNull;
 /// The data shared by multiple `RawCc<T, O>` pointers.
 #[repr(C)]
 pub(crate) struct RawCcBox<T: ?Sized, O: AbstractObjectSpace> {
-    /// The lowest REF_COUNT_SHIFT bits are used for metadata.
-    /// The higher bits are used for ref count.
     pub(crate) ref_count: O::RefCount,
 
     #[cfg(test)]
@@ -75,16 +73,23 @@ pub struct RawCcBoxWithGcHeader<T: ?Sized, O: AbstractObjectSpace> {
 /// ```
 pub type Cc<T> = RawCc<T, ObjectSpace>;
 
+/// Weak reference of [`Cc`](type.Cc.html).
+pub type Weak<T> = RawWeak<T, ObjectSpace>;
+
 /// Low-level type for [`Cc<T>`](type.Cc.html).
 pub struct RawCc<T: ?Sized, O: AbstractObjectSpace>(NonNull<RawCcBox<T, O>>);
 
+/// Low-level type for [`Weak<T>`](type.Weak.html).
+pub struct RawWeak<T: ?Sized, O: AbstractObjectSpace>(NonNull<RawCcBox<T, O>>);
+
 // `ManuallyDrop<T>` does not implement `UnwindSafe`. But `CcBox::drop` does
 // make sure `T` is dropped. If `T` is unwind-safe, so does `CcBox<T>`.
 impl<T: UnwindSafe + ?Sized> UnwindSafe for RawCcBox<T, ObjectSpace> {}
 
-// `NonNull` does not implement `UnwindSafe`. But `Cc` only uses it
+// `NonNull` does not implement `UnwindSafe`. But `Cc` and `Weak` only use it
 // as a "const" pointer. If `T` is unwind-safe, so does `Cc<T>`.
-impl<T: UnwindSafe + ?Sized> UnwindSafe for Cc<T> {}
+impl<T: UnwindSafe + ?Sized, O: AbstractObjectSpace> UnwindSafe for RawCc<T, O> {}
+impl<T: UnwindSafe + ?Sized, O: AbstractObjectSpace> UnwindSafe for RawWeak<T, O> {}
 
 /// Type-erased `Cc<T>` with interfaces needed by GC.
 ///
@@ -275,6 +280,11 @@ impl<T: ?Sized, O: AbstractObjectSpace> RawCcBox<T, O> {
         self.ref_count.ref_count()
     }
 
+    #[inline]
+    fn weak_count(&self) -> usize {
+        self.ref_count.weak_count()
+    }
+
     #[inline]
     fn set_dropped(&self) -> bool {
         self.ref_count.set_dropped()
@@ -348,6 +358,44 @@ impl<T: std::fmt::Debug + ?Sized> OptionalDebug for T {
     }
 }
 
+impl<T: ?Sized, O: AbstractObjectSpace> RawCc<T, O> {
+    /// Obtains a "weak reference", a non-owning pointer.
+    pub fn downgrade(&self) -> RawWeak<T, O> {
+        let inner = self.inner();
+        inner.ref_count.inc_weak();
+        debug::log(|| {
+            (
+                inner.debug_name(),
+                format!("new-weak ({})", inner.ref_count.weak_count()),
+            )
+        });
+        RawWeak(self.0)
+    }
+}
+
+impl<T: ?Sized, O: AbstractObjectSpace> RawWeak<T, O> {
+    /// Attempts to obtain a "strong reference".
+    ///
+    /// Returns `None` if the value has already been dropped.
+    pub fn upgrade(&self) -> Option<RawCc<T, O>> {
+        let inner = self.inner();
+        // Make the below operation "atomic".
+        let _locked = inner.ref_count.locked();
+        if inner.is_dropped() {
+            None
+        } else {
+            inner.inc_ref();
+            debug::log(|| {
+                (
+                    inner.debug_name(),
+                    format!("new-strong ({})", inner.ref_count.ref_count()),
+                )
+            });
+            Some(RawCc(self.0))
+        }
+    }
+}
+
 impl<T: ?Sized, O: AbstractObjectSpace> RawCc<T, O> {
     #[inline]
     pub(crate) fn inner(&self) -> &RawCcBox<T, O> {
@@ -380,11 +428,24 @@ impl<T: ?Sized, O: AbstractObjectSpace> RawCc<T, O> {
         self.inner().ref_count()
     }
 
+    #[inline]
+    fn weak_count(&self) -> usize {
+        self.inner().weak_count()
+    }
+
     pub(crate) fn debug_name(&self) -> String {
         self.inner().debug_name()
     }
 }
 
+impl<T: ?Sized, O: AbstractObjectSpace> RawWeak<T, O> {
+    #[inline]
+    fn inner(&self) -> &RawCcBox<T, O> {
+        // safety: CcBox lifetime maintained by ref count. Pointer is valid.
+        unsafe { self.0.as_ref() }
+    }
+}
+
 impl<T: ?Sized, O: AbstractObjectSpace> Clone for RawCc<T, O> {
     #[inline]
     fn clone(&self) -> Self {
@@ -398,6 +459,22 @@ impl<T: ?Sized, O: AbstractObjectSpace> Clone for RawCc<T, O> {
     }
 }
 
+impl<T: ?Sized, O: AbstractObjectSpace> Clone for RawWeak<T, O> {
+    #[inline]
+    fn clone(&self) -> Self {
+        let inner = self.inner();
+        let ref_count = &inner.ref_count;
+        ref_count.inc_weak();
+        debug::log(|| {
+            (
+                inner.debug_name(),
+                format!("clone-weak ({})", ref_count.weak_count()),
+            )
+        });
+        Self(self.0)
+    }
+}
+
 impl<T: ?Sized> Deref for Cc<T> {
     type Target = T;
 
@@ -453,13 +530,41 @@ fn drop_ccbox<T: ?Sized, O: AbstractObjectSpace>(cc_box: *mut RawCcBox<T, O>) {
 impl<T: ?Sized, O: AbstractObjectSpace> Drop for RawCc<T, O> {
     fn drop(&mut self) {
         let ptr: *mut RawCcBox<T, O> = self.0.as_ptr();
+        let inner = self.inner();
         // Block threaded collector. This is needed because "drop()" is a
         // complex operation. The whole operation needs to be "atomic".
-        let _locked = self.inner().ref_count.locked();
+        let _locked = inner.ref_count.locked();
         let old_ref_count = self.dec_ref();
         debug::log(|| (self.debug_name(), format!("drop ({})", self.ref_count())));
         debug_assert!(old_ref_count >= 1);
         if old_ref_count == 1 {
+            if self.weak_count() == 0 {
+                // safety: CcBox lifetime maintained by ref count.
+                drop_ccbox(ptr);
+            } else {
+                inner.drop_t();
+            }
+        }
+    }
+}
+
+impl<T: ?Sized, O: AbstractObjectSpace> Drop for RawWeak<T, O> {
+    fn drop(&mut self) {
+        let ptr: *mut RawCcBox<T, O> = self.0.as_ptr();
+        let inner = self.inner();
+        let ref_count = &inner.ref_count;
+        // Block threaded collector to "freeze" the ref count, for safety.
+        let _locked = ref_count.locked();
+        let old_ref_count = ref_count.ref_count();
+        let old_weak_count = ref_count.dec_weak();
+        debug::log(|| {
+            (
+                inner.debug_name(),
+                format!("drop-weak ({})", ref_count.weak_count()),
+            )
+        });
+        debug_assert!(old_weak_count >= 1);
+        if old_ref_count == 0 && old_weak_count == 1 {
             // safety: CcBox lifetime maintained by ref count.
             drop_ccbox(ptr);
         }

src/debug.rs

@@ -12,6 +12,7 @@ thread_local!(pub(crate) static VERBOSE: bool = std::env::var("VERBOSE").is_ok()
 
 /// Enable debug log for the given scope. Return the debug log.
 pub(crate) fn capture_log(mut func: impl FnMut()) -> String {
+    NEXT_DEBUG_NAME.with(|n| n.set(0));
     LAST_NAME.with(|n| n.borrow_mut().clear());
     ENABLED.with(|e| e.set(true));
     func();

src/lib.rs

@@ -148,6 +148,22 @@
 //! }
 //! ```
 //!
+//! ### Weak references
+//!
+//! Similar to `std::rc::Rc`, use [`Cc::downgrade`](struct.RawCc.html#method.downgrade)
+//! to create weak references. Use [`Weak::upgrade`](struct.RawWeak.html#method.upgrade)
+//! to test if the value is still alive and to access the value. For example:
+//!
+//! ```
+//! use gcmodule::{Cc, Weak};
+//!
+//! let value = Cc::new("foo");
+//! let weak: Weak<_> = value.downgrade();
+//! assert_eq!(*weak.upgrade().unwrap(), "foo");
+//! drop(value);
+//! assert!(weak.upgrade().is_none());  // Cannot upgrade after dropping value
+//! ```
+//!
 //! # Technical Details
 //!
 //! ## Memory Layouts
@@ -157,15 +173,16 @@
 //! ### Untracked types
 //!
 //! If [`<T as Trace>::is_type_tracked()`](trait.Trace.html#method.is_type_tracked)
-//! returns `false`, the layout is similar to `Rc<T>` but without a `weak_count`:
+//! returns `false`, the layout is similar to `Rc<T>`:
 //!
 //! ```plain,ignore
 //! Shared T                    Pointer
-//! +------------------+     .-- Cc<T>
-//! | ref_count: usize | <--<
-//! |------------------|     '-- Cc<T>::clone()
-//! | T (shared data)  | <--- Cc<T>::deref()
-//! +------------------+
+//! +-------------------+     .-- Cc<T>
+//! | ref_count: usize  | <--<
+//! | weak_count: usize |     '-- Cc<T>::clone()
+//! |-------------------|
+//! | T (shared data)   | <--- Cc<T>::deref()
+//! +-------------------+
 //! ```
 //!
 //! ### Tracked types
@@ -176,15 +193,16 @@
 //!
 //! ```plain,ignore
 //! Shared T with GcHeader
-//! +------------------+
-//! | gc_prev: pointer | ---> GcHeader in a linked list.
-//! | gc_next: pointer |
-//! | vptr<T>: pointer | ---> Pointer to the `&T as &dyn Trace` virtual table.
-//! |------------------|
-//! | ref_count: usize | <--- Cc<T>
-//! | ---------------- |
-//! | T (shared data)  | <--- Cc<T>::deref()
-//! +------------------+
+//! +-------------------+
+//! | gc_prev: pointer  | ---> GcHeader in a linked list.
+//! | gc_next: pointer  |
+//! | vptr<T>: pointer  | ---> Pointer to the `&T as &dyn Trace` virtual table.
+//! |-------------------|
+//! | ref_count: usize  | <--- Cc<T>
+//! | weak_count: usize |
+//! | ----------------- |
+//! | T (shared data)   | <--- Cc<T>::deref()
+//! +-------------------+
 //! ```
 //!
 //! ## Incorrect `Trace` implementation
@@ -256,7 +274,7 @@ pub mod testutil;
 mod trace;
 mod trace_impls;
 
-pub use cc::{Cc, RawCc};
+pub use cc::{Cc, RawCc, RawWeak, Weak};
 pub use collect::{collect_thread_cycles, count_thread_tracked, ObjectSpace};
 pub use trace::{Trace, Tracer};
 

src/tests.rs

@@ -109,6 +109,76 @@ fn test_simple_non_trait_cycles() {
     assert_eq!(collect::collect_thread_cycles(), 2);
 }
 
+#[test]
+fn test_weakref_without_cycles() {
+    let log = debug::capture_log(|| {
+        let s1 = Cc::new("S".to_string());
+        let w1 = s1.downgrade();
+        let s2 = w1.upgrade().unwrap();
+        let w2 = w1.clone();
+        drop(s1);
+        drop(s2);
+        let w3 = w2.clone();
+        assert!(w3.upgrade().is_none());
+        assert!(w2.upgrade().is_none());
+        assert!(w1.upgrade().is_none());
+    });
+    assert_eq!(
+        log,
+        r#"
+0: new (CcBox), new-weak (1), new-strong (2), clone-weak (2), drop (1), drop (0), drop (T), clone-weak (3), drop-weak (2), drop-weak (1), drop-weak (0), drop (CcBox)"#
+    );
+}
+
+#[test]
+fn test_weakref_with_cycles() {
+    let log = debug::capture_log(|| {
+        debug::NEXT_DEBUG_NAME.with(|n| n.set(1));
+        let a: Cc<RefCell<Vec<Box<dyn Trace>>>> = Cc::new(RefCell::new(Vec::new()));
+        debug::NEXT_DEBUG_NAME.with(|n| n.set(2));
+        let b: Cc<RefCell<Vec<Box<dyn Trace>>>> = Cc::new(RefCell::new(Vec::new()));
+        a.borrow_mut().push(Box::new(b.clone()));
+        b.borrow_mut().push(Box::new(a.clone()));
+        let wa = a.downgrade();
+        let wa1 = wa.clone();
+        let wb = b.downgrade();
+        drop(a);
+        drop(b);
+        assert!(wa.upgrade().is_some());
+        assert!(wb.upgrade().is_some());
+        assert_eq!(collect::collect_thread_cycles(), 2);
+        assert!(wa.upgrade().is_none());
+        assert!(wa1.upgrade().is_none());
+        assert!(wb.upgrade().is_none());
+        assert!(wb.clone().upgrade().is_none());
+    });
+    assert_eq!(
+        log,
+        r#"
+1: new (CcBoxWithGcHeader)
+2: new (CcBoxWithGcHeader), clone (2)
+1: clone (2), new-weak (1), clone-weak (2)
+2: new-weak (1)
+1: drop (1)
+2: drop (1)
+1: new-strong (2), drop (1)
+2: new-strong (2), drop (1)
+collect: collect_thread_cycles
+2: gc_traverse
+1: trace, gc_traverse
+2: trace
+collect: 2 unreachable objects
+2: gc_clone (2)
+1: gc_clone (2)
+2: drop (T)
+1: drop (1), drop (T)
+2: drop (1), drop (0)
+1: drop (0)
+2: clone-weak (2), drop-weak (1), drop-weak (0), drop (CcBoxWithGcHeader)
+1: drop-weak (1), drop-weak (0), drop (CcBoxWithGcHeader)"#
+    );
+}
+
 #[test]
 fn test_drop_by_ref_count() {
     let log = debug::capture_log(|| test_small_graph(3, &[], 0, 0));