add protected RMW operations to Guard

Author: ibraheemdev

src/collector.rs

@@ -72,9 +72,10 @@ impl Collector {
     /// loads of concurrent objects for its lifetime. The thread will be
     /// marked as inactive when the guard is dropped.
     ///
-    /// Note that loads of objects that may be retired must be protected with the
-    /// [`Guard::protect`]. See [the guide](crate::guide#starting-operations) for
-    /// an introduction to using guards, or the documentation of [`LocalGuard`] for
+    /// Note that loads of objects that may be retired must be protected with
+    /// the [`Guard::protect`]. See [the
+    /// guide](crate::guide#starting-operations) for an introduction to
+    /// using guards, or the documentation of [`LocalGuard`] for
     /// more details.
     ///
     /// Note that `enter` is reentrant, and it is legal to create multiple

src/guard.rs

@@ -22,7 +22,8 @@ pub trait Guard {
     /// This method is not marked as `unsafe`, but will affect the validity of
     /// pointers loaded using [`Guard::protect`], similar to dropping a guard.
     /// It is intended to be used safely by users of concurrent data structures,
-    /// as references will be tied to the guard and this method takes `&mut self`.
+    /// as references will be tied to the guard and this method takes `&mut
+    /// self`.
     fn refresh(&mut self);
 
     /// Flush any retired values in the local batch.
@@ -46,8 +47,8 @@ pub trait Guard {
     /// a cheap way to get an identifier for the current thread without TLS
     /// overhead. Note that thread IDs may be reused, so the value returned
     /// is only unique for the lifetime of this thread.
-    ///
     fn thread_id(&self) -> usize;
+
     /// Protects the load of an atomic pointer.
     ///
     /// Any valid pointer loaded through a guard using the `protect` method is
@@ -58,10 +59,63 @@ pub trait Guard {
     ///
     /// Note that the lifetime of a guarded pointer is logically tied to that of
     /// the guard — when the guard is dropped the pointer is invalidated. Data
-    /// structures that return shared references to values should ensure that the
-    /// lifetime of the reference is tied to the lifetime of a guard.
-    fn protect<T>(&self, ptr: &AtomicPtr<T>, ordering: Ordering) -> *mut T {
-        ptr.load(raw::Collector::protect(ordering))
+    /// structures that return shared references to values should ensure that
+    /// the lifetime of the reference is tied to the lifetime of a guard.
+    fn protect<T>(&self, ptr: &AtomicPtr<T>, order: Ordering) -> *mut T {
+        ptr.load(raw::Collector::protect(order))
+    }
+
+    /// Stores a value into the pointer, returning the protected previous value.
+    ///
+    /// This method is equivalent to [`AtomicPtr::swap`], except the returned
+    /// value is guaranteed to be protected with the same guarantees as
+    /// [`Guard::protect`].
+    fn swap<T>(&self, ptr: &AtomicPtr<T>, value: *mut T, order: Ordering) -> *mut T {
+        ptr.swap(value, raw::Collector::protect(order))
+    }
+
+    /// Stores a value into the pointer if the current value is the same as the
+    /// `current` value, returning the protected previous value.
+    ///
+    /// This method is equivalent to [`AtomicPtr::compare_exchange`], except the
+    /// returned value is guaranteed to be protected with the same
+    /// guarantees as [`Guard::protect`].
+    fn compare_exchange<T>(
+        &self,
+        ptr: &AtomicPtr<T>,
+        current: *mut T,
+        new: *mut T,
+        success: Ordering,
+        failure: Ordering,
+    ) -> Result<*mut T, *mut T> {
+        ptr.compare_exchange(
+            current,
+            new,
+            raw::Collector::protect(success),
+            raw::Collector::protect(failure),
+        )
+    }
+
+    /// Stores a value into the pointer if the current value is the same as the
+    /// `current` value, returning the protected previous value.
+    ///
+    /// This method is equivalent to [`AtomicPtr::compare_exchange_weak`],
+    /// except the returned value is guaranteed to be protected with the
+    /// same guarantees as [`Guard::protect`].
+    fn compare_exchange_weak<T>(
+        &self,
+        ptr: &AtomicPtr<T>,
+        current: *mut T,
+        new: *mut T,
+        success: Ordering,
+        failure: Ordering,
+    ) -> Result<*mut T, *mut T> {
+        ptr.compare_exchange_weak(
+            current,
+            new,
+            raw::Collector::protect(success),
+            raw::Collector::protect(failure),
+        )
     }
 
     /// Retires a value, running `reclaim` when no threads hold a reference to

src/raw/collector.rs

@@ -87,24 +87,20 @@ impl Collector {
         //
         // Note that all pointer loads perform a light barrier to participate in the
         // total order.
-        membarrier::light_store_barrier();
+        membarrier::light_barrier();
     }
 
-    /// Strengthens an ordering to that necessary to protect the load of a pointer.
+    /// Strengthens an ordering to that necessary to protect the load of a
+    /// pointer.
     #[inline]
-    pub fn protect(_ordering: Ordering) -> Ordering {
-        // This fence shouldn't really be necessary because loads use `SeqCst`
-        // unconditionally, but it doesn't hurt.
-        membarrier::light_load_barrier();
-
+    pub fn protect(_order: Ordering) -> Ordering {
         // We have to respect both the user provided ordering and the ordering required
         // by the membarrier strategy. `SeqCst` is equivalent to `Acquire` on
         // most platforms, so we just use it unconditionally.
         //
-        // Loads performed with this ordering, paired with the light barrier above, will
-        // participate in the total order established by `enter`, and thus see the new
-        // values of any pointers that were retired when the thread was
-        // inactive.
+        // Loads performed with this ordering, paired with the light barrier in `enter`,
+        // will participate in the total order established by `enter`, and thus see the
+        // new values of any pointers that were retired when the thread was inactive.
         Ordering::SeqCst
     }
 

src/raw/membarrier.rs

@@ -4,8 +4,8 @@
 //!
 //! There is a total order over all memory barriers provided by this module:
 //! - Light store barriers, created by a pair of [`light_store`] and
-//!   [`light_store_barrier`].
-//! - Light load barriers, created by a pair of [`light_load_barrier`] and
+//!   [`light_barrier`].
+//! - Light load barriers, created by a pair of [`light_barrier`] and
 //!   [`light_load`].
 //! - Sequentially consistent barriers, or cumulative light barriers.
 //! - Heavy barriers, created by [`heavy`].
@@ -50,15 +50,10 @@ mod default {
         Ordering::SeqCst
     }
 
-    /// Issues a light memory barrier for a preceding store operation.
+    /// Issues a light memory barrier for a preceding store or subsequent load
+    /// operation.
     #[inline]
-    pub fn light_store_barrier() {
-        // This is a no-op due to strong loads and stores.
-    }
-
-    /// Issues a light memory barrier for a subsequent load operation.
-    #[inline]
-    pub fn light_load_barrier() {
+    pub fn light_barrier() {
         // This is a no-op due to strong loads and stores.
     }
 
@@ -95,17 +90,10 @@ mod linux {
         }
     }
 
-    /// Issues a light memory barrier for a preceding store operation.
-    #[inline]
-    pub fn light_store_barrier() {
-        atomic::compiler_fence(atomic::Ordering::SeqCst)
-    }
-
-    /// Issues a light memory barrier for a subsequent load operation.
+    /// Issues a light memory barrier for a preceding store or subsequent load
+    /// operation.
     #[inline]
-    pub fn light_load_barrier() {
-        // This fence shouldn't really be necessary because loads use `SeqCst`
-        // unconditionally, but it doesn't hurt.
+    pub fn light_barrier() {
         atomic::compiler_fence(atomic::Ordering::SeqCst)
     }
 
@@ -167,9 +155,9 @@ mod linux {
         ///
         /// # Caveat
         ///
-        /// We're defining it here because, unfortunately, the `libc` crate currently doesn't
-        /// expose `membarrier_cmd` for us. You can find the numbers in the
-        /// [Linux source code](https://github.com/torvalds/linux/blob/master/include/uapi/linux/membarrier.h).
+        /// We're defining it here because, unfortunately, the `libc` crate
+        /// currently doesn't expose `membarrier_cmd` for us. You can
+        /// find the numbers in the [Linux source code](https://github.com/torvalds/linux/blob/master/include/uapi/linux/membarrier.h).
         ///
         /// This enum should really be `#[repr(libc::c_int)]`, but Rust
         /// currently doesn't allow it.
@@ -349,16 +337,11 @@ mod windows {
         Ordering::Relaxed
     }
 
-    /// Issues a light memory barrier for a preceding store operation.
-    #[inline]
-    pub fn light_store_barrier() {
-        atomic::compiler_fence(Ordering::SeqCst);
-    }
-
-    /// Issues a light memory barrier for a subsequent load operation.
+    /// Issues a light memory barrier for a preceding store or subsequent load
+    /// operation.
     #[inline]
-    pub fn light_load_barrier() {
-        atomic::compiler_fence(Ordering::SeqCst);
+    pub fn light_barrier() {
+        atomic::compiler_fence(atomic::Ordering::SeqCst)
     }
 
     /// The ordering for a load operation that synchronizes with heavy barriers.

src/raw/tls/mod.rs

@@ -39,10 +39,10 @@ unsafe impl<T: Send> Send for ThreadLocal<T> {}
 
 /// Safety:
 ///
-/// - Values can be inserted through a shared reference and thus dropped
-///   on another thread than they were created on, hence `T: Send`.
-/// - However, there is no way to access a `T` inserted by another thread
-///   except through iteration, which is unsafe, so `T: Sync` is not required.
+/// - Values can be inserted through a shared reference and thus dropped on
+///   another thread than they were created on, hence `T: Send`.
+/// - However, there is no way to access a `T` inserted by another thread except
+///   through iteration, which is unsafe, so `T: Sync` is not required.
 unsafe impl<T: Send> Sync for ThreadLocal<T> {}
 
 impl<T> ThreadLocal<T> {

src/reclaim.rs

@@ -1,8 +1,9 @@
 //! Common memory reclaimers.
 //!
-//! The functions in this module can be passed to [`retire`](crate::Collector::retire)
-//! to free allocated memory or run drop glue. See [the guide](crate#custom-reclaimers)
-//! for details about memory reclamation, and writing custom reclaimers.
+//! The functions in this module can be passed to
+//! [`retire`](crate::Collector::retire) to free allocated memory or run drop
+//! glue. See [the guide](crate#custom-reclaimers) for details about memory
+//! reclamation, and writing custom reclaimers.
 
 use std::ptr;