Cleanup comments a bit more.

Author: Lee-Janggun

src/lock/api.rs

@@ -23,27 +23,25 @@ pub unsafe trait RawLock: Default + Send + Sync {
     ///
     /// # Safety
     ///
-    /// `unlock()` should be called with the token given by the corresponding `lock()`.
+    /// - `self` must be a an acquired lock.
+    /// - `token` must be from a [`RawLock::lock`] or [`RawTryLock::unlock`] call to `self`.
     unsafe fn unlock(&self, token: Self::Token);
 }
 
 /// Raw lock interface for the try_lock API.
 ///
 /// # Safety
 ///
-/// Implementations of this trait must ensure that the lock is actually exclusive: a lock can't be
-/// acquired while the lock is already locked.
+/// See [`RawLock`] for safety requirements.
 ///
-/// Also, `try_lock()`, when successful, should return a token that can be used for
-/// `RawLock::unlock`.
+/// Also, [`RawTryLock::try_lock`] should return a token that can be used for [`RawLock::unlock`].
 pub unsafe trait RawTryLock: RawLock {
     /// Tries to acquire the raw lock.
     fn try_lock(&self) -> Result<Self::Token, ()>;
 }
 
 /// A type-safe lock.
-#[repr(C)]
-#[derive(Debug)]
+#[derive(Debug, Default)]
 pub struct Lock<L: RawLock, T> {
     inner: L,
     data: UnsafeCell<T>,
@@ -54,19 +52,6 @@ pub struct Lock<L: RawLock, T> {
 // SATEFY: threads can only access `&mut T` via the lock, and `L` is `Sync`.
 unsafe impl<L: RawLock, T: Send> Sync for Lock<L, T> {}
 
-impl<L: RawLock, T: Default> Default for Lock<L, T>
-where
-    L: Default,
-{
-    // Manual impl for minimum trait bound.
-    fn default() -> Self {
-        Self {
-            inner: L::default(),
-            data: UnsafeCell::default(),
-        }
-    }
-}
-
 impl<L: RawLock, T> Lock<L, T> {
     /// Creates a new lock.
     pub fn new(data: T) -> Self {

src/lock/seqlock.rs

@@ -56,7 +56,7 @@ impl RawSeqLock {
     /// # Safety
     ///
     /// - `self` must be a an acquired writer's lock.
-    /// - `seq` must be the be the value returned from the corresponding of the `write_lock()`.
+    /// - `seq` must be from the most recent [`SeqLock::write_lock`] call on `self`.
     pub unsafe fn write_unlock(&self, seq: usize) {
         self.seq.store(seq.wrapping_add(2), Release);
     }
@@ -88,6 +88,7 @@ impl RawSeqLock {
     /// # Safety
     ///
     /// - `seq` must be even.
+    // No need to require `self` to be a read lock, as the sequence number is enough to validate.
     pub unsafe fn upgrade(&self, seq: usize) -> bool {
         if self
             .seq
@@ -223,7 +224,7 @@ impl<T> Drop for ReadGuard<'_, T> {
     fn drop(&mut self) {
         // HACK(@jeehoonkang): we really need linear type here:
         // https://github.com/rust-lang/rfcs/issues/814
-        panic!("`seqlock::ReadGuard` should never drop. Use `ReadGuard::finish()` instead.");
+        panic!("`seqlock::ReadGuard` should never drop. Use `ReadGuard::finish` instead.");
     }
 }
 

src/lockfree/list.rs

@@ -21,7 +21,7 @@ pub struct Node<K, V> {
 /// Sorted singly linked list.
 ///
 /// Use-after-free will be caused when an unprotected guard is used, as the lifetime of returned
-/// elements are linked to that of the guard in the same way a `Shared<'g,T>` is.
+/// elements are linked to that of the guard in the same way a [`Shared`] is.
 #[derive(Debug)]
 pub struct List<K, V> {
     head: Atomic<Node<K, V>>,

src/lockfree/queue.rs

@@ -66,8 +66,6 @@ impl<T> Queue<T> {
         });
 
         loop {
-            guard.repin();
-
             // We push onto the tail, so we'll start optimistically by looking there first.
             let tail = self.tail.load(Acquire, guard);
 
@@ -97,6 +95,7 @@ impl<T> Queue<T> {
                 }
                 Err(e) => new = e.new,
             }
+            guard.repin();
         }
     }
 
@@ -105,8 +104,6 @@ impl<T> Queue<T> {
     /// Returns `None` if the queue is observed to be empty.
     pub fn try_pop(&self, guard: &mut Guard) -> Option<T> {
         loop {
-            guard.repin();
-
             let head = self.head.load(Acquire, guard);
             let next = unsafe { head.deref() }.next.load(Acquire, guard);
 
@@ -125,7 +122,8 @@ impl<T> Queue<T> {
             // than that of current head. We relase that view to the head with the below CAS,
             // ensuring that the index of the new head is less than or equal to that of the tail.
             //
-            // Note: similar reasoning is done in SC memory regarding index of head and tail.
+            // Note: this reasoning is also done in SC memory regarding index of head and tail,
+            // albeit simpler.
             if self
                 .head
                 .compare_exchange(head, next, Release, Relaxed, guard)
@@ -150,6 +148,7 @@ impl<T> Queue<T> {
 
                 return Some(result);
             }
+            guard.repin();
         }
     }
 }