From c9083c8bc1b93d7e51ff51f53b0fc0280a948eb0 Mon Sep 17 00:00:00 2001 From: Bert Peters Date: Sat, 9 Sep 2023 12:02:52 +0200 Subject: [PATCH 1/2] Clarify feature selection --- src/lib.rs | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 9c958eb..56b7355 100644 --- a/src/lib.rs +++ b/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; From 1fe44d0a0573c90972b49e0db051ea5b18d73b7f Mon Sep 17 00:00:00 2001 From: Bert Peters Date: Mon, 11 Sep 2023 08:27:06 +0200 Subject: [PATCH 2/2] Expand changelog --- CHANGELOG.md | 16 +++++++++++++--- Cargo.toml | 2 +- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e407500..48a3390 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/Cargo.toml b/Cargo.toml index 74db0f7..decc54b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "tracing-mutex" -version = "0.2.1" +version = "0.3.0" authors = ["Bert Peters "] edition = "2021" license = "MIT OR Apache-2.0"