Bump version

21: Prepare for release v0.2.1 r=bertptrs a=bertptrs



Co-authored-by: Bert Peters <bert@bertptrs.nl>

.github/workflows/ci.yml

@@ -2,6 +2,8 @@ on:
   push:
     branches:
       - master
+      - staging
+      - trying
   pull_request:
 
 name: Continuous integration

CHANGELOG.md

@@ -6,9 +6,12 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.1] - 2022-05-23
+
 ### Added
 
 - Build [docs.rs] documentation with all features enabled for completeness.
+- Add support for `std::sync::Condvar`
 
 ### Fixed
 
@@ -64,7 +67,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Initial release.
 
-[Unreleased]: https://github.com/bertptrs/tracing-mutex/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/bertptrs/tracing-mutex/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/bertptrs/tracing-mutex/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/bertptrs/tracing-mutex/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/bertptrs/tracing-mutex/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/bertptrs/tracing-mutex/compare/v0.1.0...v0.1.1

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tracing-mutex"
-version = "0.2.0"
+version = "0.2.1"
 authors = ["Bert Peters <bert@bertptrs.nl>"]
 edition = "2021"
 license = "MIT OR Apache-2.0"

LICENSE-APACHE

@@ -186,7 +186,7 @@ APPENDIX: How to apply the Apache License to your work.
    same "printed page" as the copyright notice for easier
    identification within third-party archives.
 
-Copyright [yyyy] [name of copyright owner]
+Copyright 2022 Bert Peters
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

README.md

@@ -59,12 +59,23 @@ performance penalty in your production environment, this library also offers deb
 when debug assertions are enabled, and to `Mutex` when they are not. Similar helper types are
 available for other synchronization primitives.
 
+### Features
+
+- Dependency-tracking wrappers for all locking primitives
+- Optional opt-out for release mode code
+- Support for primitives from:
+  - `std::sync`
+  - `parking_lot`
+  - Any library that implements the `lock_api` traits
+
 ## Future improvements
 
 - Improve performance in lock tracing
 - Optional logging to make debugging easier
 - Better and configurable error handling when detecting cyclic dependencies
-- Support for other locking libraries, such as `parking_lot`
+- Support for other locking libraries
+- Support for async locking libraries
+- Support for `Send` mutex guards
 
 **Note:** `parking_lot` has already began work on its own deadlock detection mechanism, which works
 in a different way. Both can be complimentary.

bors.toml

@@ -0,0 +1,5 @@
+status = [
+    'Rust project (stable)',
+    'Rust project (beta)',
+    'Documentation build',
+]

src/parkinglot.rs

@@ -194,9 +194,9 @@ impl TracingOnce {
         self.inner.call_once(f);
     }
 
-    /// Performs the given initialization routeine once and only once.
+    /// Performs the given initialization routine once and only once.
     ///
-    /// This method is identical to [`TracingOnce::call_once`] except it ignores poisining.
+    /// This method is identical to [`TracingOnce::call_once`] except it ignores poisoning.
     pub fn call_once_force(&self, f: impl FnOnce(OnceState)) {
         let _borrow = self.id.get_borrowed();
         self.inner.call_once_force(f);

src/stdsync.rs

@@ -16,6 +16,7 @@
 use std::fmt;
 use std::ops::Deref;
 use std::ops::DerefMut;
+use std::sync::Condvar;
 use std::sync::LockResult;
 use std::sync::Mutex;
 use std::sync::MutexGuard;
@@ -27,6 +28,8 @@ use std::sync::RwLockReadGuard;
 use std::sync::RwLockWriteGuard;
 use std::sync::TryLockError;
 use std::sync::TryLockResult;
+use std::sync::WaitTimeoutResult;
+use std::time::Duration;
 
 use crate::BorrowedMutex;
 use crate::LazyMutexId;
@@ -48,6 +51,14 @@ pub type DebugMutexGuard<'a, T> = TracingMutexGuard<'a, T>;
 #[cfg(not(debug_assertions))]
 pub type DebugMutexGuard<'a, T> = MutexGuard<'a, T>;
 
+/// Debug-only `Condvar`
+///
+/// Type alias that accepts the mutex guard emitted from [`DebugMutex`].
+#[cfg(debug_assertions)]
+pub type DebugCondvar = TracingCondvar;
+#[cfg(not(debug_assertions))]
+pub type DebugCondvar = Condvar;
+
 /// Debug-only tracing `RwLock`.
 ///
 /// Type alias that resolves to [`TracingRwLock`] when debug assertions are enabled and to
@@ -214,6 +225,123 @@ impl<'a, T: fmt::Display> fmt::Display for TracingMutexGuard<'a, T> {
     }
 }
 
+/// Wrapper around [`std::sync::Condvar`].
+///
+/// Allows `TracingMutexGuard` to be used with a `Condvar`. Unlike other structs in this module,
+/// this wrapper does not add any additional dependency tracking or other overhead on top of the
+/// primitive it wraps. All dependency tracking happens through the mutexes itself.
+///
+/// # Panics
+///
+/// This struct does not add any panics over the base implementation of `Condvar`, but panics due to
+/// dependency tracking may poison associated mutexes.
+///
+/// # Examples
+///
+/// ```
+/// use std::sync::Arc;
+/// use std::thread;
+///
+/// use tracing_mutex::stdsync::{TracingCondvar, TracingMutex};
+///
+/// let pair = Arc::new((TracingMutex::new(false), TracingCondvar::new()));
+/// let pair2 = Arc::clone(&pair);
+///
+/// // Spawn a thread that will unlock the condvar
+/// thread::spawn(move || {
+///     let (lock, condvar) = &*pair2;
+///     *lock.lock().unwrap() = true;
+///     condvar.notify_one();
+/// });
+///
+/// // Wait until the thread unlocks the condvar
+/// let (lock, condvar) = &*pair;
+/// let guard = lock.lock().unwrap();
+/// let guard = condvar.wait_while(guard, |started| !*started).unwrap();
+///
+/// // Guard should read true now
+/// assert!(*guard);
+/// ```
+#[derive(Debug, Default)]
+pub struct TracingCondvar(Condvar);
+
+impl TracingCondvar {
+    /// Creates a new condition variable which is ready to be waited on and notified.
+    pub fn new() -> Self {
+        Default::default()
+    }
+
+    /// Wrapper for [`std::sync::Condvar::wait`].
+    pub fn wait<'a, T>(
+        &self,
+        guard: TracingMutexGuard<'a, T>,
+    ) -> LockResult<TracingMutexGuard<'a, T>> {
+        let TracingMutexGuard { _mutex, inner } = guard;
+
+        map_lockresult(self.0.wait(inner), |inner| TracingMutexGuard {
+            _mutex,
+            inner,
+        })
+    }
+
+    /// Wrapper for [`std::sync::Condvar::wait_while`].
+    pub fn wait_while<'a, T, F>(
+        &self,
+        guard: TracingMutexGuard<'a, T>,
+        condition: F,
+    ) -> LockResult<TracingMutexGuard<'a, T>>
+    where
+        F: FnMut(&mut T) -> bool,
+    {
+        let TracingMutexGuard { _mutex, inner } = guard;
+
+        map_lockresult(self.0.wait_while(inner, condition), |inner| {
+            TracingMutexGuard { _mutex, inner }
+        })
+    }
+
+    /// Wrapper for [`std::sync::Condvar::wait_timeout`].
+    pub fn wait_timeout<'a, T>(
+        &self,
+        guard: TracingMutexGuard<'a, T>,
+        dur: Duration,
+    ) -> LockResult<(TracingMutexGuard<'a, T>, WaitTimeoutResult)> {
+        let TracingMutexGuard { _mutex, inner } = guard;
+
+        map_lockresult(self.0.wait_timeout(inner, dur), |(inner, result)| {
+            (TracingMutexGuard { _mutex, inner }, result)
+        })
+    }
+
+    /// Wrapper for [`std::sync::Condvar::wait_timeout_while`].
+    pub fn wait_timeout_while<'a, T, F>(
+        &self,
+        guard: TracingMutexGuard<'a, T>,
+        dur: Duration,
+        condition: F,
+    ) -> LockResult<(TracingMutexGuard<'a, T>, WaitTimeoutResult)>
+    where
+        F: FnMut(&mut T) -> bool,
+    {
+        let TracingMutexGuard { _mutex, inner } = guard;
+
+        map_lockresult(
+            self.0.wait_timeout_while(inner, dur, condition),
+            |(inner, result)| (TracingMutexGuard { _mutex, inner }, result),
+        )
+    }
+
+    /// Wrapper for [`std::sync::Condvar::notify_one`].
+    pub fn notify_one(&self) {
+        self.0.notify_one();
+    }
+
+    /// Wrapper for [`std::sync::Condvar::notify_all`].
+    pub fn notify_all(&self) {
+        self.0.notify_all();
+    }
+}
+
 /// Wrapper for [`std::sync::RwLock`].
 #[derive(Debug, Default)]
 pub struct TracingRwLock<T> {