cleanup documentation

Author: ibraheemdev

src/collector.rs

@@ -4,128 +4,135 @@ use crate::{LocalGuard, OwnedGuard};
 use std::fmt;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
-/// Fast, efficient, and robust memory reclamation.
+/// A concurrent garbage collector.
 ///
-/// A `Collector` manages the allocation and retirement of concurrent objects.
+/// A `Collector` manages the access and retirement of concurrent objects
 /// Objects can be safely loaded through *guards*, which can be created using
 /// the [`enter`](Collector::enter) or [`enter_owned`](Collector::enter_owned)
 /// methods.
+///
+/// Every instance of a concurrent data structure should typically own its
+/// `Collector`. This allows the garbage collection of non-`'static` values, as
+/// memory reclamation is guaranteed to run when the `Collector` is dropped.
 pub struct Collector {
+    /// A unique identifier for a collector.
     id: usize,
+
+    /// The underlying raw collector instance.
     pub(crate) raw: raw::Collector,
 }
 
-unsafe impl Send for Collector {}
-unsafe impl Sync for Collector {}
+impl Default for Collector {
+    fn default() -> Self {
+        Self::new()
+    }
+}
 
 impl Collector {
+    /// The default batch size for a new collector.
     const DEFAULT_BATCH_SIZE: usize = 32;
 
     /// Creates a new collector.
     pub fn new() -> Self {
+        // A counter for collector IDs.
         static ID: AtomicUsize = AtomicUsize::new(0);
 
+        // Initialize the `membarrier` module, detecting the presence of
+        // operating-system strong barrier APIs.
         membarrier::detect();
+
         let cpus = std::thread::available_parallelism()
             .map(Into::into)
             .unwrap_or(1);
 
+        // Ensure every batch accumulates at least as many entries
+        // as there are threads on the system.
         let batch_size = cpus.max(Self::DEFAULT_BATCH_SIZE);
 
         Self {
-            raw: raw::Collector::new(cpus, batch_size),
             id: ID.fetch_add(1, Ordering::Relaxed),
+            raw: raw::Collector::new(cpus, batch_size),
         }
     }
 
-    /// Sets the number of values that must be in a batch
-    /// before reclamation is attempted.
-    ///
-    /// Retired values are added to thread-local *batches*
-    /// before starting the reclamation process. After
-    /// `batch_size` is hit, values are moved to separate
-    /// *retirement lists*, where reference counting kicks
-    /// in and batches are eventually reclaimed.
+    /// Sets the number of objects that must be in a batch before reclamation is
+    /// attempted.
     ///
-    /// A larger batch size means that deallocation is done
-    /// less frequently, but reclamation also becomes more
-    /// expensive due to longer retirement lists needing
-    /// to be traversed and freed.
+    /// Retired objects are added to thread-local *batches* before starting the
+    /// reclamation process. After `batch_size` is hit, the objects are moved to
+    /// separate *retirement lists*, where reference counting kicks in and
+    /// batches are eventually reclaimed.
     ///
-    /// Note that batch sizes should generally be larger
-    /// than the number of threads accessing objects.
+    /// A larger batch size amortizes the cost of retirement. However,
+    /// reclamation latency can also grow due to the large number of objects
+    /// needed to be freed. Note that reclamation can not be attempted
+    /// unless the batch contains at least as many objects as the number of
+    /// active threads.
     ///
     /// The default batch size is `32`.
     pub fn batch_size(mut self, batch_size: usize) -> Self {
         self.raw.batch_size = batch_size;
         self
     }
 
-    /// Marks the current thread as active, returning a guard
-    /// that allows protecting loads of concurrent objects. The thread
-    /// will be marked as inactive when the guard is dropped.
+    /// Marks the current thread as active, returning a guard that protects
+    /// loads of concurrent objects for its lifetime. The thread will be
+    /// marked as inactive when the guard is dropped.
     ///
-    /// See [the guide](crate::guide#starting-operations) for an
-    /// introduction to using guards, or the documentation of [`LocalGuard`]
-    /// for more details.
+    /// 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.
     ///
-    /// # Performance
+    /// Note that `enter` is reentrant, and it is legal to create multiple
+    /// guards on the same thread. The thread will stay marked as active
+    /// until the last guard is dropped.
     ///
-    /// Creating and destroying a guard is about the same as locking and
-    /// unlocking an uncontended `Mutex`, performance-wise. Because of this,
-    /// guards should be re-used across multiple operations if possible.
-    /// However, note that holding a guard prevents the reclamation of any
-    /// concurrent objects retired during it's lifetime, so there is a
-    /// tradeoff between performance and memory usage.
+    /// [`Guard::protect`]: crate::Guard::protect
     ///
-    /// # Examples
-    ///
-    /// ```rust
-    /// # use std::sync::atomic::{AtomicPtr, Ordering};
-    /// # let collector = seize::Collector::new();
-    /// use seize::{reclaim, Linked, Guard};
+    /// # Performance
     ///
-    /// let ptr = AtomicPtr::new(collector.link_boxed(1_usize));
+    /// Performance-wise, creating and destroying a `LocalGuard` is about the
+    /// same as locking and unlocking an uncontended `Mutex`. Because of
+    /// this, guards should be reused across multiple operations if
+    /// possible. However, holding a guard prevents the reclamation of any
+    /// concurrent objects retired during its lifetime, so there is
+    /// a tradeoff between performance and memory usage.
     ///
-    /// let guard = collector.enter();
-    /// let value = guard.protect(&ptr, Ordering::Acquire);
-    /// unsafe { assert_eq!(**value, 1) }
-    /// # unsafe { guard.defer_retire(value, reclaim::boxed) };
-    /// ```
-    ///
-    /// Note that `enter` is reentrant, and it is legal to create
-    /// multiple guards on the same thread. The thread will stay
-    /// marked as active until the last guard is dropped:
+    /// # Examples
     ///
     /// ```rust
     /// # use std::sync::atomic::{AtomicPtr, Ordering};
+    /// use seize::Guard;
     /// # let collector = seize::Collector::new();
-    /// use seize::{reclaim, Linked, Guard};
+    ///  
+    /// // An atomic object.
+    /// let ptr = AtomicPtr::new(Box::into_raw(Box::new(1_usize)));
     ///
-    /// let ptr = AtomicPtr::new(collector.link_boxed(1_usize));
+    /// {
+    ///     // Create a guard that is active for this scope.
+    ///     let guard = collector.enter();
     ///
-    /// let guard1 = collector.enter();
-    /// let guard2 = collector.enter();
+    ///     // Read the object using a protected load.
+    ///     let value = guard.protect(&ptr, Ordering::Acquire);
+    ///     unsafe { assert_eq!(*value, 1) }
     ///
-    /// let value = guard2.protect(&ptr, Ordering::Acquire);
-    /// drop(guard1);
-    /// // the first guard is dropped, but `value`
-    /// // is still safe to access as a guard still
-    /// // exists
-    /// unsafe { assert_eq!(**value, 1) }
-    /// # unsafe { guard2.defer_retire(value, reclaim::boxed) };
-    /// drop(guard2) // _now_, the thread is marked as inactive
+    ///     // If there are other thread that may retire the object,
+    ///     // the pointer is no longer valid after the guard is dropped.
+    ///     drop(guard);
+    /// }
+    /// # unsafe { drop(Box::from_raw(ptr.load(Ordering::Relaxed))) };
     /// ```
     #[inline]
     pub fn enter(&self) -> LocalGuard<'_> {
         LocalGuard::enter(self)
     }
 
-    /// Create an owned guard that protects objects for it's lifetime.
+    /// Create an owned guard that protects objects for its lifetime.
     ///
-    /// Unlike local guards created with [`enter`](Collector::enter),
-    /// owned guards are independent of the current thread, allowing
-    /// them to implement `Send`. See the documentation of [`OwnedGuard`]
+    /// Unlike local guards created with [`enter`](Collector::enter), owned
+    /// guards are independent of the current thread, allowing them to
+    /// implement `Send` and `Sync`. See the documentation of [`OwnedGuard`]
     /// for more details.
     #[inline]
     pub fn enter_owned(&self) -> OwnedGuard<'_> {
@@ -137,21 +144,17 @@ impl Collector {
     ///
     /// Note that this method is disconnected from any guards on the current
     /// thread, so the pointer may be reclaimed immediately. Use
-    /// [`Guard::defer_retire`](crate::Guard::defer_retire) if the pointer
-    /// may still be accessed by the current thread.
+    /// [`Guard::defer_retire`](crate::Guard::defer_retire) if the pointer may
+    /// still be accessed by the current thread while the guard is active.
     ///
     /// # Safety
     ///
-    /// The retired object must no longer be accessible to any thread that
+    /// The retired pointer must no longer be accessible to any thread that
     /// enters after it is removed. It also cannot be accessed by the
     /// current thread after `retire` is called.
     ///
-    /// Retiring the same pointer twice can cause **undefined behavior**, even
-    /// if the reclaimer doesn't free memory.
-    ///
-    /// Additionally, the pointer must be valid to access as a [`Link`], per the
-    /// [`AsLink`] trait, and the reclaimer passed to `retire` must
-    /// correctly free values of type `T`.
+    /// Additionally, the pointer must be valid to pass to the provided
+    /// reclaimer, once it is safe to reclaim.
     ///
     /// # Examples
     ///
@@ -161,42 +164,47 @@ impl Collector {
     /// ```
     /// # use std::sync::atomic::{AtomicPtr, Ordering};
     /// # let collector = seize::Collector::new();
-    /// use seize::{reclaim, Linked};
+    /// use seize::reclaim;
     ///
-    /// let ptr = AtomicPtr::new(collector.link_boxed(1_usize));
+    /// // An atomic object.
+    /// let ptr = AtomicPtr::new(Box::into_raw(Box::new(1_usize)));
     ///
+    /// // Create a guard.
     /// let guard = collector.enter();
-    /// // store the new value
-    /// let old = ptr.swap(collector.link_boxed(2_usize), Ordering::Release);
-    /// // reclaim the old value
-    /// // safety: the `swap` above made the old value unreachable for any new threads
+    ///
+    /// // Store a new value.
+    /// let old = ptr.swap(Box::into_raw(Box::new(2_usize)), Ordering::Release);
+    ///
+    /// // Reclaim the old value.
+    /// //
+    /// // Safety: The `swap` above made the old value unreachable for any new threads.
+    /// // Additionally, the old value was allocated with a `Box`, so `reclaim::boxed`
+    /// // is valid.
     /// unsafe { collector.retire(old, reclaim::boxed) };
     /// # unsafe { collector.retire(ptr.load(Ordering::Relaxed), reclaim::boxed) };
     /// ```
     ///
-    /// Alternative, a custom reclaimer function can be used:
+    /// Alternative, a custom reclaimer function can be used.
     ///
     /// ```
-    /// # use seize::{Link, Collector, Linked};
-    /// # let collector = Collector::new();
-    /// let value = collector.link_boxed(1);
+    /// let collector = seize::Collector::new();
     ///
-    /// // safety: the value was never shared
-    /// unsafe {
-    ///     collector.retire(value, |link: *mut Link| unsafe {
-    ///         // safety: the value retired was of type *mut Linked<i32>
-    ///         let ptr: *mut Linked<i32> = Link::cast(link);
+    /// // Allocate a value and immediately retire it.
+    /// let value: *mut usize = Box::into_raw(Box::new(1_usize));
     ///
-    ///         // safety: the value was allocated with `link_boxed`
+    /// // Safety: The value was never shared.
+    /// unsafe {
+    ///     collector.retire(value, |ptr: *mut usize| unsafe {
+    ///         // Safety: The value was allocated with `Box::new`.
     ///         let value = Box::from_raw(ptr);
-    ///         println!("dropping {}", value);
+    ///         println!("Dropping {value}");
     ///         drop(value);
     ///     });
     /// }
     /// ```
     #[inline]
     pub unsafe fn retire<T>(&self, ptr: *mut T, reclaim: unsafe fn(*mut T)) {
-        debug_assert!(!ptr.is_null(), "attempted to retire null pointer");
+        debug_assert!(!ptr.is_null(), "attempted to retire a null pointer");
 
         // Note that `add` doesn't ever actually reclaim the pointer immediately if
         // the current thread is active. Instead, it adds it to the current thread's
@@ -217,8 +225,8 @@ impl Collector {
     /// threads are currently active, whether accessing values that have
     /// been retired or accessing the collector through any type of guard.
     /// This is akin to having a unique reference to the collector. However,
-    /// this method takes a shared reference, as reclaimers to be run by this
-    /// thread are allowed to access the collector recursively.
+    /// this method takes a shared reference, as reclaimers to
+    /// be run by this thread are allowed to access the collector recursively.
     ///
     /// # Notes
     ///
@@ -240,12 +248,6 @@ impl PartialEq for Collector {
     }
 }
 
-impl Default for Collector {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
 impl fmt::Debug for Collector {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("Collector")