More unit tests

Author: botahamec

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "happylock"
-version = "0.4.1"
+version = "0.4.2"
 authors = ["Mica White <botahamec@outlook.com>"]
 edition = "2021"
 rust-version = "1.82"

happylock.md

@@ -2,6 +2,7 @@
 marp: true
 theme: gaia
 class: invert
+author: Mica White
 ---
 
 <!-- _class: lead invert -->
@@ -112,7 +113,7 @@ use happylock::{ThreadKey, Mutex};
 
 fn main() {
     // each thread can only have one thread key (that's why we unwrap)
-    // ThreadKey is not Send, Sync, Copy, or Clone
+    // ThreadKey is not Send, Copy, or Clone
     let key = ThreadKey::get().unwrap();
 
     let mutex = Mutex::new(10);
@@ -153,6 +154,8 @@ fn main() {
 }
 ```
 
+This `LockCollection` can be implemented simply by releasing the currently acquired locks and retrying on failure
+
 ---
 
 ## The Lockable API
@@ -266,7 +269,17 @@ Time Complexity: O(nlogn)
 
 ## Problem: Live-locking
 
-Although this library is able to successfully prevent deadlocks, livelocks may still be an issue. Imagine thread 1 gets resource 1, thread 2 gets resource 2, thread 1 realizes it can't get resource 2, thread 2 realizes it can't get resource 1, thread 1 drops resource 1, thread 2 drops resource 2, and then repeat forever. In practice, this situation probably wouldn't last forever. But it would be nice if this could be prevented somehow.
+Although this library is able to successfully prevent deadlocks, livelocks may still be an issue.
+
+1. Thread 1 locks mutex 1
+2. Thread 2 locks mutex 2
+3. Thread 1 tries to lock mutex 2 and fails
+4. Thread 2 tries to lock mutex 1 and fails
+5. Thread 1 releases mutex 1
+6. Thread 2 releases mutex 2
+7. Repeat
+
+This pattern will probably end eventually, but we should really avoid it, for performance reasons.
 
 ---
 
@@ -384,8 +397,8 @@ This is what we were trying to avoid earlier
 This is what I used in HappyLock 0.1:
 
 ```rust
-struct ReadLock<'a, T(&'a RwLock<T>);
-struct WriteLock<'a, T(&'a RwLock<T>);
+struct ReadLock<'a, T>(&'a RwLock<T>);
+struct WriteLock<'a, T>(&'a RwLock<T>);
 ```
 
 **Problem:** This can't be used inside of an `OwnedLockCollection`
@@ -413,7 +426,7 @@ unsafe trait Lockable {
 
 ---
 
-## Not every lock can be read doe
+## Not every lock can be read tho
 
 ```rust
 // This trait is used to indicate that reading is actually useful
@@ -432,25 +445,6 @@ impl<L: Sharable> OwnedLockable<L> {
 
 ---
 
-## Missing Features
-
-- `Condvar`/`Barrier`
-- We probably don't need `OnceLock` or `LazyLock`
-- Standard Library Backend
-- Mutex poisoning
-- Support for `no_std`
-- Convenience methods: `lock_swap`, `lock_set`?
-- `try_lock_swap` doesn't need a `ThreadKey`
-- Going further: `LockCell` API (preemptive allocation)
-
----
-
-<!--_class: invert lead -->
-
-## What's next?
-
----
-
 ## Poisoning
 
 ```rust
@@ -473,50 +467,55 @@ Allows: `Poisonable<LockCollection>` and `LockCollection<Poisonable>`
 
 ---
 
-## OS Locks
+# `LockableGetMut` and `LockableIntoInner`
 
-- Using `parking_lot` makes the binary size much larger
-- Unfortunately, it's impossible to implement `RawLock` on the standard library lock primitives
-- Creating a new crate based on a fork of the standard library is hard
-- Solution: create a new library (`sys_locks`), which exposes raw locks from the operating system
-- This is more complicated than you might think
-
----
+```rust
+fn Mutex::<T>::get_mut(&mut self) -> &mut T // already exists in std
+// this is safe because a mutable reference means nobody else can access the lock
 
-## Expanding Cyclic Wait
+trait LockableGetMut: Lockable {
+    type Inner<'a>;
 
-> ... sometimes you need to lock an object to read its value and determine what should be locked next... is there a way to address it?
+    fn get_mut(&mut self) -> Self::Inner<'_>
+}
 
-```rust
-let guard = m1.lock(key);
-if *guard == true {
-    let key = Mutex::unlock(m);
-    let data = [&m1, &m2];
-    let collection = LockCollection::try_new(data).unwrap();
-    let guard = collection.lock(key);
+impl<A: LockableGetMut, B: LockableGetMut> LockableGetMut for (A, B) {
+    type Inner = (A::Inner<'a>, B::Inner<'b>);
 
-    // m1 might no longer be true here...
+    fn get_mut(&mut self) -> Self::Inner<'_> {
+        (self.0.get_mut(), self.1.get_mut())
+    }
 }
 ```
 
 ---
 
-## What I Really Want
+## Missing Features
 
-```txt
-ordered locks: m1, m2, m3
+- `Condvar`/`Barrier`
+- `OnceLock` or `LazyLock`
+- Standard Library Backend
+- Support for `no_std`
+- Convenience methods: `lock_swap`, `lock_set`?
+- `try_lock_swap` doesn't need a `ThreadKey`
+- Going further: `LockCell` API (preemptive allocation)
 
-if m1 is true
-    lock m2 and keep m1 locked
-else
-    skip m2 and lock m3
-```
+---
 
-We can specify lock orders using `OwnedLockCollection`
+<!--_class: invert lead -->
+
+## What's next?
+
+---
 
-Then we need an iterator over the collection to keep that ordering
 
-This will be hard to do with tuples (but might not be impossible)
+## OS Locks
+
+- Using `parking_lot` makes the binary size much larger
+- Unfortunately, it's impossible to implement `RawLock` on the standard library lock primitives
+- Creating a new crate based on a fork of the standard library is hard
+- Solution: create a new library (`sys_locks`), which exposes raw locks from the operating system
+- This is more complicated than you might think
 
 ---
 
@@ -617,6 +616,106 @@ A `Readonly` collection cannot be exclusively locked.
 - LazyLock and OnceLock
   - can these even deadlock?
 
+---
+## Expanding Cyclic Wait
+
+> ... sometimes you need to lock an object to read its value and determine what should be locked next... is there a way to address it?
+
+```rust
+let guard = m1.lock(key);
+if *guard == true {
+    let key = Mutex::unlock(m);
+    let data = [&m1, &m2];
+    let collection = LockCollection::try_new(data).unwrap();
+    let guard = collection.lock(key);
+
+    // m1 might no longer be true here...
+}
+```
+
+---
+
+## What I Really Want
+
+```txt
+ordered locks: m1, m2, m3
+
+if m1 is true
+    lock m2 and keep m1 locked
+else
+    skip m2 and lock m3
+```
+
+We can specify lock orders using `OwnedLockCollection`
+
+Then we need an iterator over the collection to keep that ordering
+
+This will be hard to do with tuples (but is not be impossible)
+
+---
+
+## Something like this
+
+```rust
+let key = ThreadKey::get().unwrap();
+let collection: OwnedLockCollection<(Vec<i32>, Vec<String>);
+let iterator: LockIterator<(Vec<i32>, Vec<String>)> = collection.locking_iter(key);
+let (guard, next: LockIterator<Vec<String>>) = collection.next();
+
+unsafe trait IntoLockIterator: Lockable {
+    type Next: Lockable;
+    type Rest;
+
+    unsafe fn next(&self) -> Self::Next; // must be called before `rest`
+    fn rest(&self) -> Self::Rest;
+}
+
+unsafe impl<A: Lockable, B: Lockable> IntoLockIterator for (A, B) {
+    type Next = A;
+    type Rest = B;
+
+    unsafe fn next(&self) -> Self::Next { self.0 }
+
+    unsafe fn rest(&self) -> Self::Rest { self.1 }
+}
+```
+
+---
+
+## Here are the helper functions we'll need
+
+```rust
+struct LockIterator<Current: IntoLockIterator, Rest: IntoLockIterator = ()>;
+
+impl<Current, Rest> LockIterator<Current, Rest> {
+    // locks the next item and moves on
+    fn next(self) -> (Current::Next::Guard, LockIterator<Current::Rest>);
+
+    // moves on without locking anything
+    fn skip(self) -> LockIterator<Current::Rest>;
+
+    // steps into the next item, allowing parts of it to be locked
+    // For example, if i have LockIterator<(Vec<String>, Vec<i32>)>, but only
+    // want to lock parts of the first Vec, then I can step into it,
+    // locking what i need to, and then exit.
+    // This is the first use of LockIterator's second generic parameter
+    fn step_into(self) -> LockIterator<Current::Next, Rest=Current::Rest>;
+
+    // Once I'm done with my step_into, I can leave and move on
+    fn exit(self) -> LockIterator<Rest>;
+}
+```
+
+---
+
+## A Quick Problem with this Approach
+
+We're going to be returning a lot of guards.
+
+The `ThreadKey` is held by the `LockIterator`.
+
+**How do we ensure that the `ThreadKey` is not used again until all of the guards are dropped?**
+
 ---
 
 <!--_class: invert lead -->

package-lock.json

@@ -0,0 +1 @@
+{}

package.json

@@ -154,6 +154,7 @@ impl<T, L: AsRef<T>> AsRef<T> for BoxedLockCollection<L> {
 	}
 }
 
+#[mutants::skip]
 impl<L: Debug> Debug for BoxedLockCollection<L> {
 	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
 		f.debug_struct(stringify!(BoxedLockCollection))

src/collection/boxed.rs

@@ -6,32 +6,38 @@ use crate::key::Keyable;
 
 use super::LockGuard;
 
+#[mutants::skip] // it's hard to get two guards safely
 impl<Guard: PartialEq, Key: Keyable> PartialEq for LockGuard<'_, Guard, Key> {
 	fn eq(&self, other: &Self) -> bool {
 		self.guard.eq(&other.guard)
 	}
 }
 
+#[mutants::skip] // it's hard to get two guards safely
 impl<Guard: PartialOrd, Key: Keyable> PartialOrd for LockGuard<'_, Guard, Key> {
 	fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
 		self.guard.partial_cmp(&other.guard)
 	}
 }
 
+#[mutants::skip] // it's hard to get two guards safely
 impl<Guard: Eq, Key: Keyable> Eq for LockGuard<'_, Guard, Key> {}
 
+#[mutants::skip] // it's hard to get two guards safely
 impl<Guard: Ord, Key: Keyable> Ord for LockGuard<'_, Guard, Key> {
 	fn cmp(&self, other: &Self) -> std::cmp::Ordering {
 		self.guard.cmp(&other.guard)
 	}
 }
 
+#[mutants::skip] // hashing involves RNG and is hard to test
 impl<Guard: Hash, Key: Keyable> Hash for LockGuard<'_, Guard, Key> {
 	fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
 		self.guard.hash(state)
 	}
 }
 
+#[mutants::skip]
 impl<Guard: Debug, Key: Keyable> Debug for LockGuard<'_, Guard, Key> {
 	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
 		Debug::fmt(&**self, f)

src/collection/guard.rs

@@ -7,6 +7,7 @@ use crate::Keyable;
 
 use super::{utils, LockGuard, OwnedLockCollection};
 
+#[mutants::skip] // it's hard to test individual locks in an OwnedLockCollection
 fn get_locks<L: Lockable>(data: &L) -> Vec<&dyn RawLock> {
 	let mut locks = Vec::new();
 	data.get_ptrs(&mut locks);
@@ -61,6 +62,7 @@ unsafe impl<L: Lockable> Lockable for OwnedLockCollection<L> {
 	where
 		Self: 'g;
 
+	#[mutants::skip] // It's hard to test lkocks in an OwnedLockCollection, because they're owned
 	fn get_ptrs<'a>(&'a self, ptrs: &mut Vec<&'a dyn RawLock>) {
 		self.data.get_ptrs(ptrs)
 	}

src/collection/owned.rs

@@ -108,6 +108,7 @@ impl<T, L: AsRef<T>> AsRef<T> for RefLockCollection<'_, L> {
 	}
 }
 
+#[mutants::skip]
 impl<L: Debug> Debug for RefLockCollection<'_, L> {
 	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
 		f.debug_struct(stringify!(RefLockCollection))

src/collection/ref.rs

@@ -43,6 +43,7 @@ unsafe impl Keyable for &mut ThreadKey {}
 // Safety: a &ThreadKey is useless by design.
 unsafe impl Sync for ThreadKey {}
 
+#[mutants::skip]
 impl Debug for ThreadKey {
 	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 		write!(f, "ThreadKey")