feat: loom support

Author: George-Miao

Cargo.toml

@@ -17,6 +17,7 @@ local-event = { version = "0.1.1", default-features = false, optional = true }
 see = { version = "0.1.1", optional = true }
 slab = { version = "0.4.11", optional = true }
 
+
 [features]
 watch = ["dep:see"]
 mutex = ["dep:slab"]
@@ -25,5 +26,11 @@ event = ["dep:event-listener", "dep:local-event"]
 bilock = ["waker_slot"]
 async_flag = ["waker_slot"]
 
+[target.'cfg(loom)'.dependencies]
+loom = { version = "0.7.2", features = ["futures"] }
+
 [dev-dependencies]
 futures = { version = "0.3.31", features = ["executor"] }
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(loom)'] }

README.md

@@ -1,5 +1,12 @@
 # Synchrony
 
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/compio-rs/synchrony/blob/master/LICENSE)
+[![crates.io](https://img.shields.io/crates/v/synchrony)](https://crates.io/crates/synchrony)
+[![docs.rs](https://img.shields.io/badge/docs.rs-synchrony-latest)](https://docs.rs/synchrony)
+[![Check](https://github.com/compio-rs/synchrony/actions/workflows/ci_check.yml/badge.svg)](https://github.com/compio-rs/synchrony/actions/workflows/ci_check.yml)
+[![Telegram](https://img.shields.io/badge/Telegram-compio--rs-blue?logo=telegram)](https://t.me/compio_rs)
+[![Discord](https://img.shields.io/discord/1429103613602435114?logo=discord&label=Discord)](https://discord.gg/bGG8EF9v)
+
 A library that provides both sync and unsync versions of common synchronization primitives.
 
 ## Features
@@ -8,11 +15,33 @@ All of the following primitives are provided in both sync and unsync versions:
 
 - Shared (`Rc`/`Arc`)
 - Atomic Scalars
-- Watch 
+- Watch
 - Waker Slot (`AtomicWaker` and its unsync counterpart)
 - Mutex
 - Async Mutex
 - BiLock
 - Flag (specialized `AtomicBool`)
 - Event (`event-listener` and `local-event`)
 - Async Flag
+
+## Loom Testing Support
+
+This library includes built-in support for [loom](https://github.com/tokio-rs/loom), a testing tool for concurrent Rust code that helps verify the correctness of concurrent algorithms.
+
+When compiled with `--cfg loom`, the library automatically switches to use loom's implementations of synchronization primitives instead of the standard library versions. This enables you to:
+
+- Detect data races and concurrency bugs
+- Verify lock-free algorithms
+- Test different thread interleavings exhaustively
+
+For more information about loom and how to write loom tests, see the [loom documentation](https://docs.rs/loom).
+
+### Supported Types
+
+The following types automatically use loom implementations when the `loom` cfg is enabled:
+
+- `std::sync::atomic::*` types (`AtomicBool`, `AtomicUsize`, etc.)
+- `std::sync::Arc` → `loom::sync::Arc`
+- `std::sync::Mutex` → `loom::sync::Mutex`
+- `std::cell::UnsafeCell` → `loom::cell::UnsafeCell`
+- `std::cell::Cell` → `loom::cell::Cell`

bacon.toml

@@ -0,0 +1,29 @@
+default_job = "clippy-loom"
+env.CARGO_TERM_COLOR = "always"
+
+[jobs.clippy-loom]
+command = ["cargo", "clippy"]
+env.RUSTFLAGS = "--cfg loom"
+need_stdout = false
+
+[jobs.test]
+command = [
+    "cargo", "nextest", "run",
+    "--hide-progress-bar", "--failure-output", "final"
+]
+need_stdout = true
+analyzer = "nextest"
+
+[jobs.doc]
+command = ["cargo", "doc", "--no-deps"]
+need_stdout = false
+
+[jobs.doc-open]
+command = ["cargo", "doc", "--no-deps", "--open"]
+need_stdout = false
+on_success = "back"
+
+[keybindings]
+c = "job:clippy-loom"
+d = "job:doc-open"
+t = "job:test"

flake.nix

@@ -1,5 +1,5 @@
 {
-  description = "Compio dev shell";
+  description = "Synchrony dev shell";
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
@@ -27,7 +27,9 @@
       {
         devShells.default = mkShell {
           buildInputs = [
+            bacon
             cargo-hack
+            cargo-nextest
             (rust-bin.selectLatestNightlyWith (
               toolchain:
               toolchain.default.override {

src/atomic/mod.rs

@@ -2,10 +2,12 @@
 
 /// Multithreaded atomic scalars
 pub mod sync {
-    pub use std::sync::atomic::{
-        AtomicBool, AtomicI8, AtomicI16, AtomicI32, AtomicI64, AtomicIsize, AtomicU8, AtomicU16,
-        AtomicU32, AtomicU64, AtomicUsize,
-    };
+    crate::cfg_loom! {
+        pub use std::sync::atomic::{
+            AtomicBool, AtomicI8, AtomicI16, AtomicI32, AtomicI64, AtomicIsize, AtomicU8, AtomicU16,
+            AtomicU32, AtomicU64, AtomicUsize,
+        };
+    }
 }
 
 /// Singlethreaded atomic scalars based on [`std::cell::Cell`]

src/atomic/unsync.rs

@@ -1,4 +1,8 @@
-use std::{cell::Cell, fmt::Debug, sync::atomic::Ordering};
+use std::{fmt::Debug, sync::atomic::Ordering};
+
+crate::cfg_loom! {
+    use std::cell::Cell;
+}
 
 atomic_int!(AtomicU8(u8));
 atomic_int!(AtomicU16(u16));
@@ -41,11 +45,19 @@ impl Debug for AtomicBool {
 
 impl AtomicBool {
     /// Creates a new [`AtomicBool`]
+    #[cfg(not(loom))]
     pub const fn new(val: bool) -> Self {
         Self { v: Cell::new(val) }
     }
 
+    /// Creates a new [`AtomicBool`]
+    #[cfg(loom)]
+    pub fn new(val: bool) -> Self {
+        Self { v: Cell::new(val) }
+    }
+
     /// Returns a mutable reference to the underlying boolean.
+    #[cfg(not(loom))]
     pub fn get_mut(&mut self) -> &mut bool {
         self.v.get_mut()
     }
@@ -195,12 +207,20 @@ macro_rules! atomic_int {
         }
 
         impl $t {
+            #[cfg(not(loom))]
             #[doc = concat!("Creates a new [`", stringify!($t), "`]")]
             pub const fn new(val: $i) -> Self {
                 Self { v: Cell::new(val) }
             }
 
+            #[cfg(loom)]
+            #[doc = concat!("Creates a new [`", stringify!($t), "`]")]
+            pub fn new(val: $i) -> Self {
+                Self { v: Cell::new(val) }
+            }
+
             /// Returns a mutable reference to the underlying integer.
+            #[cfg(not(loom))]
             pub fn get_mut(&mut self) -> &mut $i {
                 self.v.get_mut()
             }

src/bilock.rs

@@ -18,14 +18,17 @@ pub mod unsync {
 macro_rules! impl_bilock {
     ($sync:ident) => {
         use std::{
-            cell::UnsafeCell,
             fmt::Debug,
             future::Future,
             ops::{Deref, DerefMut},
             pin::Pin,
             task::{Context, Poll},
         };
 
+        crate::cfg_loom! {
+            use std::cell::UnsafeCell;
+        }
+
         use crate::$sync::{flag::Flag, shared::Shared, waker_slot::WakerSlot};
 
         /// A lock shared by two parties.

src/lib.rs

@@ -118,3 +118,17 @@ pub mod unsync {
 /// A trait to assert that a type is `Send + Sync`.
 #[allow(dead_code)]
 trait AssertMt: Send + Sync {}
+
+macro_rules! cfg_loom {
+    {
+        $vis:vis use $alt:ident :: $($tail:tt)*
+    } => {
+        #[cfg(loom)]
+        $vis use loom::$($tail)*
+
+        #[cfg(not(loom))]
+        $vis use $alt::$($tail)*
+    };
+}
+
+use cfg_loom;

src/mutex.rs

@@ -79,7 +79,6 @@ const WAIT_KEY_NONE: usize = usize::MAX;
 macro_rules! impl_mutex {
     ($sync:ident) => {
         use std::{
-            cell::UnsafeCell,
             fmt,
             future::Future,
             marker::PhantomData,
@@ -93,6 +92,11 @@ macro_rules! impl_mutex {
         use slab::Slab;
 
         use super::*;
+
+        crate::cfg_loom! {
+            use std::cell::UnsafeCell;
+        }
+
         use crate::$sync::{
             atomic::AtomicUsize, mutex_blocking::Mutex as BlockingMutex, shared::Shared,
         };

src/mutex_blocking.rs

@@ -2,10 +2,12 @@
 
 /// Multithreaded blocking Mutex
 pub mod sync {
+    crate::cfg_loom! {
+        use std::sync::{Mutex as Inner, MutexGuard as InnerGuard};
+    }
     use std::{
         fmt,
         ops::{Deref, DerefMut},
-        sync::{Mutex as Inner, MutexGuard as InnerGuard},
     };
 
     /// A multithreaded Mutex based on [`std::sync::Mutex`].
@@ -19,10 +21,19 @@ pub mod sync {
 
     impl<T> Mutex<T> {
         /// Creates a new mutex in an unlocked state ready for use.
+        #[cfg(not(loom))]
         pub const fn new(val: T) -> Self {
             Self(Inner::new(val))
         }
 
+        /// Creates a new mutex in an unlocked state ready for use.
+        ///
+        /// This `new` is not `const` due to loom not supporting it.
+        #[cfg(loom)]
+        pub fn new(val: T) -> Self {
+            Self(Inner::new(val))
+        }
+
         /// Get the inner [`std::sync::Mutex`].
         pub fn into_inner(self) -> Inner<T> {
             self.0