reformat comments

Author: ibraheemdev

rustfmt.toml

@@ -1,2 +1,2 @@
 wrap_comments = true
-comment_width = 90
+comment_width = 80

src/collector.rs

@@ -12,8 +12,8 @@ use std::sync::atomic::{AtomicUsize, Ordering};
 /// 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.
+/// `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,
@@ -37,8 +37,8 @@ impl Collector {
         // A counter for collector IDs.
         static ID: AtomicUsize = AtomicUsize::new(0);
 
-        // Initialize the `membarrier` module, detecting the presence
-        // of operating-system strong barrier APIs.
+        // Initialize the `membarrier` module, detecting the presence of
+        // operating-system strong barrier APIs.
         membarrier::detect();
 
         let cpus = std::thread::available_parallelism()
@@ -55,48 +55,47 @@ impl Collector {
         }
     }
 
-    /// Sets the number of objects that must be in a batch
-    /// before reclamation is attempted.
+    /// Sets the number of objects that must be in a batch before reclamation is
+    /// attempted.
     ///
-    /// 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.
+    /// 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.
     ///
-    /// 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.
+    /// 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 protects loads of concurrent objects for its lifetime.
-    /// 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.
     ///
-    /// Note that loads of objects that may be retired must be paired with
-    /// the [`seize::protect`](crate::protect) function to be protected.
-    /// 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 paired with the
+    /// [`seize::protect`](crate::protect) function to be protected. 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 guards
-    /// on the same thread. The thread will stay marked as active until the last
-    /// guard is dropped.
+    /// 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.
     ///
     /// # Performance
     ///
-    /// 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.
+    /// 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.
     ///
     /// # Examples
     ///
@@ -129,10 +128,10 @@ impl Collector {
 
     /// 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` and `Sync`. See the documentation of
-    /// [`OwnedGuard`] for more details.
+    /// 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<'_> {
         OwnedGuard::enter(self)
@@ -143,8 +142,8 @@ 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 while the guard is active.
+    /// [`Guard::defer_retire`](crate::Guard::defer_retire) if the pointer may
+    /// still be accessed by the current thread while the guard is active.
     ///
     /// # Safety
     ///
@@ -224,13 +223,14 @@ 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
     ///
     /// Note that if reclaimers initialize guards across threads, or initialize
-    /// owned guards, objects retired through those guards may not be reclaimed.
+    /// owned guards, objects retired through those guards may not be
+    /// reclaimed.
     pub unsafe fn reclaim_all(&self) {
         unsafe { self.raw.reclaim_all() };
     }
@@ -246,19 +246,19 @@ impl PartialEq for Collector {
     }
 }
 
-/// Strengthens an ordering to that necessary to protect the load of a concurrent
-/// object.
+/// Strengthens an ordering to that necessary to protect the load of a
+/// concurrent object.
 ///
 /// If this function is paired with the load of an object while a guard is
-/// active on the current thread, the value of that object is guaranteed to
-/// stay valid until the guard is dropped or the object is retired by the
-/// current thread. Importantly, if another thread retires this object, it will
-/// not be reclaimed for the lifetime of the guard.
+/// active on the current thread, the value of that object is guaranteed to stay
+/// valid until the guard is dropped or the object is retired by the current
+/// thread. Importantly, if another thread retires this object, it will not be
+/// reclaimed for the lifetime of the guard.
 ///
 /// Although this function returns an ordering, it must be *paired* with a given
 /// load for that load to be considered protected. That is, this function must
-/// execute before that load. This can be achieved by simply calling this function
-/// directly on the load ordering:
+/// execute before that load. This can be achieved by simply calling this
+/// function directly on the load ordering:
 ///
 /// ```ignore
 /// let value = ptr.load(seize::protect(Ordering::Acquire));
@@ -270,11 +270,11 @@ impl PartialEq for Collector {
 /// let value = ptr.swap(ptr::null_mut(), seize::protect(Ordering::AcqRel));
 /// ```
 ///
-/// 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. However,
+/// 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. However,
 /// managing the lifetime of any references is up to the caller. Data structures
-/// that return shared references should ensure that the lifetime of the references
-/// are tied to the lifetime of a guard.
+/// that return shared references should ensure that the lifetime of the
+/// references are tied to the lifetime of a guard.
 pub fn protect(ordering: Ordering) -> Ordering {
     raw::Collector::protect(ordering)
 }

src/guard.rs

@@ -6,50 +6,50 @@ use crate::Collector;
 
 /// A guard that enables protected loads of concurrent objects.
 ///
-/// This trait provides common functionality implemented by [`LocalGuard`]
-/// and [`OwnedGuard`]. See [the guide](crate::guide#starting-operations)
-/// for an introduction to using guards.
+/// This trait provides common functionality implemented by [`LocalGuard`] and
+/// [`OwnedGuard`]. See [the guide](crate::guide#starting-operations) for an
+/// introduction to using guards.
 pub trait Guard {
     /// Refreshes the guard.
     ///
-    /// Calling this method is similar to dropping and immediately
-    /// creating a new guard. The current thread remains active, but any
-    /// pointers that were previously protected may be reclaimed.
+    /// Calling this method is similar to dropping and immediately creating a
+    /// new guard. The current thread remains active, but any pointers that
+    /// were previously protected may be reclaimed.
     ///
     /// # Safety
     ///
-    /// This method is not marked as `unsafe`, but will affect
-    /// the validity of pointers loaded using [`seize::protect`](crate::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`.
+    /// This method is not marked as `unsafe`, but will affect the validity of
+    /// pointers loaded using [`seize::protect`](crate::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`.
     fn refresh(&mut self);
 
     /// Flush any retired values in the local batch.
     ///
-    /// This method flushes any values from the current thread's local
-    /// batch, starting the reclamation process. Note that no memory
-    /// can be reclaimed while this guard is active, but calling `flush`
-    /// may allow memory to be reclaimed more quickly after the guard is
-    /// dropped.
+    /// This method flushes any values from the current thread's local batch,
+    /// starting the reclamation process. Note that no memory can be
+    /// reclaimed while this guard is active, but calling `flush` may allow
+    /// memory to be reclaimed more quickly after the guard is dropped.
     ///
-    /// Note that the batch must contain at least as many objects as the
-    /// number of currently active threads for a flush to be performed.
-    /// See [`Collector::batch_size`] for details about batch sizes.
+    /// Note that the batch must contain at least as many objects as the number
+    /// of currently active threads for a flush to be performed. See
+    /// [`Collector::batch_size`] for details about batch sizes.
     fn flush(&self);
 
     /// Returns the collector this guard was created from.
     fn collector(&self) -> &Collector;
 
     /// Returns a numeric identifier for the current thread.
     ///
-    /// Guards rely on thread-local state, including thread IDs. This method
-    /// is 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
+    /// Guards rely on thread-local state, including thread IDs. This method is
+    /// 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;
 
-    /// Retires a value, running `reclaim` when no threads hold a reference to it.
+    /// Retires a value, running `reclaim` when no threads hold a reference to
+    /// it.
     ///
     /// This method delays reclamation until the guard is dropped, as opposed to
     /// [`Collector::retire`], which may reclaim objects immediately.
@@ -95,8 +95,8 @@ impl LocalGuard<'_> {
         // Safety: `thread` is the current thread.
         let reservation = unsafe { collector.raw.reservation(thread) };
 
-        // Calls to `enter` may be reentrant, so we need to keep track of the number
-        // of active guards for the current thread.
+        // Calls to `enter` may be reentrant, so we need to keep track of the number of
+        // active guards for the current thread.
         let guards = reservation.guards.get();
         reservation.guards.set(guards + 1);
 
@@ -131,8 +131,8 @@ impl Guard for LocalGuard<'_> {
     /// Flush any retired values in the local batch.
     #[inline]
     fn flush(&self) {
-        // Note that this does not actually retire any values, it just attempts
-        // to add the batch to any active reservations lists, including ours.
+        // Note that this does not actually retire any values, it just attempts to add
+        // the batch to any active reservations lists, including ours.
         //
         // Safety: `self.thread` is the current thread.
         unsafe { self.collector.raw.try_retire_batch(self.thread) }
@@ -150,7 +150,8 @@ impl Guard for LocalGuard<'_> {
         self.thread.id
     }
 
-    /// Retires a value, running `reclaim` when no threads hold a reference to it.
+    /// Retires a value, running `reclaim` when no threads hold a reference to
+    /// it.
     #[inline]
     unsafe fn defer_retire<T>(&self, ptr: *mut T, reclaim: unsafe fn(*mut T)) {
         // Safety:
@@ -187,10 +188,11 @@ impl fmt::Debug for LocalGuard<'_> {
 /// thread.
 ///
 /// Unlike [`LocalGuard`], an owned guard is independent of the current thread,
-/// allowing it to implement `Send` and `Sync`. This is useful for holding guards
-/// across `.await` points in work-stealing schedulers, where execution may be resumed
-/// on a different thread than started on. However, owned guards are more expensive to
-/// create and destroy, so should be avoided if cross-thread usage is not required.
+/// allowing it to implement `Send` and `Sync`. This is useful for holding
+/// guards across `.await` points in work-stealing schedulers, where execution
+/// may be resumed on a different thread than started on. However, owned guards
+/// are more expensive to create and destroy, so should be avoided if
+/// cross-thread usage is not required.
 ///
 /// Most of the functionality provided by this type is through the [`Guard`]
 /// trait.
@@ -205,11 +207,12 @@ pub struct OwnedGuard<'a> {
     reservation: *const Reservation,
 }
 
-// Safety: All shared methods on `OwnedGuard` that access shared memory are synchronized
-// with locks.
+// Safety: All shared methods on `OwnedGuard` that access shared memory are
+// synchronized with locks.
 unsafe impl Sync for OwnedGuard<'_> {}
 
-// Safety: `OwnedGuard` owns its thread slot and is not tied to any thread-locals.
+// Safety: `OwnedGuard` owns its thread slot and is not tied to any
+// thread-locals.
 unsafe impl Send for OwnedGuard<'_> {}
 
 impl OwnedGuard<'_> {
@@ -247,8 +250,8 @@ impl Guard for OwnedGuard<'_> {
         // Safety: `self.reservation` is owned by the current thread.
         let reservation = unsafe { &*self.reservation };
         let _lock = reservation.lock.lock().unwrap();
-        // Note that this does not actually retire any values, it just attempts
-        // to add the batch to any active reservations lists, including ours.
+        // Note that this does not actually retire any values, it just attempts to add
+        // the batch to any active reservations lists, including ours.
         //
         // Safety: We hold the lock and so have unique access to the batch.
         unsafe { self.collector.raw.try_retire_batch(self.thread) }
@@ -263,14 +266,15 @@ impl Guard for OwnedGuard<'_> {
     /// Returns a numeric identifier for the current thread.
     #[inline]
     fn thread_id(&self) -> usize {
-        // We can't return the ID of our thread slot because `OwnedGuard`
-        // is `Send` so the ID is not uniquely tied to the current thread.
-        // We also can't return the OS thread ID because it might conflict
-        // with our thread IDs, so we have to get/create the current thread.
+        // We can't return the ID of our thread slot because `OwnedGuard` is `Send` so
+        // the ID is not uniquely tied to the current thread. We also can't
+        // return the OS thread ID because it might conflict with our thread
+        // IDs, so we have to get/create the current thread.
         Thread::current().id
     }
 
-    /// Retires a value, running `reclaim` when no threads hold a reference to it.
+    /// Retires a value, running `reclaim` when no threads hold a reference to
+    /// it.
     #[inline]
     unsafe fn defer_retire<T>(&self, ptr: *mut T, reclaim: unsafe fn(*mut T)) {
         // Safety: `self.reservation` is owned by the current thread.