Finish leak doc/tests

.github/workflows/ci.yml

@@ -142,6 +142,9 @@ jobs:
   miri:
     name: Miri
     runs-on: ubuntu-latest
+    env:
+      # the tests for `ArcStr::leak` intentionally leak memory.
+      MIRIFLAGS: -Zmiri-ignore-leaks
     steps:
       - uses: actions/checkout@v4
       - uses: hecrj/setup-rust-action@v2
@@ -181,6 +184,7 @@ jobs:
       RUST_BACKTRACE: 0
       # only used by asan, but we set it for all of them cuz its easy
       ASAN_OPTIONS: detect_stack_use_after_return=1
+      LSAN_OPTIONS: "suppressions=lsan_suppressions.txt"
     strategy:
       fail-fast: false
       matrix:
@@ -190,6 +194,9 @@ jobs:
         include:
           - sanitizer: memory
             extra_rustflags: "-Zsanitizer-memory-track-origins"
+          - sanitizer: address
+            # to disable the ArcStr::leak test (can't get suppressions to work in CI)
+            extra_rustflags: "--cfg=asan"
 
     steps:
       - uses: actions/checkout@v4

src/arc_str.rs

@@ -537,27 +537,48 @@ impl ArcStr {
         }
     }
 
-    /// Convert the `ArcStr` into a `'static` `ArcStr`, even if it was
-    /// originally created from runtime values.
+    /// Convert the `ArcStr` into a "static" `ArcStr`, even if it was originally
+    /// created from runtime values. The `&'static str` is returned.
     ///
-    /// This is useful
+    /// This is useful if you want to use [`ArcStr::as_static`] or
+    /// [`ArcStr::is_static`] on a value only known at runtime.
     ///
-    /// If the `ArcStr` is already static, then
+    /// If the `ArcStr` is already static, then this is a noop.
+    ///
+    /// # Caveats
+    /// Calling this function on an ArcStr will cause us to never free it, thus
+    /// leaking it's memory. Doing this excessively can lead to problems.
+    ///
+    /// # Examples
+    /// ```no_run
+    /// # // This isn't run because it needs a leakcheck suppression,
+    /// # // which I can't seem to make work in CI (no symbols for
+    /// # // doctests?). Instead, we test this in tests/arc_str.rs
+    /// # use arcstr::ArcStr;
+    /// let s = ArcStr::from("foobar");
+    /// assert!(!ArcStr::is_static(&s));
+    /// assert!(ArcStr::as_static(&s).is_none());
+    ///
+    /// let leaked: &'static str = s.leak();
+    /// assert_eq!(leaked, s);
+    /// assert!(ArcStr::is_static(&s));
+    /// assert_eq!(ArcStr::as_static(&s), Some("foobar"));
+    /// ```
     #[inline]
-    pub fn leak(this: &Self) -> &'static str {
-        if Self::has_static_lenflag(this) {
-            return unsafe { Self::to_static_unchecked(this) };
+    pub fn leak(&self) -> &'static str {
+        if Self::has_static_lenflag(self) {
+            return unsafe { Self::to_static_unchecked(self) };
         }
         let is_static_count = unsafe {
             // Not sure about ordering, maybe relaxed would be fine.
-            Self::load_count_flag_raw(this, Ordering::Acquire)
+            Self::load_count_flag_raw(self, Ordering::Acquire)
         };
         if is_static_count.flag_part() {
-            return unsafe { Self::to_static_unchecked(this) };
+            return unsafe { Self::to_static_unchecked(self) };
         }
-        unsafe { Self::become_static(this, is_static_count.uint_part() == 1) };
-        debug_assert!(Self::is_static(this));
-        unsafe { Self::to_static_unchecked(this) }
+        unsafe { Self::become_static(self, is_static_count.uint_part() == 1) };
+        debug_assert!(Self::is_static(self));
+        unsafe { Self::to_static_unchecked(self) }
     }
 
     unsafe fn become_static(this: &Self, is_unique: bool) {
@@ -1657,4 +1678,20 @@ mod loomtest {
             t2.join().unwrap();
         });
     }
+
+    #[test]
+    fn leak_drop() {
+        loom::model(|| {
+            let a1 = ArcStr::from("foo");
+            let a2 = a1.clone();
+
+            let t1 = thread::spawn(move || {
+                drop(a1);
+            });
+            let t2 = thread::spawn(move || a2.leak());
+            t1.join().unwrap();
+            let leaked: &'static str = t2.join().unwrap();
+            assert_eq!(leaked, "foo");
+        });
+    }
 }

tests/arc_str.rs

@@ -4,6 +4,7 @@
     // yep, we create owned instance just for comparison, to test comparison
     // with owned instacnces.
     clippy::cmp_owned,
+    unexpected_cfgs,
 )]
 use arcstr::ArcStr;
 
@@ -353,3 +354,17 @@
 fn repeat_string_panics() {
     ArcStr::repeat("AAA", usize::MAX);
 }
+
+#[test]
+#[allow(unknown_lints)]
+#[cfg_attr(asan, ignore)] // Leaks memory intentionally
+fn test_leaking() {
+    let s = ArcStr::from("foobar");
+    assert!(!ArcStr::is_static(&s));
+    assert!(ArcStr::as_static(&s).is_none());
+
+    let leaked: &'static str = s.leak();
+    assert_eq!(leaked, s);
+    assert!(ArcStr::is_static(&s));
+    assert_eq!(ArcStr::as_static(&s), Some("foobar"));
+}