Merge lock and lockfree crates

Author: jeehoonkang

lock/.gitignore .gitignore

@@ -1,5 +1,5 @@
 [package]
-name = "lockfree"
+name = "kaist-cs431"
 version = "0.1.0"
 authors = ["Jeehoon Kang <jeehoon.kang@kaist.ac.kr>"]
 edition = "2021"

lockfree/Cargo.toml Cargo.toml

@@ -0,0 +1,8 @@
+//! KAIST CS431: Concurrent Programming.
+
+#![warn(missing_docs)]
+#![warn(missing_debug_implementations)]
+#![allow(clippy::result_unit_err)]
+
+pub mod lock;
+pub mod lockfree;

lock/Cargo.toml

@@ -3,22 +3,31 @@ use core::marker::PhantomData;
 use core::mem;
 use core::ops::{Deref, DerefMut};
 
+/// Raw lock interface.
 pub trait RawLock: Default + Send + Sync {
+    /// Raw lock's token type.
     type Token: Clone;
 
+    /// Acquires the raw lock.
     fn lock(&self) -> Self::Token;
 
+    /// Releases the raw lock.
+    ///
     /// # Safety
     ///
     /// `unlock()` should be called with the token given by the corresponding `lock()`.
     unsafe fn unlock(&self, token: Self::Token);
 }
 
+/// Raw lock interface for the try_lock API.
 pub trait RawTryLock: RawLock {
+    /// Tries to acquire the raw lock.
     fn try_lock(&self) -> Result<Self::Token, ()>;
 }
 
+/// A type-safe lock.
 #[repr(C)]
+#[derive(Debug)]
 pub struct Lock<L: RawLock, T> {
     lock: L,
     data: UnsafeCell<T>,
@@ -28,17 +37,20 @@ unsafe impl<L: RawLock, T: Send> Send for Lock<L, T> {}
 unsafe impl<L: RawLock, T: Send> Sync for Lock<L, T> {}
 
 impl<L: RawLock, T> Lock<L, T> {
+    /// Creates a new lock.
     pub fn new(data: T) -> Self {
         Self {
             lock: L::default(),
             data: UnsafeCell::new(data),
         }
     }
 
+    /// Destroys the lock and retrieves the lock-protected value.
     pub fn into_inner(self) -> T {
         self.data.into_inner()
     }
 
+    /// Acquires the lock and dereferences the inner value.
     pub fn lock(&self) -> LockGuard<L, T> {
         let token = self.lock.lock();
         LockGuard {
@@ -50,6 +62,7 @@ impl<L: RawLock, T> Lock<L, T> {
 }
 
 impl<L: RawTryLock, T> Lock<L, T> {
+    /// Tries to acquire the lock and dereferences the inner value.
     pub fn try_lock(&self) -> Result<LockGuard<L, T>, ()> {
         self.lock.try_lock().map(|token| LockGuard {
             lock: self,
@@ -74,6 +87,7 @@ impl<L: RawLock, T> Lock<L, T> {
         &*self.data.get()
     }
 
+    /// Dereferences the inner value.
     pub fn get_mut(&mut self) -> &mut T {
         unsafe { &mut *self.data.get() }
     }
@@ -87,6 +101,8 @@ impl<L: RawLock, T> Lock<L, T> {
     }
 }
 
+/// A guard that holds the lock and dereferences the inner value.
+#[derive(Debug)]
 pub struct LockGuard<'s, L: RawLock, T> {
     lock: &'s Lock<L, T>,
     token: L::Token,
@@ -97,6 +113,7 @@ unsafe impl<'s, L: RawLock, T: Send> Send for LockGuard<'s, L, T> {}
 unsafe impl<'s, L: RawLock, T: Sync> Sync for LockGuard<'s, L, T> {}
 
 impl<'s, L: RawLock, T> LockGuard<'s, L, T> {
+    /// Returns the address of the referenced lock.
     pub fn raw(&mut self) -> usize {
         self.lock as *const _ as usize
     }
@@ -123,6 +140,7 @@ impl<'s, L: RawLock, T> DerefMut for LockGuard<'s, L, T> {
 }
 
 impl<'s, L: RawLock, T> LockGuard<'s, L, T> {
+    /// Transforms a lock guard to an address.
     pub fn into_raw(self) -> usize {
         let ret = self.lock as *const _ as usize;
         mem::forget(self);

lock/src/lib.rs

@@ -8,9 +8,11 @@ struct Node {
     locked: AtomicBool,
 }
 
-#[derive(Clone)]
+#[derive(Debug, Clone)]
 pub struct Token(*const CachePadded<Node>);
 
+/// CLH lock.
+#[derive(Debug)]
 pub struct ClhLock {
     tail: AtomicPtr<CachePadded<Node>>,
 }
@@ -54,10 +56,11 @@ impl RawLock for ClhLock {
 
 #[cfg(test)]
 mod tests {
-    use crate::clhlock::ClhLock;
+    use super::super::api;
+    use super::ClhLock;
 
     #[test]
     fn smoke() {
-        crate::lock::tests::smoke::<ClhLock>();
+        api::tests::smoke::<ClhLock>();
     }
 }

lockfree/.gitignore

@@ -10,9 +10,11 @@ struct Node {
     next: AtomicPtr<CachePadded<Node>>,
 }
 
-#[derive(Clone)]
+#[derive(Debug, Clone)]
 pub struct Token(*mut CachePadded<Node>);
 
+/// An MCS lock.
+#[derive(Debug)]
 pub struct McsLock {
     tail: AtomicPtr<CachePadded<Node>>,
 }
@@ -82,10 +84,11 @@ impl RawLock for McsLock {
 
 #[cfg(test)]
 mod tests {
-    use crate::mcslock::McsLock;
+    use super::super::api;
+    use super::McsLock;
 
     #[test]
     fn smoke() {
-        crate::lock::tests::smoke::<McsLock>();
+        api::tests::smoke::<McsLock>();
     }
 }

lockfree/Cargo.lock

@@ -14,9 +14,11 @@ struct Node {
     _marker: PhantomData<*const ()>,
 }
 
-#[derive(Clone)]
+#[derive(Debug, Clone)]
 pub struct Token(*mut CachePadded<Node>);
 
+/// An MCS parking lock.
+#[derive(Debug)]
 pub struct McsParkingLock {
     tail: AtomicPtr<CachePadded<Node>>,
 }
@@ -89,10 +91,11 @@ impl RawLock for McsParkingLock {
 
 #[cfg(test)]
 mod tests {
-    use crate::mcsparkinglock::McsParkingLock;
+    use super::super::api;
+    use super::mcsparkinglock::McsParkingLock;
 
     #[test]
     fn smoke() {
-        crate::lock::tests::smoke::<McsParkingLock>();
+        api::tests::smoke::<McsParkingLock>();
     }
 }

lockfree/src/lib.rs

@@ -0,0 +1,16 @@
+//! Locks.
+
+mod api;
+mod clhlock;
+mod mcslock;
+mod mcsparkinglock;
+pub mod seqlock;
+mod spinlock;
+mod ticketlock;
+
+pub use api::{Lock, LockGuard, RawLock, RawTryLock};
+pub use clhlock::ClhLock;
+pub use mcslock::McsLock;
+pub use mcsparkinglock::McsParkingLock;
+pub use spinlock::SpinLock;
+pub use ticketlock::TicketLock;