Add parking_lot README

Author: sarsko

wrappers/parking_lot/README.md

@@ -0,0 +1,23 @@
+# Shuttle support for `parking_lot`
+
+This folder contains the implementation and wrapper that enables testing of [parking_lot](https://crates.io/crates/parking_lot) applications with Shuttle.
+
+## How to use
+
+To use it, add the following in your Cargo.toml:
+
+```
+[features]
+shuttle = [
+   "parking_lot/shuttle",
+]
+
+[dependencies]
+parking_lot = { package = "shuttle-parking_lot", version = "VERSION_NUMBER" }
+```
+
+The code will then behave as before when the `shuttle` feature flag is not provided, and will run with Shuttle-compatible primitives when the `shuttle` feature flag is provided.
+
+## Limitations
+
+Shuttle's parking_lot functionality is currently limited to a subset of the `Mutex` and `RwLock` primitives. If your project needs functionality which is not currently supported, please file an issue or, better yet, open a PR to contribute the functionality.

wrappers/parking_lot/parking_lot_impl/src/mutex.rs

@@ -1,4 +1,4 @@
-//! An asynchronous reader-writer lock.
+//! An asynchronous mutual exclusion primitive.
 
 // This implementation is adapted from the one in shuttle-tokio
 
@@ -10,7 +10,7 @@ use std::ops::{Deref, DerefMut};
 use std::thread;
 use tracing::trace;
 
-/// An asynchronous semaphore
+/// An asynchronous mutex
 pub struct Mutex<T: ?Sized> {
     semaphore: BatchSemaphore,
     inner: UnsafeCell<T>,
@@ -73,7 +73,7 @@ impl<T: ?Sized> Mutex<T> {
                 unreachable!()
             }
         });
-        trace!("acquired parking_Lot lock {:p}", self);
+        trace!("acquired parking_lot lock {:p}", self);
     }
 
     /// Acquires a mutex, blocking the current thread until it is able to do so.

wrappers/parking_lot/parking_lot_impl/src/rwlock.rs

@@ -32,17 +32,16 @@ impl<T> RwLock<T> {
     /// Creates a new instance of an `RwLock<T>` which is unlocked
     /// and allows a maximum of `max_readers` concurrent readers.
     const fn with_max_readers(value: T, max_readers: usize) -> Self {
-        let sem = BatchSemaphore::const_new(max_readers, Fairness::StrictlyFair);
-        let rwlock = RwLock {
+        RwLock {
             max_readers,
-            sem,
+            sem: BatchSemaphore::const_new(max_readers, Fairness::StrictlyFair),
             inner: UnsafeCell::new(value),
-        };
-        rwlock
+        }
     }
 }
 
 impl<T: ?Sized> RwLock<T> {
+    /// Locks this `RwLock` with shared read access, blocking the current thread
     /// until it can be acquired.
     ///
     /// The calling thread will be blocked until there are no more writers which
@@ -56,7 +55,7 @@ impl<T: ?Sized> RwLock<T> {
     /// once it is dropped.
     #[inline]
     pub fn read(&self) -> RwLockReadGuard<'_, T> {
-        trace!("parking_lot rwlock {:p} acquiring read lock", self);
+        trace!("parking_lot rwlock {:p} read acquiring RwLockReadGuard", self);
         self.sem.acquire_blocking(1).unwrap_or_else(|_| {
             // The semaphore was closed. but, we never explicitly close it, and we have a
             // handle to it through the Arc, which means that this can never happen.
@@ -65,7 +64,7 @@ impl<T: ?Sized> RwLock<T> {
             }
         });
 
-        trace!("parking_lot rwlock {:p} acquired", self);
+        trace!("parking_lot rwlock {:p} read acquired RwLockReadGuard", self);
 
         RwLockReadGuard {
             sem: &self.sem,
@@ -80,6 +79,8 @@ impl<T: ?Sized> RwLock<T> {
     /// Otherwise, an RAII guard is returned which will release read access
     /// when dropped.
     pub fn try_read(&self) -> Option<RwLockReadGuard<'_, T>> {
+        trace!("parking_lot rwlock {:p} try_read acquiring RwlockReadGuard", self);
+
         match self.sem.try_acquire(1) {
             Ok(permit) => permit,
             Err(TryAcquireError::NoPermits) => return None,
@@ -91,7 +92,7 @@ impl<T: ?Sized> RwLock<T> {
             }
         }
 
-        trace!("parking_lot rwlock {:p} try_read acquired ReadGuard", self);
+        trace!("parking_lot rwlock {:p} try_read acquired RwLockReadGuard", self);
 
         Some(RwLockReadGuard {
             sem: &self.sem,
@@ -103,7 +104,7 @@ impl<T: ?Sized> RwLock<T> {
     /// Locks this `RwLock` with exclusive write access, blocking the current
     /// thread until it can be acquired.
     pub fn write(&self) -> RwLockWriteGuard<'_, T> {
-        trace!("parking_lot rwlock {:p} acquiring write lock", self);
+        trace!("parking_lot rwlock {:p} write acquiring RwLockWriteGuard", self);
         self.sem.acquire_blocking(1).unwrap_or_else(|_| {
             // The semaphore was closed. but, we never explicitly close it, and we have a
             // handle to it through the Arc, which means that this can never happen.
@@ -112,7 +113,7 @@ impl<T: ?Sized> RwLock<T> {
             }
         });
 
-        trace!("parking_lot rwlock {:p} acquired WriteGuard", self);
+        trace!("parking_lot rwlock {:p} write acquired RwLockWriteGuard", self);
         RwLockWriteGuard {
             permits_acquired: self.max_readers,
             data: self.inner.get(),
@@ -127,7 +128,7 @@ impl<T: ?Sized> RwLock<T> {
     /// Otherwise, an RAII guard is returned which will release write access
     /// when dropped.
     pub fn try_write(&self) -> Option<RwLockWriteGuard<'_, T>> {
-        tracing::trace!("parking_lot rwlock {:p} try_write acquired WriteGuard", self,);
+        tracing::trace!("parking_lot rwlock {:p} try_write acquiring RwLockWriteGuard", self);
 
         match self.sem.try_acquire(1) {
             Ok(permit) => permit,
@@ -140,7 +141,7 @@ impl<T: ?Sized> RwLock<T> {
             }
         }
 
-        tracing::trace!("parking_lot rwlock {:p} try_write acquired WriteGuard", self,);
+        tracing::trace!("parking_lot rwlock {:p} try_write acquired RwLockWriteGuard", self);
 
         Some(RwLockWriteGuard {
             permits_acquired: self.max_readers,
@@ -261,7 +262,10 @@ impl<'a, T: ?Sized> RwLockWriteGuard<'a, T> {
         let RwLockWriteGuard { sem, data, .. } = self;
         let to_release = self.permits_acquired - 1;
 
-        tracing::trace!("rwlock {:p} downgrading to ReadGuard", &self);
+        tracing::trace!(
+            "parking_lot rwlock {:p} downgrade RwLockWriteGuard to RwLockReadGuard",
+            &self
+        );
 
         // NB: Forget to avoid drop impl from being called.
         std::mem::forget(self);

wrappers/tokio/impls/tokio/inner/src/sync/mutex.rs

@@ -9,7 +9,7 @@ use std::sync::Arc;
 use std::thread;
 use tracing::trace;
 
-/// An asynchronous semaphore
+/// An asynchronous mutex
 pub struct Mutex<T: ?Sized> {
     semaphore: BatchSemaphore,
     inner: UnsafeCell<T>,