Merge #33

33: Prepare for release 0.3.0 r=bertptrs a=bertptrs

Double check

- [x] documentation
- [x] changelog
- [x] tests


Co-authored-by: Bert Peters <[email protected]>

CHANGELOG.md

@@ -6,17 +6,26 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0] - 2023-09-09
+
 ### Added
 
 - The minimum supported Rust version is now defined as 1.70. Previously it was undefined.
 - Wrappers for `std::sync` primitives can now be `const` constructed.
 - Add support for `std::sync::OnceLock`
-- Added backtraces of mutex allocations to the cycle report. 
+- Added backtraces of mutex allocations to the cycle report. Capturing backtraces does incur some
+  overhead, this can be mitigated by disabling the `backtraces` feature which is enabled by default.
 
 ### Breaking
 
 - Update [`parking_lot`][parking_lot] dependency to `0.12`.
-- Restructured the crate to reduce typename verbosity. For details, see: #25.
+- Restructured the crate to reduce typename verbosity. Wrapper names now match the name of the
+  primitive they wrap. Specific always/debug tracing versions have now moved to separate modules.
+  For example, `tracing_mutex::stdsync::TracingMutex` is now
+  `tracing_mutex::stdsync::tracing::Mutex`, and `tracing_mutex::stdsync::DebugMutex` is now called
+  `tracing_mutex::stdsync::Mutex`. This hopefully reduces the visual noise while reading code that
+  uses this in practice. Unwrapped primitives are reexported under `tracing_mutex::stdsync::raw` for
+  convenience.
 
 ### Fixed
 
@@ -84,7 +93,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.1...HEAD
+[Unreleased]: https://github.com/bertptrs/tracing-mutex/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/bertptrs/tracing-mutex/compare/v0.2.1...v0.3.0
 [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

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tracing-mutex"
-version = "0.2.1"
+version = "0.3.0"
 authors = ["Bert Peters <[email protected]>"]
 edition = "2021"
 license = "MIT OR Apache-2.0"

src/lib.rs

@@ -18,8 +18,23 @@
 //! # Structure
 //!
 //! Each module in this crate exposes wrappers for a specific base-mutex with dependency trakcing
-//! added. For now, that is limited to [`stdsync`] which provides wrappers for the base locks in the
-//! standard library. More back-ends may be added as features in the future.
+//! added. This includes [`stdsync`] which provides wrappers for the base locks in the standard
+//! library, and more depending on enabled compile-time features. More back-ends may be added as
+//! features in the future.
+//!
+//! # Feature flags
+//!
+//! `tracing-mutex` uses feature flags to reduce the impact of this crate on both your compile time
+//! and runtime overhead. Below are the available flags. Modules are annotated with the features
+//! they require.
+//!
+//! - `backtraces`: Enables capturing backtraces of mutex dependencies, to make it easier to
+//!   determine what sequence of events would trigger a deadlock. This is enabled by default, but if
+//!   the performance overhead is unaccceptable, it can be disabled by disabling default features.
+//!
+//! - `lockapi`: Enables the wrapper lock for [`lock_api`][lock_api] locks
+//!
+//! - `parkinglot`: Enables wrapper types for [`parking_lot`][parking_lot] mutexes
 //!
 //! # Performance considerations
 //!
@@ -44,7 +59,13 @@
 //! (such as [`stdsync::Mutex`]) which evaluate to a tracing mutex when debug assertions are
 //! enabled, and to the underlying mutex when they're not.
 //!
+//! For ease of debugging, this crate will, by default, capture a backtrace when establishing a new
+//! dependency between two mutexes. This has an additional overhead of over 60%. If this additional
+//! debugging aid is not required, it can be disabled by disabling default features.
+//!
 //! [paper]: https://whileydave.com/publications/pk07_jea/
+//! [lock_api]: https://docs.rs/lock_api/0.4/lock_api/index.html
+//! [parking_lot]: https://docs.rs/parking_lot/0.12.1/parking_lot/
 #![cfg_attr(docsrs, feature(doc_cfg))]
 use std::cell::RefCell;
 use std::fmt;