bert/tracing-mutex
1
0
Fork 0
mirror of https://github.com/bertptrs/tracing-mutex.git synced 2025-12-25 20:50:32 +01:00
Code Issues Projects Releases Wiki Activity

Compare commits

base: bert:v0.2.1
Branches Tags
bert:master bert:dependabot/github_actions/dtolnay/rust-toolchain-1.100
bert:v0.3.2 bert:v0.3.1 bert:v0.3.0 bert:v0.2.1 bert:v0.2.0 bert:v0.1.2 bert:v0.1.1 bert:v0.1.0
...
compare: bert:master
Branches Tags
bert:dependabot/github_actions/dtolnay/rust-toolchain-1.100 bert:master
bert:v0.3.2 bert:v0.3.1 bert:v0.3.0 bert:v0.2.1 bert:v0.2.0 bert:v0.1.2 bert:v0.1.1 bert:v0.1.0

68 Commits
v0.2.1 ... master

Author SHA1 Message Date
dependabot[bot]
476e249be3 Bump actions/checkout from 5 to 6 
Bumps [actions/checkout](https://github.com/actions/checkout) from 5 to 6.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v5...v6)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '6'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
 2025-11-27 09:32:39 +01:00
Bert Peters
a05739810d Enforce Item granularity 2025-11-27 09:30:03 +01:00
Bert Peters
ed6676d345 Avoid broken docs in dependency 2025-11-27 09:30:03 +01:00
Bert Peters
003f6a02d7 Prepare for release v0.3.2 
This is a bugfix release and contains no new functionality.
 2025-09-04 18:49:51 +02:00
Bert Peters
d72827a74d Add missing fmt impls 2025-09-03 09:02:33 +02:00
Bert Peters
df0f28b386 Relax sized bounds for std::sync wrappers 2025-09-03 09:02:33 +02:00
dependabot[bot]
8dec9db799 Bump actions/checkout from 4 to 5 
Bumps [actions/checkout](https://github.com/actions/checkout) from 4 to 5.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v4...v5)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '5'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
 2025-08-18 12:58:16 +02:00
Bert Peters
28d67e871c Make elided lifetimes explicit 2025-08-18 12:51:08 +02:00
Bert Peters
90843416e3 Missing section header 2025-05-13 16:09:39 +02:00
Bert Peters
522ee3ffe5 Prepare release v0.3.1 2025-05-13 16:04:47 +02:00
Bert Peters
1791ef5243 Update changelog 2025-05-13 15:57:30 +02:00
Bert Peters
4b872c1262 Remove deprecated Cargo.toml options 2025-05-13 15:57:30 +02:00
Bert Peters
99bca9852c Opt in to edition 2024 formatting 2025-05-13 15:57:30 +02:00
Bert Peters
b396016224 Remove bors config 2025-05-13 15:57:30 +02:00
Bert Peters
c29ccc4f4d Avoid updating deps on older versions 2025-04-10 20:58:45 +02:00
Bert Peters
8ec32bdf16 Reorganise features 
Now the features do not directly enable each other, which should silence
extraneous deprecation warnings while running tests. This can be cleaned
up in the next BC break when the old features are removed.
 2025-04-10 20:58:45 +02:00
Bert Peters
ccc4c98791 Rename dependencies to their crate names 
Keep the old names but deprecate them so we can remove them in 0.4.
 2025-04-10 20:58:45 +02:00
Bert Peters
9a79b53147 Merge pull request #44 from bertptrs/reset-feature 
Allow resetting dependencies of specific mutexes
 2025-03-10 20:16:59 +01:00
Bert Peters
af366ca3af Document new functionality 2025-03-10 19:32:24 +01:00
Bert Peters
1ad0b2756e Rework CI for experimental features 2025-03-10 18:31:47 +01:00
Bert Peters
d1a6b93ea8 Add new reset_dependencies API 2025-03-01 13:25:20 +01:00
Bert Peters
ebdb6a18fe Restructure stdsync module 2025-03-01 12:39:55 +01:00
Bert Peters
4666923972 Merge pull request #41 from bertptrs/37-make-parking_lot-api-consistent-so-importing-from-toml-works-seamlessly 
Complete `parking_lot` API wrappers
 2025-01-18 20:03:01 +01:00
Bert Peters
7ae0bd3989 Add example showcasing how to replace parking_lot 2025-01-18 20:00:00 +01:00
Bert Peters
0f201989e0 Add missing functions to parking_lot API wrappers 2025-01-18 19:57:32 +01:00
Bert Peters
3dd73fa7ff Merge pull request #40 from bertptrs/dependabot 
Introduce dependabot
 2025-01-18 12:48:37 +01:00
Bert Peters
914320a91c Update cargo dependencies 
This should fix a "security issue"
 2025-01-18 12:45:38 +01:00
Bert Peters
095279aa62 Auto-update github actions packages 2025-01-18 12:39:14 +01:00
Bert Peters
d93879fcf2 Merge pull request #38 from bertptrs/lazylock 
Add support for LazyLock
 2025-01-18 12:30:56 +01:00
Bert Peters
4b17c45a4a Update docs 2025-01-18 12:29:38 +01:00
Bert Peters
7a943ebba6 Fix clippy issues 2025-01-18 12:11:26 +01:00
Bert Peters
25ae542ade Add support for LazyLock 2025-01-18 11:59:18 +01:00
Bert Peters
40f835afd2 Fix clippy issues 2025-01-18 11:57:47 +01:00
Bert Peters
e60dba2c25 Move MSRV checking to a separate step 2025-01-18 11:57:47 +01:00
Bert Peters
8b69ba7835 Update to actions/checkout v4 2025-01-18 11:57:47 +01:00
Bert Peters
9ca5af2c82 Merge pull request #36 from bertptrs/example/show-potential 2023-11-13 08:37:36 +01:00
Bert Peters
74b4fe0bb1 Rewrite example to show potential deadlock 
The example originally showed a certain deadlock, which was not as clear
as it could be. The new version shows intentionally racy code that may
result in a successful execution but may also deadlock.
 2023-11-12 18:36:53 +01:00
bors[bot]
6199598944 Merge #34 
34: Fix remaining references to TracingMutex r=bertptrs a=bertptrs

Thanks to `@ReinierMaas` for noticing.

Co-authored-by: Bert Peters <bert@bertptrs.nl>
 2023-10-06 07:01:48 +00:00
Bert Peters
fd75fc453b Fix remaining references to TracingMutex 2023-10-06 08:59:21 +02:00
bors[bot]
43df59ac1c 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 <bert@bertptrs.nl>
 2023-09-13 10:03:25 +00:00
Bert Peters
1fe44d0a05 Expand changelog 2023-09-11 08:27:06 +02:00
Bert Peters
c9083c8bc1 Clarify feature selection 2023-09-09 12:02:52 +02:00
bors[bot]
d8c559fd3f Merge #32 
32: Capture backtraces for mutex dependencies r=bertptrs a=bertptrs

Builds on top of #28.

This PR adds backtrace data to the dependency graph, so you can figure out what series of events might have introduced the cycle in dependencies. Only the first backtrace

These changes do have a performance penalty, with a worst case of 20-50% degradation over previous results. This applies to the worst case scenario where every dependency between mutexes is new and thus is unlikely to be as severe.

Below is an example of what this can look like, generated with `examples/mutex_cycle.rs`. The formatting is decidedly suboptimal but backtraces cannot be formatted very well in stable rust at the moment. The exact performance hit depends on a lot of things, such as the level of backtraces captured (off, 1, or full), and how many dependencies are involved.

```
thread 'main' panicked at 'Found cycle in mutex dependency graph:
   0: tracing_mutex::MutexDep::capture
             at ./src/lib.rs:278:23
   1: core::ops::function::FnOnce::call_once
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/ops/function.rs:250:5
   2: tracing_mutex::graph::DiGraph<V,E>::add_edge
             at ./src/graph.rs:131:50
   3: tracing_mutex::MutexId::mark_held::{{closure}}
             at ./src/lib.rs:146:17
   4: std:🧵:local::LocalKey<T>::try_with
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/thread/local.rs:270:16
   5: std:🧵:local::LocalKey<T>::with
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/thread/local.rs:246:9
   6: tracing_mutex::MutexId::mark_held
             at ./src/lib.rs:142:25
   7: tracing_mutex::MutexId::get_borrowed
             at ./src/lib.rs:129:9
   8: tracing_mutex::stdsync::tracing::Mutex<T>::lock
             at ./src/stdsync.rs:110:25
   9: mutex_cycle::main
             at ./examples/mutex_cycle.rs:20:18
  10: core::ops::function::FnOnce::call_once
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/ops/function.rs:250:5
  11: std::sys_common::backtrace::__rust_begin_short_backtrace
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/sys_common/backtrace.rs:135:18
  12: std::rt::lang_start::{{closure}}
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/rt.rs:166:18
  13: core::ops::function::impls::<impl core::ops::function::FnOnce<A> for &F>::call_once
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/ops/function.rs:284:13
  14: std::panicking::try::do_call
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panicking.rs:500:40
  15: std::panicking::try
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panicking.rs:464:19
  16: std::panic::catch_unwind
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panic.rs:142:14
  17: std::rt::lang_start_internal::{{closure}}
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/rt.rs:148:48
  18: std::panicking::try::do_call
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panicking.rs:500:40
  19: std::panicking::try
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panicking.rs:464:19
  20: std::panic::catch_unwind
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panic.rs:142:14
  21: std::rt::lang_start_internal
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/rt.rs:148:20
  22: std::rt::lang_start
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/rt.rs:165:17
  23: main
  24: <unknown>
  25: __libc_start_main
  26: _start

   0: tracing_mutex::MutexDep::capture
             at ./src/lib.rs:278:23
   1: core::ops::function::FnOnce::call_once
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/ops/function.rs:250:5
   2: tracing_mutex::graph::DiGraph<V,E>::add_edge
             at ./src/graph.rs:131:50
   3: tracing_mutex::MutexId::mark_held::{{closure}}
             at ./src/lib.rs:146:17
   4: std:🧵:local::LocalKey<T>::try_with
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/thread/local.rs:270:16
   5: std:🧵:local::LocalKey<T>::with
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/thread/local.rs:246:9
   6: tracing_mutex::MutexId::mark_held
             at ./src/lib.rs:142:25
   7: tracing_mutex::MutexId::get_borrowed
             at ./src/lib.rs:129:9
   8: tracing_mutex::stdsync::tracing::Mutex<T>::lock
             at ./src/stdsync.rs:110:25
   9: mutex_cycle::main
             at ./examples/mutex_cycle.rs:14:18
  10: core::ops::function::FnOnce::call_once
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/ops/function.rs:250:5
  11: std::sys_common::backtrace::__rust_begin_short_backtrace
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/sys_common/backtrace.rs:135:18
  12: std::rt::lang_start::{{closure}}
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/rt.rs:166:18
  13: core::ops::function::impls::<impl core::ops::function::FnOnce<A> for &F>::call_once
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/ops/function.rs:284:13
  14: std::panicking::try::do_call
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panicking.rs:500:40
  15: std::panicking::try
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panicking.rs:464:19
  16: std::panic::catch_unwind
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panic.rs:142:14
  17: std::rt::lang_start_internal::{{closure}}
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/rt.rs:148:48
  18: std::panicking::try::do_call
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panicking.rs:500:40
  19: std::panicking::try
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panicking.rs:464:19
  20: std::panic::catch_unwind
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panic.rs:142:14
  21: std::rt::lang_start_internal
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/rt.rs:148:20
  22: std::rt::lang_start
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/rt.rs:165:17
  23: main
  24: <unknown>
  25: __libc_start_main
  26: _start

', src/lib.rs:163:13
stack backtrace:
   0: rust_begin_unwind
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/std/src/panicking.rs:593:5
   1: core::panicking::panic_fmt
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/panicking.rs:67:14
   2: tracing_mutex::MutexId::mark_held
             at ./src/lib.rs:163:13
   3: tracing_mutex::MutexId::get_borrowed
             at ./src/lib.rs:129:9
   4: tracing_mutex::stdsync::tracing::Mutex<T>::lock
             at ./src/stdsync.rs:110:25
   5: mutex_cycle::main
             at ./examples/mutex_cycle.rs:25:14
   6: core::ops::function::FnOnce::call_once
             at /rustc/eb26296b556cef10fb713a38f3d16b9886080f26/library/core/src/ops/function.rs:250:5
```

Importantly, the error shows all the dependencies that are already part of the graph, not the one that was just added, since that is already visible from the immediate panic.

Co-authored-by: Bert Peters <bert@bertptrs.nl>
 2023-09-09 09:24:46 +00:00
Bert Peters
a8e8af6351 Make dependency tracking a compile time setting 2023-09-09 11:21:22 +02:00
Bert Peters
068303d81d Show cycle backtraces when they happen 2023-09-09 11:21:22 +02:00
Bert Peters
6be3e05cab Capture backtraces of allocations for debugging 
Largely based on https://github.com/bertptrs/tracing-mutex/pull/28 with
only minor modifications.
 2023-08-27 16:44:02 +02:00
Bert Peters
909e934572 Reuse dependency orderings in graph 
This avoids a potential panic when adding new nodes to the graph, as
there is no feasible way to overflow IDs any more.
 2023-08-27 15:48:57 +02:00
bors[bot]
0ae544a07a Merge #31 
31: Update CI dependencies r=bertptrs a=bertptrs

actions-rs uses deprecated features, move to dtolney for the toolchain and just use regular run commands for everything else

Co-authored-by: Bert Peters <bert@bertptrs.nl>
 2023-08-27 12:39:35 +00:00
Bert Peters
4148d509bf Update CI dependencies 
actions-rs uses deprecated features, move to dtolney for the toolchain
and just use regular run commands for everything else
 2023-08-27 14:35:40 +02:00
Bert Peters
fc1593b76f Bump criterion version 
0.3 uses some Rust features that will not work in the future, so upgrade
while we're moving thigns anyway
 2023-08-27 14:25:14 +02:00
Bert Peters
8f19921e9e Merge pull request #30 from bertptrs/remove-lazy-static 2023-08-27 11:26:58 +02:00
Bert Peters
00420d6807 Implement wrapper for OnceLock 2023-08-26 00:58:54 +02:00
Bert Peters
49b15bb6bd Bump MSRV to 1.70 2023-08-26 00:58:54 +02:00
Bert Peters
29c9daf53e Replace dependency on lazy-static with OnceLock 2023-08-25 08:44:45 +02:00
bors[bot]
8feedb09d2 Merge #27 
27: Add MSRV of 1.63 r=bertptrs a=bertptrs

Fixes #26.

Co-authored-by: Bert Peters <bert@bertptrs.nl>
 2022-08-29 06:34:17 +00:00
Bert Peters
de9888a102 Update documentation with MSRV 2022-08-29 08:32:17 +02:00
Bert Peters
2d2e03eede Simplify lazy mutex ID drop 2022-08-29 08:26:12 +02:00
Bert Peters
e9b577a0f5 Make stdsync wrappers const-constructible 2022-08-27 10:33:15 +02:00
Bert Peters
5f6823394d Build and test with Rust 1.63 2022-08-27 10:26:42 +02:00
bors[bot]
61d19f866c Merge #25 
25: Restructure modules r=bertptrs a=bertptrs

The `TracingFoo`, `DebugFoo` versions of every `Foo` resulted in quite verbose types everywhere. This PR restructures them to separate modules. The new modules map onto the old types as follows:

- `tracing_mutex::foo::TracingFoo` -> `tracing_mutex::foo::tracing::Foo`
- `tracing_mutex::foo::DebugFoo` -> `tracing_mutex::foo::Foo`

Co-authored-by: Bert Peters <bert@bertptrs.nl>
 2022-08-27 08:18:29 +00:00
Bert Peters
f78969ebf7 Update documentation 2022-08-27 10:08:51 +02:00
Bert Peters
56b0604448 Restructure parking_lot wrappers 2022-08-27 10:06:31 +02:00
Bert Peters
6e5516eaa7 Restructure std::sync wrappers 2022-08-27 10:01:51 +02:00
Bert Peters
764d3df454 Add parking_lot to changelog 2022-08-24 10:28:51 +02:00
bors[bot]
e543860d8b Merge #24 
24: Update parking_lot dependency to 0.12 r=bertptrs a=djkoloski

The changelog for parking_lot 0.12 can be found [here](https://github.com/Amanieu/parking_lot/blob/master/CHANGELOG.md#parking_lot-0120-parking_lot_core-090-lock_api-046-2022-01-28):
```
- The MSRV is bumped to 1.49.0.
- Disabled eventual fairness on wasm32-unknown-unknown. (#302)
- Added a rwlock method to report if lock is held exclusively. (#303)
- Use new asm! macro. (#304)
- Use windows-rs instead of winapi for faster builds. (#311)
- Moved hardware lock elision support to a separate Cargo feature. (#313)
- Removed used of deprecated spin_loop_hint. (#314)
```

Co-authored-by: David Koloski <dkoloski@google.com>
 2022-08-24 08:20:55 +00:00
David Koloski
ed04552af3 Update parking_lot dependency to 0.12 2022-08-23 11:34:31 -04:00
bors[bot]
c5a506436c Merge #23 
23: Ensure `BorrowedMutex` is `!Send` r=bertptrs a=bertptrs

This should prevent the bugs found in #22.

Co-authored-by: Bert Peters <bert@bertptrs.nl>
 2022-06-23 20:02:10 +00:00
Bert Peters
33cb6014a3 Ensure BorrowedMutex is !Send 2022-06-23 21:54:25 +02:00
23 changed files with 2575 additions and 1053 deletions
Expand all files Collapse all files

7
.github/dependabot.yml vendored Normal file
View File

@@ -0,0 +1,7 @@
---
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"

62
.github/workflows/ci.yml vendored
View File

@@ -15,56 +15,64 @@ jobs:
strategy:
matrix:
rust:
- "1.74" # Current minimum for experimental features
- stable
- beta
- nightly
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v6
- uses: actions-rs/toolchain@v1
- uses: dtolnay/rust-toolchain@master
with:
profile: minimal
toolchain: ${{ matrix.rust }}
override: true
components: rustfmt, clippy
components: clippy
- uses: actions-rs/cargo@v1
with:
command: build
# --all-targets ensures that we also build the benchmarks and tests already.
args: --all-features --all-targets
# Make sure we test with recent deps
- run: cargo update
# Note: some crates broke BC with 1.74 so we use the locked deps
if: "${{ matrix.rust != '1.74' }}"
- run: cargo build --all-features --all-targets
- run: cargo test --all-features
# Note: Rust 1.74 doesn't understand edition 2024 formatting so no point
if: "${{ matrix.rust != '1.74' }}"
- run: cargo clippy --all-features --all-targets -- -D warnings
- uses: actions-rs/cargo@v1
with:
command: test
args: --all-features
msrv:
name: MSRV
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions-rs/cargo@v1
- uses: dtolnay/rust-toolchain@1.74
with:
command: fmt
args: --all -- --check
toolchain: "1.70"
- uses: actions-rs/cargo@v1
# Test everything except experimental features.
- run: cargo test --features backtraces,lock_api,parking_lot
formatting:
name: Formatting
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
# Use nightly formatting options
- uses: dtolnay/rust-toolchain@nightly
with:
command: clippy
args: --all-features --all-targets -- -D warnings
components: rustfmt
- run: cargo fmt --check
docs:
name: Documentation build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v6
- uses: actions-rs/toolchain@v1
with:
profile: minimal
toolchain: nightly
override: true
- uses: dtolnay/rust-toolchain@nightly
- name: Build documentation
env:
# Build the docs like docs.rs builds it
RUSTDOCFLAGS: --cfg docsrs
run: cargo doc --all-features
run: cargo doc --all-features --no-deps

1
.gitignore vendored
View File

@@ -1,2 +1 @@
/target
Cargo.lock

72
CHANGELOG.md
View File

@@ -6,6 +6,73 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.3.2]
### Fixed
- `std::sync` wrappers now no longer incorrectly require `T: Sized`
- Added missing `Display` and `Debug` implementations to `RwLock(Read|Write)Guard`.
## [0.3.1]
### Added
- On Rust 1.80 or newer, a wrapper for `std::sync::LazyLock` is now available. The MSRV has not been
changed; older versions simply don't get this wrapper.
- Added missing const-initialisation wrappers for `parking_lot`. The API interface for
`tracing_mutex::parkinglot` is now identical to `parking_lot`, and an example showing how to use
it as a drop-in replacement was added.
- Introduced `experimental` feature, which will be used going forward to help evolve the API outside
the normal stability guarantees. APIs under this feature are not subject to semver or MSRV
guarantees.
- Added experimental api `tracing_mutex::util::reset_dependencies`, which can be used to reset the
ordering information of a specific mutex when you need to reorder them. This API is unsafe, as its
use invalidates any of the deadlock prevention guarantees made.
### Changed
- Reworked CI to better test continued support for the minimum supported Rust version
### Fixed
- Support for `parking_lot` and `lock_api` can now be enabled properly with the matching feature
names.
### Deprecated
- The `parkinglot` and `lockapi` features have been deprecated. They will be removed in version 0.4.
To fix it, you can use the `parking_lot` and `lock_api` features respectively.
## [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. 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. 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
- Enforce that all internal mutex guards are `!Send`. They already should be according to other
reasons, but this adds extra security through the type system.
## [0.2.1] - 2022-05-23
### Added
@@ -67,7 +134,10 @@ 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.2...HEAD
[0.3.2]: https://github.com/bertptrs/tracing-mutex/compare/v0.3.1...v0.3.2
[0.3.1]: https://github.com/bertptrs/tracing-mutex/compare/v0.3.0...v0.3.1
[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

863
Cargo.lock generated Normal file
View File

@@ -0,0 +1,863 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 3
[[package]]
name = "aho-corasick"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6748e8def348ed4d14996fa801f4122cd763fff530258cdc03f64b25f89d3a5a"
dependencies = [
"memchr",
]
[[package]]
name = "anes"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"
[[package]]
name = "anstyle"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "15c4c2c83f81532e5845a733998b6971faca23490340a418e9b72a3ec9de12ea"
[[package]]
name = "autocfg"
version = "1.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ace50bade8e6234aa140d9a2f552bbee1db4d353f69b8217bc503490fc1a9f26"
[[package]]
name = "bitflags"
version = "1.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
[[package]]
name = "bitflags"
version = "2.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b4682ae6287fcf752ecaabbfcc7b6f9b72aa33933dc23a554d853aea8eea8635"
[[package]]
name = "bumpalo"
version = "3.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a3e2c3daef883ecc1b5d58c15adae93470a91d425f3532ba1695849656af3fc1"
[[package]]
name = "cast"
version = "0.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
[[package]]
name = "cfg-if"
version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
[[package]]
name = "ciborium"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "effd91f6c78e5a4ace8a5d3c0b6bfaec9e2baaef55f3efc00e45fb2e477ee926"
dependencies = [
"ciborium-io",
"ciborium-ll",
"serde",
]
[[package]]
name = "ciborium-io"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cdf919175532b369853f5d5e20b26b43112613fd6fe7aee757e35f7a44642656"
[[package]]
name = "ciborium-ll"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "defaa24ecc093c77630e6c15e17c51f5e187bf35ee514f4e2d67baaa96dae22b"
dependencies = [
"ciborium-io",
"half",
]
[[package]]
name = "clap"
version = "4.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1d5f1946157a96594eb2d2c10eb7ad9a2b27518cb3000209dec700c35df9197d"
dependencies = [
"clap_builder",
]
[[package]]
name = "clap_builder"
version = "4.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "78116e32a042dd73c2901f0dc30790d20ff3447f3e3472fad359e8c3d282bcd6"
dependencies = [
"anstyle",
"clap_lex",
]
[[package]]
name = "clap_lex"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cd7cc57abe963c6d3b9d8be5b06ba7c8957a930305ca90304f24ef040aa6f961"
[[package]]
name = "criterion"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"
dependencies = [
"anes",
"cast",
"ciborium",
"clap",
"criterion-plot",
"is-terminal",
"itertools",
"num-traits",
"once_cell",
"oorandom",
"plotters",
"rayon",
"regex",
"serde",
"serde_derive",
"serde_json",
"tinytemplate",
"walkdir",
]
[[package]]
name = "criterion-plot"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
dependencies = [
"cast",
"itertools",
]
[[package]]
name = "crossbeam-channel"
version = "0.5.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a33c2bf77f2df06183c3aa30d1e96c0695a313d4f9c453cc3762a6db39f99200"
dependencies = [
"cfg-if",
"crossbeam-utils",
]
[[package]]
name = "crossbeam-deque"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ce6fd6f855243022dcecf8702fef0c297d4338e226845fe067f6341ad9fa0cef"
dependencies = [
"cfg-if",
"crossbeam-epoch",
"crossbeam-utils",
]
[[package]]
name = "crossbeam-epoch"
version = "0.9.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ae211234986c545741a7dc064309f67ee1e5ad243d0e48335adc0484d960bcc7"
dependencies = [
"autocfg",
"cfg-if",
"crossbeam-utils",
"memoffset",
"scopeguard",
]
[[package]]
name = "crossbeam-utils"
version = "0.8.16"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5a22b2d63d4d1dc0b7f1b6b2747dd0088008a9be28b6ddf0b1e7d335e3037294"
dependencies = [
"cfg-if",
]
[[package]]
name = "either"
version = "1.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a26ae43d7bcc3b814de94796a5e736d4029efb0ee900c12e2d54c993ad1a1e07"
[[package]]
name = "errno"
version = "0.3.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "33d852cb9b869c2a9b3df2f71a3074817f01e1844f839a144f5fcef059a4eb5d"
dependencies = [
"libc",
"windows-sys 0.59.0",
]
[[package]]
name = "getrandom"
version = "0.2.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "be4136b2a15dd319360be1c07d9933517ccf0be8f16bf62a3bee4f0d618df427"
dependencies = [
"cfg-if",
"libc",
"wasi",
]
[[package]]
name = "half"
version = "1.8.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "eabb4a44450da02c90444cf74558da904edde8fb4e9035a9a6a4e15445af0bd7"
[[package]]
name = "hermit-abi"
version = "0.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "443144c8cdadd93ebf52ddb4056d257f5b52c04d3c804e657d19eb73fc33668b"
[[package]]
name = "is-terminal"
version = "0.4.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cb0889898416213fab133e1d33a0e5858a48177452750691bde3666d0fdbaf8b"
dependencies = [
"hermit-abi",
"rustix",
"windows-sys 0.48.0",
]
[[package]]
name = "itertools"
version = "0.10.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"
dependencies = [
"either",
]
[[package]]
name = "itoa"
version = "1.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "af150ab688ff2122fcef229be89cb50dd66af9e01a4ff320cc137eecc9bacc38"
[[package]]
name = "js-sys"
version = "0.3.64"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c5f195fe497f702db0f318b07fdd68edb16955aed830df8363d837542f8f935a"
dependencies = [
"wasm-bindgen",
]
[[package]]
name = "libc"
version = "0.2.169"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b5aba8db14291edd000dfcc4d620c7ebfb122c613afb886ca8803fa4e128a20a"
[[package]]
name = "linux-raw-sys"
version = "0.4.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
[[package]]
name = "lock_api"
version = "0.4.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c1cc9717a20b1bb222f333e6a92fd32f7d8a18ddc5a3191a11af45dcbf4dcd16"
dependencies = [
"autocfg",
"scopeguard",
]
[[package]]
name = "log"
version = "0.4.20"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b5e6163cb8c49088c2c36f57875e58ccd8c87c7427f7fbd50ea6710b2f3f2e8f"
[[package]]
name = "memchr"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2dffe52ecf27772e601905b7522cb4ef790d2cc203488bbd0e2fe85fcb74566d"
[[package]]
name = "memoffset"
version = "0.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5a634b1c61a95585bd15607c6ab0c4e5b226e695ff2800ba0cdccddf208c406c"
dependencies = [
"autocfg",
]
[[package]]
name = "num-traits"
version = "0.2.16"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f30b0abd723be7e2ffca1272140fac1a2f084c77ec3e123c192b66af1ee9e6c2"
dependencies = [
"autocfg",
]
[[package]]
name = "num_cpus"
version = "1.16.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4161fcb6d602d4d2081af7c3a45852d875a03dd337a6bfdd6e06407b61342a43"
dependencies = [
"hermit-abi",
"libc",
]
[[package]]
name = "once_cell"
version = "1.18.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dd8b5dd2ae5ed71462c540258bedcb51965123ad7e7ccf4b9a8cafaa4a63576d"
[[package]]
name = "oorandom"
version = "11.1.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0ab1bc2a289d34bd04a330323ac98a1b4bc82c9d9fcb1e66b63caa84da26b575"
[[package]]
name = "parking_lot"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3742b2c103b9f06bc9fff0a37ff4912935851bee6d36f3c02bcc755bcfec228f"
dependencies = [
"lock_api",
"parking_lot_core",
]
[[package]]
name = "parking_lot_core"
version = "0.9.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "93f00c865fe7cabf650081affecd3871070f26767e7b2070a3ffae14c654b447"
dependencies = [
"cfg-if",
"libc",
"redox_syscall",
"smallvec",
"windows-targets 0.48.5",
]
[[package]]
name = "plotters"
version = "0.3.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d2c224ba00d7cadd4d5c660deaf2098e5e80e07846537c51f9cfa4be50c1fd45"
dependencies = [
"num-traits",
"plotters-backend",
"plotters-svg",
"wasm-bindgen",
"web-sys",
]
[[package]]
name = "plotters-backend"
version = "0.3.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9e76628b4d3a7581389a35d5b6e2139607ad7c75b17aed325f210aa91f4a9609"
[[package]]
name = "plotters-svg"
version = "0.3.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "38f6d39893cca0701371e3c27294f09797214b86f1fb951b89ade8ec04e2abab"
dependencies = [
"plotters-backend",
]
[[package]]
name = "ppv-lite86"
version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5b40af805b3121feab8a3c29f04d8ad262fa8e0561883e7653e024ae4479e6de"
[[package]]
name = "proc-macro2"
version = "1.0.66"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "18fb31db3f9bddb2ea821cde30a9f70117e3f119938b5ee630b7403aa6e2ead9"
dependencies = [
"unicode-ident",
]
[[package]]
name = "quote"
version = "1.0.33"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5267fca4496028628a95160fc423a33e8b2e6af8a5302579e322e4b520293cae"
dependencies = [
"proc-macro2",
]
[[package]]
name = "rand"
version = "0.8.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
dependencies = [
"libc",
"rand_chacha",
"rand_core",
]
[[package]]
name = "rand_chacha"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
dependencies = [
"ppv-lite86",
"rand_core",
]
[[package]]
name = "rand_core"
version = "0.6.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
dependencies = [
"getrandom",
]
[[package]]
name = "rayon"
version = "1.7.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1d2df5196e37bcc87abebc0053e20787d73847bb33134a69841207dd0a47f03b"
dependencies = [
"either",
"rayon-core",
]
[[package]]
name = "rayon-core"
version = "1.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4b8f95bd6966f5c87776639160a66bd8ab9895d9d4ab01ddba9fc60661aebe8d"
dependencies = [
"crossbeam-channel",
"crossbeam-deque",
"crossbeam-utils",
"num_cpus",
]
[[package]]
name = "redox_syscall"
version = "0.3.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "567664f262709473930a4bf9e51bf2ebf3348f2e748ccc50dea20646858f8f29"
dependencies = [
"bitflags 1.3.2",
]
[[package]]
name = "regex"
version = "1.9.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "12de2eff854e5fa4b1295edd650e227e9d8fb0c9e90b12e7f36d6a6811791a29"
dependencies = [
"aho-corasick",
"memchr",
"regex-automata",
"regex-syntax",
]
[[package]]
name = "regex-automata"
version = "0.3.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "49530408a136e16e5b486e883fbb6ba058e8e4e8ae6621a77b048b314336e629"
dependencies = [
"aho-corasick",
"memchr",
"regex-syntax",
]
[[package]]
name = "regex-syntax"
version = "0.7.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dbb5fb1acd8a1a18b3dd5be62d25485eb770e05afb408a9627d14d451bae12da"
[[package]]
name = "rustix"
version = "0.38.43"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a78891ee6bf2340288408954ac787aa063d8e8817e9f53abb37c695c6d834ef6"
dependencies = [
"bitflags 2.4.0",
"errno",
"libc",
"linux-raw-sys",
"windows-sys 0.59.0",
]
[[package]]
name = "ryu"
version = "1.0.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1ad4cc8da4ef723ed60bced201181d83791ad433213d8c24efffda1eec85d741"
[[package]]
name = "same-file"
version = "1.0.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
dependencies = [
"winapi-util",
]
[[package]]
name = "scopeguard"
version = "1.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
[[package]]
name = "serde"
version = "1.0.188"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf9e0fcba69a370eed61bcf2b728575f726b50b55cba78064753d708ddc7549e"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.188"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4eca7ac642d82aa35b60049a6eccb4be6be75e599bd2e9adb5f875a737654af2"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "serde_json"
version = "1.0.105"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "693151e1ac27563d6dbcec9dee9fbd5da8539b20fa14ad3752b2e6d363ace360"
dependencies = [
"itoa",
"ryu",
"serde",
]
[[package]]
name = "smallvec"
version = "1.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "62bb4feee49fdd9f707ef802e22365a35de4b7b299de4763d44bfea899442ff9"
[[package]]
name = "syn"
version = "2.0.29"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c324c494eba9d92503e6f1ef2e6df781e78f6a7705a0202d9801b198807d518a"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "tinytemplate"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc"
dependencies = [
"serde",
"serde_json",
]
[[package]]
name = "tracing-mutex"
version = "0.3.2"
dependencies = [
"autocfg",
"criterion",
"lock_api",
"parking_lot",
"rand",
]
[[package]]
name = "unicode-ident"
version = "1.0.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "301abaae475aa91687eb82514b328ab47a211a533026cb25fc3e519b86adfc3c"
[[package]]
name = "walkdir"
version = "2.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "36df944cda56c7d8d8b7496af378e6b16de9284591917d307c9b4d313c44e698"
dependencies = [
"same-file",
"winapi-util",
]
[[package]]
name = "wasi"
version = "0.11.0+wasi-snapshot-preview1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423"
[[package]]
name = "wasm-bindgen"
version = "0.2.87"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7706a72ab36d8cb1f80ffbf0e071533974a60d0a308d01a5d0375bf60499a342"
dependencies = [
"cfg-if",
"wasm-bindgen-macro",
]
[[package]]
name = "wasm-bindgen-backend"
version = "0.2.87"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5ef2b6d3c510e9625e5fe6f509ab07d66a760f0885d858736483c32ed7809abd"
dependencies = [
"bumpalo",
"log",
"once_cell",
"proc-macro2",
"quote",
"syn",
"wasm-bindgen-shared",
]
[[package]]
name = "wasm-bindgen-macro"
version = "0.2.87"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dee495e55982a3bd48105a7b947fd2a9b4a8ae3010041b9e0faab3f9cd028f1d"
dependencies = [
"quote",
"wasm-bindgen-macro-support",
]
[[package]]
name = "wasm-bindgen-macro-support"
version = "0.2.87"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "54681b18a46765f095758388f2d0cf16eb8d4169b639ab575a8f5693af210c7b"
dependencies = [
"proc-macro2",
"quote",
"syn",
"wasm-bindgen-backend",
"wasm-bindgen-shared",
]
[[package]]
name = "wasm-bindgen-shared"
version = "0.2.87"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ca6ad05a4870b2bf5fe995117d3728437bd27d7cd5f06f13c17443ef369775a1"
[[package]]
name = "web-sys"
version = "0.3.64"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b85cbef8c220a6abc02aefd892dfc0fc23afb1c6a426316ec33253a3877249b"
dependencies = [
"js-sys",
"wasm-bindgen",
]
[[package]]
name = "winapi"
version = "0.3.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
dependencies = [
"winapi-i686-pc-windows-gnu",
"winapi-x86_64-pc-windows-gnu",
]
[[package]]
name = "winapi-i686-pc-windows-gnu"
version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
[[package]]
name = "winapi-util"
version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "70ec6ce85bb158151cae5e5c87f95a8e97d2c0c4b001223f33a334e3ce5de178"
dependencies = [
"winapi",
]
[[package]]
name = "winapi-x86_64-pc-windows-gnu"
version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
[[package]]
name = "windows-sys"
version = "0.48.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9"
dependencies = [
"windows-targets 0.48.5",
]
[[package]]
name = "windows-sys"
version = "0.59.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
dependencies = [
"windows-targets 0.52.6",
]
[[package]]
name = "windows-targets"
version = "0.48.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9a2fa6e2155d7247be68c096456083145c183cbbbc2764150dda45a87197940c"
dependencies = [
"windows_aarch64_gnullvm 0.48.5",
"windows_aarch64_msvc 0.48.5",
"windows_i686_gnu 0.48.5",
"windows_i686_msvc 0.48.5",
"windows_x86_64_gnu 0.48.5",
"windows_x86_64_gnullvm 0.48.5",
"windows_x86_64_msvc 0.48.5",
]
[[package]]
name = "windows-targets"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
dependencies = [
"windows_aarch64_gnullvm 0.52.6",
"windows_aarch64_msvc 0.52.6",
"windows_i686_gnu 0.52.6",
"windows_i686_gnullvm",
"windows_i686_msvc 0.52.6",
"windows_x86_64_gnu 0.52.6",
"windows_x86_64_gnullvm 0.52.6",
"windows_x86_64_msvc 0.52.6",
]
[[package]]
name = "windows_aarch64_gnullvm"
version = "0.48.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2b38e32f0abccf9987a4e3079dfb67dcd799fb61361e53e2882c3cbaf0d905d8"
[[package]]
name = "windows_aarch64_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
[[package]]
name = "windows_aarch64_msvc"
version = "0.48.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dc35310971f3b2dbbf3f0690a219f40e2d9afcf64f9ab7cc1be722937c26b4bc"
[[package]]
name = "windows_aarch64_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
[[package]]
name = "windows_i686_gnu"
version = "0.48.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a75915e7def60c94dcef72200b9a8e58e5091744960da64ec734a6c6e9b3743e"
[[package]]
name = "windows_i686_gnu"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
[[package]]
name = "windows_i686_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
[[package]]
name = "windows_i686_msvc"
version = "0.48.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f55c233f70c4b27f66c523580f78f1004e8b5a8b659e05a4eb49d4166cca406"
[[package]]
name = "windows_i686_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
[[package]]
name = "windows_x86_64_gnu"
version = "0.48.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "53d40abd2583d23e4718fddf1ebec84dbff8381c07cae67ff7768bbf19c6718e"
[[package]]
name = "windows_x86_64_gnu"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
[[package]]
name = "windows_x86_64_gnullvm"
version = "0.48.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0b7b52767868a23d5bab768e390dc5f5c55825b6d30b86c844ff2dc7414044cc"
[[package]]
name = "windows_x86_64_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
[[package]]
name = "windows_x86_64_msvc"
version = "0.48.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538"
[[package]]
name = "windows_x86_64_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"

29
Cargo.toml
View File

@@ -1,15 +1,14 @@
[package]
name = "tracing-mutex"
version = "0.2.1"
authors = ["Bert Peters <bert@bertptrs.nl>"]
version = "0.3.2"
edition = "2021"
license = "MIT OR Apache-2.0"
documentation = "https://docs.rs/tracing-mutex"
categories = ["concurrency", "development-tools::debugging"]
keywords = ["mutex", "rwlock", "once", "thread"]
description = "Ensure deadlock-free mutexes by allocating in order, or else."
readme = "README.md"
repository = "https://github.com/bertptrs/tracing-mutex"
rust-version = "1.70"
[package.metadata.docs.rs]
# Build docs for all features so the documentation is more complete
@@ -18,19 +17,31 @@ all-features = true
rustdoc-args = ["--cfg", "docsrs"]
[dependencies]
lazy_static = "1"
lock_api = { version = "0.4", optional = true }
parking_lot = { version = "0.11", optional = true }
parking_lot = { version = "0.12", optional = true }
[dev-dependencies]
criterion = "0.3"
criterion = "0.5"
rand = "0.8"
[[bench]]
name = "mutex"
harness = false
[[example]]
name = "drop_in_parking_lot"
required-features = ["parkinglot"]
[features]
# Feature names do not match crate names pending namespaced features.
lockapi = ["lock_api"]
parkinglot = ["parking_lot", "lockapi"]
default = ["backtraces"]
backtraces = []
experimental = []
lock_api = ["dep:lock_api"]
parking_lot = ["dep:parking_lot", "lock_api"]
# Deprecated feature names from when cargo couldn't distinguish between dep and feature
lockapi = ["dep:lock_api"]
parkinglot = ["dep:parking_lot", "lock_api"]
[build-dependencies]
autocfg = "1.4.0"

23
README.md
View File

@@ -23,10 +23,12 @@ tree out of it, and panics if your dependencies would create a cycle. It provide
existing synchronization primitives with an identical API, and should be a drop-in replacement.
Inspired by [this blogpost][whileydave], which references a similar behaviour implemented by
[Abseil][abseil-mutex] for their mutexes.
[Abseil][abseil-mutex] for their mutexes. [This article goes into more depth on the exact
implementation.][article]
[whileydave]: https://whileydave.com/2020/12/19/dynamic-cycle-detection-for-lock-ordering/
[abseil-mutex]: https://abseil.io/docs/cpp/guides/synchronization
[article]: https://bertptrs.nl/2022/06/23/deadlock-free-mutexes-and-directed-acyclic-graphs.html
## Usage
@@ -34,7 +36,7 @@ Add this dependency to your `Cargo.lock` file like any other:
```toml
[dependencies]
tracing-mutex = "0.2"
tracing-mutex = "0.3"
```
Then use the locks provided by this library instead of the ones you would use otherwise.
@@ -42,9 +44,9 @@ Replacements for the synchronization primitives in `std::sync` can be found in t
Support for other synchronization primitives is planned.
```rust
use tracing_mutex::stdsync::TracingMutex;
use tracing_mutex::stdsync::Mutex;
let some_mutex = TracingMutex::new(42);
let some_mutex = Mutex::new(42);
*some_mutex.lock().unwrap() += 1;
println!("{:?}", some_mutex);
```
@@ -54,15 +56,19 @@ introduce a cyclic dependency between your locks, the operation panics instead.
immediately notice the cyclic dependency rather than be eventually surprised by it in production.
Mutex tracing is efficient, but it is not completely overhead-free. If you cannot spare the
performance penalty in your production environment, this library also offers debug-only tracing.
`DebugMutex`, also found in the `stdsync` module, is a type alias that evaluates to `TracingMutex`
when debug assertions are enabled, and to `Mutex` when they are not. Similar helper types are
available for other synchronization primitives.
performance penalty in your production environment, this library also offers debug-only tracing. The
type aliases in `tracing_mutex::stdsync` correspond to tracing primitives from
`tracing_mutex::stdsync::tracing` when debug assertions are enabled, and to primitives from
`std::sync::Mutex` when they are not. A similar structure exists for other
The minimum supported Rust version is 1.70. Increasing this is not considered a breaking change, but
will be avoided within semver-compatible releases if possible.
### Features
- Dependency-tracking wrappers for all locking primitives
- Optional opt-out for release mode code
- Optional backtrace capture to aid with reproducing cyclic mutex chains
- Support for primitives from:
- `std::sync`
- `parking_lot`
@@ -71,7 +77,6 @@ available for other synchronization primitives.
## 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
- Support for async locking libraries

6
benches/mutex.rs
View File

@@ -1,13 +1,13 @@
use std::sync::Arc;
use std::sync::Mutex;
use criterion::criterion_group;
use criterion::criterion_main;
use criterion::BenchmarkId;
use criterion::Criterion;
use criterion::Throughput;
use criterion::criterion_group;
use criterion::criterion_main;
use rand::prelude::*;
use tracing_mutex::stdsync::TracingMutex;
use tracing_mutex::stdsync::tracing::Mutex as TracingMutex;
const SAMPLE_SIZES: [usize; 5] = [10, 30, 100, 300, 1000];

5
bors.toml
View File

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

10
build.rs Normal file
View File

@@ -0,0 +1,10 @@
use autocfg::AutoCfg;
fn main() {
// To avoid bumping MSRV unnecessarily, we can sniff certain features. Reevaluate this on major
// releases.
let ac = AutoCfg::new().unwrap();
ac.emit_has_path("std::sync::LazyLock");
autocfg::rerun_path("build.rs");
}

32
examples/drop_in_parking_lot.rs Normal file
View File

@@ -0,0 +1,32 @@
//! This example shows how you can use the [`tracing-mutex`] crate as a drop-in replacement for the
//! parking_lot crate. By default, `tracing-mutex` offers a set of type aliases that allows you to
//! use cycle-checking in development, and raw primitives in release mode, but this way, you can
//! even remove the dependency altogether, or hide it behind a feature.
//!
//! You can use whatever conditional compilation makes sense in context.
use std::sync::Arc;
#[cfg(not(debug_assertions))]
use parking_lot;
#[cfg(debug_assertions)]
// Note: specifically use the `tracing` module, because at this point we are very sure we want to do
// deadlock tracing, so no need to use the automatic selection.
use tracing_mutex::parkinglot::tracing as parking_lot;
fn main() {
let mutex = Arc::new(parking_lot::const_mutex(0));
let handles: Vec<_> = (0..42)
.map(|_| {
let mutex = Arc::clone(&mutex);
std::thread::spawn(move || *mutex.lock() += 1)
})
.collect();
handles
.into_iter()
.for_each(|handle| handle.join().unwrap());
assert_eq!(*mutex.lock(), 42);
}

62
examples/mutex_cycle.rs Normal file
View File

@@ -0,0 +1,62 @@
//! Show what a crash looks like
//!
//! This shows what a traceback of a cycle detection looks like. It is expected to crash when run in
//! debug mode, because it might deadlock. In release mode, no tracing is used and the program may
//! do any of the following:
//!
//! - Return a random valuation of `a`, `b`, and `c`. The implementation has a race-condition by
//! design. I have observed (4, 3, 6), but also (6, 3, 5).
//! - Deadlock forever.
//!
//! One can increase the SLEEP_TIME constant to increase the likelihood of a deadlock to occur. On
//! my machine, 1ns of sleep time gives about a 50/50 chance of the program deadlocking.
use std::thread;
use std::time::Duration;
use tracing_mutex::stdsync::Mutex;
fn main() {
let a = Mutex::new(1);
let b = Mutex::new(2);
let c = Mutex::new(3);
// Increase this time to increase the likelihood of a deadlock.
const SLEEP_TIME: Duration = Duration::from_nanos(1);
// Depending on random CPU performance, this section may deadlock, or may return a result. With
// tracing enabled, the potential deadlock is always detected and a backtrace should be
// produced.
thread::scope(|s| {
// Create an edge from a to b
s.spawn(|| {
let a = a.lock().unwrap();
thread::sleep(SLEEP_TIME);
*b.lock().unwrap() += *a;
});
// Create an edge from b to c
s.spawn(|| {
let b = b.lock().unwrap();
thread::sleep(SLEEP_TIME);
*c.lock().unwrap() += *b;
});
// Create an edge from c to a
//
// N.B. the program can crash on any of the three edges, as there is no guarantee which
// thread will execute first. Nevertheless, any one of them is guaranteed to panic with
// tracing enabled.
s.spawn(|| {
let c = c.lock().unwrap();
thread::sleep(SLEEP_TIME);
*a.lock().unwrap() += *c;
});
});
println!(
"{}, {}, {}",
a.into_inner().unwrap(),
b.into_inner().unwrap(),
c.into_inner().unwrap()
);
}

2
rustfmt.toml Normal file
View File

@@ -0,0 +1,2 @@
style_edition="2024"
imports_granularity="Item"

130
src/graph.rs
View File

@@ -1,6 +1,7 @@
use std::cell::Cell;
use std::collections::HashMap;
use std::collections::HashSet;
use std::collections::hash_map::Entry;
use std::hash::Hash;
type Order = usize;
@@ -19,23 +20,24 @@ type Order = usize;
/// visibly changed.
///
/// [paper]: https://whileydave.com/publications/pk07_jea/
#[derive(Default, Debug)]
pub struct DiGraph<V>
#[derive(Debug)]
pub struct DiGraph<V, E>
where
V: Eq + Hash + Copy,
{
nodes: HashMap<V, Node<V>>,
/// Next topological sort order
next_ord: Order,
nodes: HashMap<V, Node<V, E>>,
// Instead of reordering the orders in the graph whenever a node is deleted, we maintain a list
// of unused ids that can be handed out later again.
unused_order: Vec<Order>,
}
#[derive(Debug)]
struct Node<V>
struct Node<V, E>
where
V: Eq + Hash + Clone,
{
in_edges: HashSet<V>,
out_edges: HashSet<V>,
out_edges: HashMap<V, E>,
// The "Ord" field is a Cell to ensure we can update it in an immutable context.
// `std::collections::HashMap` doesn't let you have multiple mutable references to elements, but
// this way we can use immutable references and still update `ord`. This saves quite a few
@@ -43,7 +45,7 @@ where
ord: Cell<Order>,
}
impl<V> DiGraph<V>
impl<V, E> DiGraph<V, E>
where
V: Eq + Hash + Copy,
{
@@ -54,12 +56,18 @@ where
/// the node in the topological order.
///
/// New nodes are appended to the end of the topological order when added.
fn add_node(&mut self, n: V) -> (&mut HashSet<V>, &mut HashSet<V>, Order) {
let next_ord = &mut self.next_ord;
fn add_node(&mut self, n: V) -> (&mut HashSet<V>, &mut HashMap<V, E>, Order) {
// need to compute next id before the call to entry() to avoid duplicate borrow of nodes
let fallback_id = self.nodes.len();
let node = self.nodes.entry(n).or_insert_with(|| {
let order = *next_ord;
*next_ord = next_ord.checked_add(1).expect("Topological order overflow");
let order = if let Some(id) = self.unused_order.pop() {
// Reuse discarded ordering entry
id
} else {
// Allocate new order id
fallback_id
};
Node {
ord: Cell::new(order),
@@ -77,9 +85,12 @@ where
Some(Node {
out_edges,
in_edges,
..
ord,
}) => {
out_edges.into_iter().for_each(|m| {
// Return ordering to the pool of unused ones
self.unused_order.push(ord.get());
out_edges.into_keys().for_each(|m| {
self.nodes.get_mut(&m).unwrap().in_edges.remove(&n);
});
@@ -96,18 +107,29 @@ where
///
/// Nodes, both from and to, are created as needed when creating new edges. If the new edge
/// would introduce a cycle, the edge is rejected and `false` is returned.
pub(crate) fn add_edge(&mut self, x: V, y: V) -> bool {
///
/// # Errors
///
/// If the edge would introduce the cycle, the underlying graph is not modified and a list of
/// all the edge data in the would-be cycle is returned instead.
pub(crate) fn add_edge(&mut self, x: V, y: V, e: impl FnOnce() -> E) -> Result<(), Vec<E>>
where
E: Clone,
{
if x == y {
// self-edges are always considered cycles
return false;
return Err(Vec::new());
}
let (_, out_edges, ub) = self.add_node(x);
if !out_edges.insert(y) {
match out_edges.entry(y) {
Entry::Occupied(_) => {
// Edge already exists, nothing to be done
return true;
return Ok(());
}
Entry::Vacant(entry) => entry.insert(e()),
};
let (in_edges, _, lb) = self.add_node(y);
@@ -119,7 +141,7 @@ where
let mut delta_f = Vec::new();
let mut delta_b = Vec::new();
if !self.dfs_f(&self.nodes[&y], ub, &mut visited, &mut delta_f) {
if let Err(cycle) = self.dfs_f(&self.nodes[&y], ub, &mut visited, &mut delta_f) {
// This edge introduces a cycle, so we want to reject it and remove it from the
// graph again to keep the "does not contain cycles" invariant.
@@ -129,7 +151,7 @@ where
self.nodes.get_mut(&x).map(|node| node.out_edges.remove(&y));
// No edge was added
return false;
return Err(cycle);
}
// No need to check as we should've found the cycle on the forward pass
@@ -141,44 +163,49 @@ where
self.reorder(delta_f, delta_b);
}
true
Ok(())
}
/// Forwards depth-first-search
fn dfs_f<'a>(
&'a self,
n: &'a Node<V>,
n: &'a Node<V, E>,
ub: Order,
visited: &mut HashSet<V>,
delta_f: &mut Vec<&'a Node<V>>,
) -> bool {
delta_f: &mut Vec<&'a Node<V, E>>,
) -> Result<(), Vec<E>>
where
E: Clone,
{
delta_f.push(n);
n.out_edges.iter().all(|w| {
for (w, e) in &n.out_edges {
let node = &self.nodes[w];
let ord = node.ord.get();
if ord == ub {
// Found a cycle
false
return Err(vec![e.clone()]);
} else if !visited.contains(w) && ord < ub {
// Need to check recursively
visited.insert(*w);
self.dfs_f(node, ub, visited, delta_f)
} else {
// Already seen this one or not interesting
true
if let Err(mut chain) = self.dfs_f(node, ub, visited, delta_f) {
chain.push(e.clone());
return Err(chain);
}
})
}
}
Ok(())
}
/// Backwards depth-first-search
fn dfs_b<'a>(
&'a self,
n: &'a Node<V>,
n: &'a Node<V, E>,
lb: Order,
visited: &mut HashSet<V>,
delta_b: &mut Vec<&'a Node<V>>,
delta_b: &mut Vec<&'a Node<V, E>>,
) {
delta_b.push(n);
@@ -192,7 +219,7 @@ where
}
}
fn reorder(&self, mut delta_f: Vec<&Node<V>>, mut delta_b: Vec<&Node<V>>) {
fn reorder(&self, mut delta_f: Vec<&Node<V, E>>, mut delta_b: Vec<&Node<V, E>>) {
self.sort(&mut delta_f);
self.sort(&mut delta_b);
@@ -213,12 +240,25 @@ where
}
}
fn sort(&self, ids: &mut [&Node<V>]) {
fn sort(&self, ids: &mut [&Node<V, E>]) {
// Can use unstable sort because mutex ids should not be equal
ids.sort_unstable_by_key(|v| &v.ord);
}
}
// Manual `Default` impl as derive causes unnecessarily strong bounds.
impl<V, E> Default for DiGraph<V, E>
where
V: Eq + Hash + Copy,
{
fn default() -> Self {
Self {
nodes: Default::default(),
unused_order: Default::default(),
}
}
}
#[cfg(test)]
mod tests {
use rand::seq::SliceRandom;
@@ -226,12 +266,14 @@ mod tests {
use super::*;
fn nop() {}
#[test]
fn test_no_self_cycle() {
// Regression test for https://github.com/bertptrs/tracing-mutex/issues/7
let mut graph = DiGraph::default();
assert!(!graph.add_edge(1, 1));
assert!(graph.add_edge(1, 1, nop).is_err());
}
#[test]
@@ -239,16 +281,16 @@ mod tests {
let mut graph = DiGraph::default();
// Add some safe edges
assert!(graph.add_edge(0, 1));
assert!(graph.add_edge(1, 2));
assert!(graph.add_edge(2, 3));
assert!(graph.add_edge(4, 2));
assert!(graph.add_edge(0, 1, nop).is_ok());
assert!(graph.add_edge(1, 2, nop).is_ok());
assert!(graph.add_edge(2, 3, nop).is_ok());
assert!(graph.add_edge(4, 2, nop).is_ok());
// Try to add an edge that introduces a cycle
assert!(!graph.add_edge(3, 1));
assert!(graph.add_edge(3, 1, nop).is_err());
// Add an edge that should reorder 0 to be after 4
assert!(graph.add_edge(4, 0));
assert!(graph.add_edge(4, 0, nop).is_ok());
}
/// Fuzz the DiGraph implementation by adding a bunch of valid edges.
@@ -256,7 +298,7 @@ mod tests {
/// This test generates all possible forward edges in a 100-node graph consisting of natural
/// numbers, shuffles them, then adds them to the graph. This will always be a valid directed,
/// acyclic graph because there is a trivial order (the natural numbers) but because the edges
/// are added in a random order the DiGraph will still occassionally need to reorder nodes.
/// are added in a random order the DiGraph will still occasionally need to reorder nodes.
#[test]
fn fuzz_digraph() {
// Note: this fuzzer is quadratic in the number of nodes, so this cannot be too large or it
@@ -277,7 +319,7 @@ mod tests {
let mut graph = DiGraph::default();
for (x, y) in edges {
assert!(graph.add_edge(x, y));
assert!(graph.add_edge(x, y, nop).is_ok());
}
}
}

193
src/lib.rs
View File

@@ -18,8 +18,28 @@
//! # 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 unacceptable, 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
//!
//! - `experimental`: Enables experimental features. Experimental features are intended to test new
//! APIs and play with new APIs before committing to them. As such, breaking changes may be
//! introduced in it between otherwise semver-compatible versions, and the MSRV does not apply to
//! experimental features.
//!
//! # Performance considerations
//!
@@ -41,59 +61,67 @@
//!
//! These operations have been reasonably optimized, but the performance penalty may yet be too much
//! for production use. In those cases, it may be beneficial to instead use debug-only versions
//! (such as [`stdsync::DebugMutex`]) which evaluate to a tracing mutex when debug assertions are
//! (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::cell::UnsafeCell;
use std::fmt;
use std::marker::PhantomData;
use std::mem::MaybeUninit;
use std::ops::Deref;
use std::ops::DerefMut;
use std::ptr;
use std::sync::Mutex;
use std::sync::MutexGuard;
use std::sync::OnceLock;
use std::sync::PoisonError;
use std::sync::atomic::AtomicUsize;
use std::sync::atomic::Ordering;
use std::sync::Mutex;
use std::sync::Once;
use std::sync::PoisonError;
use lazy_static::lazy_static;
#[cfg(feature = "lockapi")]
#[cfg(feature = "lock_api")]
#[cfg_attr(docsrs, doc(cfg(feature = "lockapi")))]
#[deprecated = "The top-level re-export `lock_api` is deprecated. Use `tracing_mutex::lockapi::raw` instead"]
pub use lock_api;
#[cfg(feature = "parkinglot")]
#[cfg(feature = "parking_lot")]
#[cfg_attr(docsrs, doc(cfg(feature = "parkinglot")))]
#[deprecated = "The top-level re-export `parking_lot` is deprecated. Use `tracing_mutex::parkinglot::raw` instead"]
pub use parking_lot;
use crate::graph::DiGraph;
use graph::DiGraph;
use reporting::Dep;
use reporting::Reportable;
mod graph;
#[cfg(feature = "lockapi")]
#[cfg_attr(docsrs, doc(cfg(feature = "lockapi")))]
#[cfg(any(feature = "lock_api", feature = "lockapi"))]
#[cfg_attr(docsrs, doc(cfg(feature = "lock_api")))]
#[cfg_attr(
all(not(docsrs), feature = "lockapi", not(feature = "lock_api")),
deprecated = "The `lockapi` feature has been renamed `lock_api`"
)]
pub mod lockapi;
#[cfg(feature = "parkinglot")]
#[cfg_attr(docsrs, doc(cfg(feature = "parkinglot")))]
#[cfg(any(feature = "parking_lot", feature = "parkinglot"))]
#[cfg_attr(docsrs, doc(cfg(feature = "parking_lot")))]
#[cfg_attr(
all(not(docsrs), feature = "parkinglot", not(feature = "parking_lot")),
deprecated = "The `parkinglot` feature has been renamed `parking_lot`"
)]
pub mod parkinglot;
mod reporting;
pub mod stdsync;
/// Counter for Mutex IDs. Atomic avoids the need for locking.
///
/// Should be part of the `MutexID` impl but static items are not yet a thing.
static ID_SEQUENCE: AtomicUsize = AtomicUsize::new(0);
pub mod util;
thread_local! {
/// Stack to track which locks are held
///
/// Assuming that locks are roughly released in the reverse order in which they were acquired,
/// a stack should be more efficient to keep track of the current state than a set would be.
static HELD_LOCKS: RefCell<Vec<usize>> = RefCell::new(Vec::new());
}
lazy_static! {
static ref DEPENDENCY_GRAPH: Mutex<DiGraph<usize>> = Default::default();
static HELD_LOCKS: RefCell<Vec<usize>> = const { RefCell::new(Vec::new()) };
}
/// Dedicated ID type for Mutexes
@@ -114,6 +142,9 @@ impl MutexId {
/// This function may panic when there are no more mutex IDs available. The number of mutex ids
/// is `usize::MAX - 1` which should be plenty for most practical applications.
pub fn new() -> Self {
// Counter for Mutex IDs. Atomic avoids the need for locking.
static ID_SEQUENCE: AtomicUsize = AtomicUsize::new(0);
ID_SEQUENCE
.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |id| id.checked_add(1))
.map(Self)
@@ -132,9 +163,12 @@ impl MutexId {
/// # Panics
///
/// This method panics if the new dependency would introduce a cycle.
pub fn get_borrowed(&self) -> BorrowedMutex {
pub fn get_borrowed(&self) -> BorrowedMutex<'_> {
self.mark_held();
BorrowedMutex(self)
BorrowedMutex {
id: self,
_not_send: PhantomData,
}
}
/// Mark this lock as held for the purposes of dependency tracking.
@@ -143,19 +177,18 @@ impl MutexId {
///
/// This method panics if the new dependency would introduce a cycle.
pub fn mark_held(&self) {
let creates_cycle = HELD_LOCKS.with(|locks| {
let opt_cycle = HELD_LOCKS.with(|locks| {
if let Some(&previous) = locks.borrow().last() {
let mut graph = get_dependency_graph();
!graph.add_edge(previous, self.value())
graph.add_edge(previous, self.value(), Dep::capture).err()
} else {
false
None
}
});
if creates_cycle {
// Panic without holding the lock to avoid needlessly poisoning it
panic!("Mutex order graph should not have cycles");
if let Some(cycle) = opt_cycle {
panic!("{}", Dep::panic_message(&cycle))
}
HELD_LOCKS.with(|locks| locks.borrow_mut().push(self.value()));
@@ -176,6 +209,14 @@ impl MutexId {
unreachable!("Tried to drop lock for mutex {:?} but it wasn't held", self)
});
}
/// Execute the given closure while the guard is held.
pub fn with_held<T>(&self, f: impl FnOnce() -> T) -> T {
// Note: we MUST construct the RAII guard, we cannot simply mark held + mark released, as
// f() may panic and corrupt our state.
let _guard = self.get_borrowed();
f()
}
}
impl Default for MutexId {
@@ -204,17 +245,13 @@ impl Drop for MutexId {
///
/// This type can be largely replaced once std::lazy gets stabilized.
struct LazyMutexId {
inner: UnsafeCell<MaybeUninit<MutexId>>,
setter: Once,
_marker: PhantomData<MutexId>,
inner: OnceLock<MutexId>,
}
impl LazyMutexId {
pub const fn new() -> Self {
Self {
inner: UnsafeCell::new(MaybeUninit::uninit()),
setter: Once::new(),
_marker: PhantomData,
inner: OnceLock::new(),
}
}
}
@@ -231,51 +268,30 @@ impl Default for LazyMutexId {
}
}
/// Safety: the UnsafeCell is guaranteed to only be accessed mutably from a `Once`.
unsafe impl Sync for LazyMutexId {}
impl Deref for LazyMutexId {
type Target = MutexId;
fn deref(&self) -> &Self::Target {
self.setter.call_once(|| {
// Safety: this function is only called once, so only one mutable reference should exist
// at a time.
unsafe {
*self.inner.get() = MaybeUninit::new(MutexId::new());
}
});
// Safety: after the above Once runs, there are no longer any mutable references, so we can
// hand this out safely.
//
// Explanation of this monstrosity:
//
// - Get a pointer to the data from the UnsafeCell
// - Dereference that to get a reference to the underlying MaybeUninit
// - Use as_ptr on MaybeUninit to get a pointer to the initialized MutexID
// - Dereference the pointer to turn in into a reference as intended.
//
// This should get slightly nicer once `maybe_uninit_extra` is stabilized.
unsafe { &*((*self.inner.get()).as_ptr()) }
}
}
impl Drop for LazyMutexId {
fn drop(&mut self) {
if self.setter.is_completed() {
// We have a valid mutex ID and need to drop it
// Safety: we know that this pointer is valid because the initializer has successfully run.
let mutex_id = unsafe { ptr::read((*self.inner.get()).as_ptr()) };
drop(mutex_id);
}
self.inner.get_or_init(MutexId::new)
}
}
/// Borrowed mutex ID
///
/// This type should be used as part of a mutex guard wrapper. It can be acquired through
/// [`MutexId::get_borrowed`] and will automatically mark the mutex as not borrowed when it is
/// dropped.
///
/// This type intentionally is [`!Send`](std::marker::Send) because the ownership tracking is based
/// on a thread-local stack which doesn't work if a guard gets released in a different thread from
/// where they're acquired.
#[derive(Debug)]
struct BorrowedMutex<'a>(&'a MutexId);
struct BorrowedMutex<'a> {
/// Reference to the mutex we're borrowing from
id: &'a MutexId,
/// This value serves no purpose but to make the type [`!Send`](std::marker::Send)
_not_send: PhantomData<MutexGuard<'static, ()>>,
}
/// Drop a lock held by the current thread.
///
@@ -283,16 +299,19 @@ struct BorrowedMutex<'a>(&'a MutexId);
///
/// This function panics if the lock did not appear to be handled by this thread. If that happens,
/// that is an indication of a serious design flaw in this library.
impl<'a> Drop for BorrowedMutex<'a> {
impl Drop for BorrowedMutex<'_> {
fn drop(&mut self) {
// Safety: the only way to get a BorrowedMutex is by locking the mutex.
unsafe { self.0.mark_released() };
unsafe { self.id.mark_released() };
}
}
/// Get a reference to the current dependency graph
fn get_dependency_graph() -> impl DerefMut<Target = DiGraph<usize>> {
fn get_dependency_graph() -> impl DerefMut<Target = DiGraph<usize, Dep>> {
static DEPENDENCY_GRAPH: OnceLock<Mutex<DiGraph<usize, Dep>>> = OnceLock::new();
DEPENDENCY_GRAPH
.get_or_init(Default::default)
.lock()
.unwrap_or_else(PoisonError::into_inner)
}
@@ -320,11 +339,11 @@ mod tests {
let c = LazyMutexId::new();
let mut graph = get_dependency_graph();
assert!(graph.add_edge(a.value(), b.value()));
assert!(graph.add_edge(b.value(), c.value()));
assert!(graph.add_edge(a.value(), b.value(), Dep::capture).is_ok());
assert!(graph.add_edge(b.value(), c.value(), Dep::capture).is_ok());
// Creating an edge c → a should fail as it introduces a cycle.
assert!(!graph.add_edge(c.value(), a.value()));
assert!(graph.add_edge(c.value(), a.value(), Dep::capture).is_err());
// Drop graph handle so we can drop vertices without deadlocking
drop(graph);
@@ -332,7 +351,11 @@ mod tests {
drop(b);
// If b's destructor correctly ran correctly we can now add an edge from c to a.
assert!(get_dependency_graph().add_edge(c.value(), a.value()));
assert!(
get_dependency_graph()
.add_edge(c.value(), a.value(), Dep::capture)
.is_ok()
);
}
/// Test creating a cycle, then panicking.

13
src/lockapi.rs
View File

@@ -8,6 +8,7 @@
//! Wrapped mutexes are at least one `usize` larger than the types they wrapped, and must be aligned
//! to `usize` boundaries. As such, libraries with many mutexes may want to consider the additional
//! required memory.
pub use lock_api as raw;
use lock_api::GuardNoSend;
use lock_api::RawMutex;
use lock_api::RawMutexFair;
@@ -24,6 +25,8 @@ use lock_api::RawRwLockUpgradeFair;
use lock_api::RawRwLockUpgradeTimed;
use crate::LazyMutexId;
use crate::MutexId;
use crate::util::PrivateTraced;
/// Tracing wrapper for all [`lock_api`] traits.
///
@@ -86,10 +89,18 @@ impl<T> TracingWrapper<T> {
}
}
impl<T> PrivateTraced for TracingWrapper<T> {
fn get_id(&self) -> &MutexId {
&self.id
}
}
unsafe impl<T> RawMutex for TracingWrapper<T>
where
T: RawMutex,
{
// Known issue with legacy initialisers, allow
#[allow(clippy::declare_interior_mutable_const)]
const INIT: Self = Self {
inner: T::INIT,
id: LazyMutexId::new(),
@@ -154,6 +165,8 @@ unsafe impl<T> RawRwLock for TracingWrapper<T>
where
T: RawRwLock,
{
// Known issue with legacy initialisers, allow
#[allow(clippy::declare_interior_mutable_const)]
const INIT: Self = Self {
inner: T::INIT,
id: LazyMutexId::new(),

289
src/parkinglot.rs
View File

@@ -1,19 +1,20 @@
//! Wrapper types and type aliases for tracing [`parking_lot`] mutexes.
//!
//! This module provides type aliases that use the [`lockapi`][crate::lockapi] module to provide
//! tracing variants of the `parking_lot` primitives. Each of the `TracingX` type aliases wraps an
//! `X` in the `parkint_lot` api with dependency tracking, and a `DebugX` will refer to a `TracingX`
//! when `debug_assertions` are enabled and to `X` when they're not. This can be used to aid
//! debugging in development while enjoying maximum performance in production.
//! tracing variants of the `parking_lot` primitives. The [`tracing`] module contains type aliases
//! that use dependency tracking, while the main `parking_lot` primitives are reexported as [`raw`].
//!
//! This main module imports from [`tracing`] when `debug_assertions` are enabled, and from [`raw`]
//! when they're not. Note that primitives for which no tracing wrapper exists are not imported into
//! the main module.
//!
//! # Usage
//!
//! ```
//! # use std::sync::Arc;
//! # use std::thread;
//! # use lock_api::Mutex;
//! # use tracing_mutex::parkinglot::TracingMutex;
//! let mutex = Arc::new(TracingMutex::new(0));
//! use tracing_mutex::parkinglot::Mutex;
//! let mutex = Arc::new(Mutex::new(0));
//!
//! let handles: Vec<_> = (0..10).map(|_| {
//! let mutex = Arc::clone(&mutex);
@@ -37,260 +38,32 @@
//! In addition, the mutex guards returned by the tracing wrappers are `!Send`, regardless of
//! whether `parking_lot` is configured to have `Send` mutex guards. This is a limitation of the
//! current bookkeeping system.
use parking_lot::Once;
use parking_lot::OnceState;
use crate::lockapi::TracingWrapper;
use crate::LazyMutexId;
pub use parking_lot as raw;
macro_rules! debug_variant {
($debug_name:ident, $tracing_name:ident, $normal_name:ty) => {
type $tracing_name = TracingWrapper<$normal_name>;
pub use parking_lot::OnceState;
pub use parking_lot::RawThreadId;
pub use parking_lot::WaitTimeoutResult;
#[cfg(debug_assertions)]
type $debug_name = TracingWrapper<$normal_name>;
#[cfg(not(debug_assertions))]
type $debug_name = $normal_name;
};
}
pub mod tracing;
debug_variant!(
DebugRawFairMutex,
TracingRawFairMutex,
parking_lot::RawFairMutex
);
debug_variant!(DebugRawMutex, TracingRawMutex, parking_lot::RawMutex);
debug_variant!(DebugRawRwLock, TracingRawRwLock, parking_lot::RawRwLock);
/// Dependency tracking fair mutex. See: [`parking_lot::FairMutex`].
pub type TracingFairMutex<T> = lock_api::Mutex<TracingRawFairMutex, T>;
/// Mutex guard for [`TracingFairMutex`].
pub type TracingFairMutexGuard<'a, T> = lock_api::MutexGuard<'a, TracingRawFairMutex, T>;
/// RAII guard for `TracingFairMutexGuard::map`.
pub type TracingMappedFairMutexGuard<'a, T> =
lock_api::MappedMutexGuard<'a, TracingRawFairMutex, T>;
/// Debug-only dependency tracking fair mutex.
///
/// If debug assertions are enabled this resolves to [`TracingFairMutex`] and to
/// [`parking_lot::FairMutex`] otherwise.
pub type DebugFairMutex<T> = lock_api::Mutex<DebugRawFairMutex, T>;
/// Mutex guard for [`DebugFairMutex`].
pub type DebugFairMutexGuard<'a, T> = lock_api::MutexGuard<'a, DebugRawFairMutex, T>;
/// RAII guard for `DebugFairMutexGuard::map`.
pub type DebugMappedFairMutexGuard<'a, T> = lock_api::MappedMutexGuard<'a, DebugRawFairMutex, T>;
/// Dependency tracking mutex. See: [`parking_lot::Mutex`].
pub type TracingMutex<T> = lock_api::Mutex<TracingRawMutex, T>;
/// Mutex guard for [`TracingMutex`].
pub type TracingMutexGuard<'a, T> = lock_api::MutexGuard<'a, TracingRawMutex, T>;
/// RAII guard for `TracingMutexGuard::map`.
pub type TracingMappedMutexGuard<'a, T> = lock_api::MappedMutexGuard<'a, TracingRawMutex, T>;
/// Debug-only dependency tracking mutex.
///
/// If debug assertions are enabled this resolves to [`TracingMutex`] and to [`parking_lot::Mutex`]
/// otherwise.
pub type DebugMutex<T> = lock_api::Mutex<DebugRawMutex, T>;
/// Mutex guard for [`DebugMutex`].
pub type DebugMutexGuard<'a, T> = lock_api::MutexGuard<'a, DebugRawMutex, T>;
/// RAII guard for `TracingMutexGuard::map`.
pub type DebugMappedMutexGuard<'a, T> = lock_api::MappedMutexGuard<'a, DebugRawMutex, T>;
/// Dependency tracking reentrant mutex. See: [`parking_lot::ReentrantMutex`].
///
/// **Note:** due to the way dependencies are tracked, this mutex can only be acquired directly
/// after itself. Acquiring any other mutex in between introduces a dependency cycle, and will
/// therefore be rejected.
pub type TracingReentrantMutex<T> =
lock_api::ReentrantMutex<TracingWrapper<parking_lot::RawMutex>, parking_lot::RawThreadId, T>;
/// Mutex guard for [`TracingReentrantMutex`].
pub type TracingReentrantMutexGuard<'a, T> = lock_api::ReentrantMutexGuard<
'a,
TracingWrapper<parking_lot::RawMutex>,
parking_lot::RawThreadId,
T,
>;
/// RAII guard for `TracingReentrantMutexGuard::map`.
pub type TracingMappedReentrantMutexGuard<'a, T> =
lock_api::MappedReentrantMutexGuard<'a, TracingRawMutex, parking_lot::RawThreadId, T>;
/// Debug-only dependency tracking reentrant mutex.
///
/// If debug assertions are enabled this resolves to [`TracingReentrantMutex`] and to
/// [`parking_lot::ReentrantMutex`] otherwise.
pub type DebugReentrantMutex<T> =
lock_api::ReentrantMutex<DebugRawMutex, parking_lot::RawThreadId, T>;
/// Mutex guard for [`DebugReentrantMutex`].
pub type DebugReentrantMutexGuard<'a, T> =
lock_api::ReentrantMutexGuard<'a, DebugRawMutex, parking_lot::RawThreadId, T>;
/// RAII guard for `DebugReentrantMutexGuard::map`.
pub type DebugMappedReentrantMutexGuard<'a, T> =
lock_api::MappedReentrantMutexGuard<'a, DebugRawMutex, parking_lot::RawThreadId, T>;
/// Dependency tracking RwLock. See: [`parking_lot::RwLock`].
pub type TracingRwLock<T> = lock_api::RwLock<TracingRawRwLock, T>;
/// Read guard for [`TracingRwLock`].
pub type TracingRwLockReadGuard<'a, T> = lock_api::RwLockReadGuard<'a, TracingRawRwLock, T>;
/// Upgradable Read guard for [`TracingRwLock`].
pub type TracingRwLockUpgradableReadGuard<'a, T> =
lock_api::RwLockUpgradableReadGuard<'a, TracingRawRwLock, T>;
/// Write guard for [`TracingRwLock`].
pub type TracingRwLockWriteGuard<'a, T> = lock_api::RwLockWriteGuard<'a, TracingRawRwLock, T>;
/// RAII guard for `TracingRwLockReadGuard::map`.
pub type TracingMappedRwLockReadGuard<'a, T> =
lock_api::MappedRwLockReadGuard<'a, TracingRawRwLock, T>;
/// RAII guard for `TracingRwLockWriteGuard::map`.
pub type TracingMappedRwLockWriteGuard<'a, T> =
lock_api::MappedRwLockWriteGuard<'a, TracingRawRwLock, T>;
/// Debug-only dependency tracking RwLock.
///
/// If debug assertions are enabled this resolved to [`TracingRwLock`] and to
/// [`parking_lot::RwLock`] otherwise.
pub type DebugRwLock<T> = lock_api::RwLock<DebugRawRwLock, T>;
/// Read guard for [`TracingRwLock`].
pub type DebugRwLockReadGuard<'a, T> = lock_api::RwLockReadGuard<'a, DebugRawRwLock, T>;
/// Upgradable Read guard for [`TracingRwLock`].
pub type DebugRwLockUpgradableReadGuard<'a, T> =
lock_api::RwLockUpgradableReadGuard<'a, DebugRawRwLock, T>;
/// Write guard for [`TracingRwLock`].
pub type DebugRwLockWriteGuard<'a, T> = lock_api::RwLockWriteGuard<'a, DebugRawRwLock, T>;
/// RAII guard for `DebugRwLockReadGuard::map`.
pub type DebugMappedRwLockReadGuard<'a, T> = lock_api::MappedRwLockReadGuard<'a, DebugRawRwLock, T>;
/// RAII guard for `DebugRwLockWriteGuard::map`.
pub type DebugMappedRwLockWriteGuard<'a, T> =
lock_api::MappedRwLockWriteGuard<'a, DebugRawRwLock, T>;
/// A dependency-tracking wrapper for [`parking_lot::Once`].
#[derive(Debug, Default)]
pub struct TracingOnce {
inner: Once,
id: LazyMutexId,
}
impl TracingOnce {
/// Create a new `TracingOnce` value.
pub const fn new() -> Self {
Self {
inner: Once::new(),
id: LazyMutexId::new(),
}
}
/// Returns the current state of this `Once`.
pub fn state(&self) -> OnceState {
self.inner.state()
}
///
/// This call is considered as "locking this `TracingOnce`" and it participates in dependency
/// tracking as such.
///
/// # Panics
///
/// This method will panic if `f` panics, poisoning this `Once`. In addition, this function
/// panics when the lock acquisition order is determined to be inconsistent.
pub fn call_once(&self, f: impl FnOnce()) {
let _borrow = self.id.get_borrowed();
self.inner.call_once(f);
}
/// Performs the given initialization routine once and only once.
///
/// 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);
}
}
/// Debug-only `Once`.
///
/// If debug assertions are enabled this resolves to [`TracingOnce`] and to [`parking_lot::Once`]
/// otherwise.
// Skip reformatting the combined imports as it duplicates the guards
#[rustfmt::skip]
#[cfg(debug_assertions)]
pub type DebugOnce = TracingOnce;
pub use tracing::{
FairMutex, FairMutexGuard, MappedFairMutexGuard, MappedMutexGuard, MappedReentrantMutexGuard,
MappedRwLockReadGuard, MappedRwLockWriteGuard, Mutex, MutexGuard, Once, RawFairMutex, RawMutex,
RawRwLock, ReentrantMutex, ReentrantMutexGuard, RwLock, RwLockReadGuard,
RwLockUpgradableReadGuard, RwLockWriteGuard, const_fair_mutex, const_mutex,
const_reentrant_mutex, const_rwlock,
};
#[rustfmt::skip]
#[cfg(not(debug_assertions))]
pub type DebugOnce = Once;
#[cfg(test)]
mod tests {
use std::sync::Arc;
use std::thread;
use super::*;
#[test]
fn test_mutex_usage() {
let mutex = Arc::new(TracingMutex::new(()));
let local_lock = mutex.lock();
drop(local_lock);
thread::spawn(move || {
let _remote_lock = mutex.lock();
})
.join()
.unwrap();
}
#[test]
#[should_panic]
fn test_mutex_conflict() {
let mutexes = [
TracingMutex::new(()),
TracingMutex::new(()),
TracingMutex::new(()),
];
for i in 0..3 {
let _first_lock = mutexes[i].lock();
let _second_lock = mutexes[(i + 1) % 3].lock();
}
}
#[test]
fn test_rwlock_usage() {
let lock = Arc::new(TracingRwLock::new(()));
let lock2 = Arc::clone(&lock);
let _read_lock = lock.read();
// Should be able to acquire lock in the background
thread::spawn(move || {
let _read_lock = lock2.read();
})
.join()
.unwrap();
}
#[test]
fn test_rwlock_upgradable_read_usage() {
let lock = TracingRwLock::new(());
// Should be able to acquire an upgradable read lock.
let upgradable_guard: TracingRwLockUpgradableReadGuard<'_, _> = lock.upgradable_read();
// Should be able to upgrade the guard.
let _write_guard: TracingRwLockWriteGuard<'_, _> =
TracingRwLockUpgradableReadGuard::upgrade(upgradable_guard);
}
#[test]
fn test_once_usage() {
let once = Arc::new(TracingOnce::new());
let once_clone = once.clone();
assert!(!once_clone.state().done());
let handle = thread::spawn(move || {
assert!(!once_clone.state().done());
once_clone.call_once(|| {});
assert!(once_clone.state().done());
});
handle.join().unwrap();
assert!(once.state().done());
}
}
pub use parking_lot::{
FairMutex, FairMutexGuard, MappedFairMutexGuard, MappedMutexGuard, MappedReentrantMutexGuard,
MappedRwLockReadGuard, MappedRwLockWriteGuard, Mutex, MutexGuard, Once, RawFairMutex, RawMutex,
RawRwLock, ReentrantMutex, ReentrantMutexGuard, RwLock, RwLockReadGuard,
RwLockUpgradableReadGuard, RwLockWriteGuard, const_fair_mutex, const_mutex,
const_reentrant_mutex, const_rwlock,
};

193
src/parkinglot/tracing.rs Normal file
View File

@@ -0,0 +1,193 @@
//! Dependency tracing wrappers for [`::parking_lot`].
pub use parking_lot::OnceState;
pub use parking_lot::RawThreadId;
use crate::LazyMutexId;
use crate::lockapi::TracingWrapper;
pub type RawFairMutex = TracingWrapper<::parking_lot::RawFairMutex>;
pub type RawMutex = TracingWrapper<::parking_lot::RawMutex>;
pub type RawRwLock = TracingWrapper<::parking_lot::RawRwLock>;
/// Dependency tracking fair mutex. See: [`::parking_lot::FairMutex`].
pub type FairMutex<T> = lock_api::Mutex<RawFairMutex, T>;
/// Mutex guard for [`FairMutex`].
pub type FairMutexGuard<'a, T> = lock_api::MutexGuard<'a, RawFairMutex, T>;
/// RAII guard for [`FairMutexGuard::map`].
pub type MappedFairMutexGuard<'a, T> = lock_api::MappedMutexGuard<'a, RawFairMutex, T>;
/// Dependency tracking mutex. See: [`::parking_lot::Mutex`].
pub type Mutex<T> = lock_api::Mutex<RawMutex, T>;
/// Mutex guard for [`Mutex`].
pub type MutexGuard<'a, T> = lock_api::MutexGuard<'a, RawMutex, T>;
/// RAII guard for [`MutexGuard::map`].
pub type MappedMutexGuard<'a, T> = lock_api::MappedMutexGuard<'a, RawMutex, T>;
/// Dependency tracking reentrant mutex. See: [`::parking_lot::ReentrantMutex`].
///
/// **Note:** due to the way dependencies are tracked, this mutex can only be acquired directly
/// after itself. Acquiring any other mutex in between introduces a dependency cycle, and will
/// therefore be rejected.
pub type ReentrantMutex<T> = lock_api::ReentrantMutex<RawMutex, parking_lot::RawThreadId, T>;
/// Mutex guard for [`ReentrantMutex`].
pub type ReentrantMutexGuard<'a, T> =
lock_api::ReentrantMutexGuard<'a, RawMutex, parking_lot::RawThreadId, T>;
/// RAII guard for `ReentrantMutexGuard::map`.
pub type MappedReentrantMutexGuard<'a, T> =
lock_api::MappedReentrantMutexGuard<'a, RawMutex, parking_lot::RawThreadId, T>;
/// Dependency tracking RwLock. See: [`::parking_lot::RwLock`].
pub type RwLock<T> = lock_api::RwLock<RawRwLock, T>;
/// Read guard for [`RwLock`].
pub type RwLockReadGuard<'a, T> = lock_api::RwLockReadGuard<'a, RawRwLock, T>;
/// Upgradable Read guard for [`RwLock`].
pub type RwLockUpgradableReadGuard<'a, T> = lock_api::RwLockUpgradableReadGuard<'a, RawRwLock, T>;
/// Write guard for [`RwLock`].
pub type RwLockWriteGuard<'a, T> = lock_api::RwLockWriteGuard<'a, RawRwLock, T>;
/// RAII guard for `RwLockReadGuard::map`.
pub type MappedRwLockReadGuard<'a, T> = lock_api::MappedRwLockReadGuard<'a, RawRwLock, T>;
/// RAII guard for `RwLockWriteGuard::map`.
pub type MappedRwLockWriteGuard<'a, T> = lock_api::MappedRwLockWriteGuard<'a, RawRwLock, T>;
/// A dependency-tracking wrapper for [`::parking_lot::Once`].
#[derive(Debug, Default)]
pub struct Once {
inner: ::parking_lot::Once,
id: LazyMutexId,
}
impl Once {
/// Create a new `Once` value.
pub const fn new() -> Self {
Self {
inner: ::parking_lot::Once::new(),
id: LazyMutexId::new(),
}
}
/// Returns the current state of this `Once`.
pub fn state(&self) -> OnceState {
self.inner.state()
}
/// This call is considered as "locking this `Once`" and it participates in dependency
/// tracking as such.
///
/// # Panics
///
/// This method will panic if `f` panics, poisoning this `Once`. In addition, this function
/// panics when the lock acquisition order is determined to be inconsistent.
pub fn call_once(&self, f: impl FnOnce()) {
self.id.with_held(|| self.inner.call_once(f));
}
/// Performs the given initialization routine once and only once.
///
/// This method is identical to [`Once::call_once`] except it ignores poisoning.
pub fn call_once_force(&self, f: impl FnOnce(OnceState)) {
self.id.with_held(|| self.inner.call_once_force(f));
}
}
/// Creates a new fair mutex in an unlocked state ready for use.
pub const fn const_fair_mutex<T>(val: T) -> FairMutex<T> {
FairMutex::const_new(<RawFairMutex as lock_api::RawMutex>::INIT, val)
}
/// Creates a new mutex in an unlocked state ready for use.
pub const fn const_mutex<T>(val: T) -> Mutex<T> {
Mutex::const_new(<RawMutex as lock_api::RawMutex>::INIT, val)
}
/// Creates a new reentrant mutex in an unlocked state ready for use.
pub const fn const_reentrant_mutex<T>(val: T) -> ReentrantMutex<T> {
ReentrantMutex::const_new(
<RawMutex as lock_api::RawMutex>::INIT,
<RawThreadId as lock_api::GetThreadId>::INIT,
val,
)
}
/// Creates a new rwlock in an unlocked state ready for use.
pub const fn const_rwlock<T>(val: T) -> RwLock<T> {
RwLock::const_new(<RawRwLock as lock_api::RawRwLock>::INIT, val)
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use std::thread;
use super::*;
#[test]
fn test_mutex_usage() {
let mutex = Arc::new(Mutex::new(()));
let local_lock = mutex.lock();
drop(local_lock);
thread::spawn(move || {
let _remote_lock = mutex.lock();
})
.join()
.unwrap();
}
#[test]
#[should_panic]
fn test_mutex_conflict() {
let mutexes = [Mutex::new(()), Mutex::new(()), Mutex::new(())];
for i in 0..3 {
let _first_lock = mutexes[i].lock();
let _second_lock = mutexes[(i + 1) % 3].lock();
}
}
#[test]
fn test_rwlock_usage() {
let lock = Arc::new(RwLock::new(()));
let lock2 = Arc::clone(&lock);
let _read_lock = lock.read();
// Should be able to acquire lock in the background
thread::spawn(move || {
let _read_lock = lock2.read();
})
.join()
.unwrap();
}
#[test]
fn test_rwlock_upgradable_read_usage() {
let lock = RwLock::new(());
// Should be able to acquire an upgradable read lock.
let upgradable_guard: RwLockUpgradableReadGuard<'_, _> = lock.upgradable_read();
// Should be able to upgrade the guard.
let _write_guard: RwLockWriteGuard<'_, _> =
RwLockUpgradableReadGuard::upgrade(upgradable_guard);
}
#[test]
fn test_once_usage() {
let once = Arc::new(Once::new());
let once_clone = once.clone();
assert!(!once_clone.state().done());
let handle = thread::spawn(move || {
assert!(!once_clone.state().done());
once_clone.call_once(|| {});
assert!(once_clone.state().done());
});
handle.join().unwrap();
assert!(once.state().done());
}
}

64
src/reporting.rs Normal file
View File

@@ -0,0 +1,64 @@
//! Cycle reporting primitives
//!
//! This module exposes [`Dep`], which resolves to either something that tracks dependencies or to
//! something that doesn't. It should only be assumed to implement the [`Reportable`] trait.
use std::backtrace::Backtrace;
use std::borrow::Cow;
use std::fmt::Write;
use std::sync::Arc;
#[cfg(feature = "backtraces")]
pub type Dep = MutexDep<Arc<Backtrace>>;
#[cfg(not(feature = "backtraces"))]
pub type Dep = MutexDep<()>;
// Base message to be reported when cycle is detected
const BASE_MESSAGE: &str = "Found cycle in mutex dependency graph:";
pub trait Reportable: Clone {
/// Capture the current state
fn capture() -> Self;
/// Format a trace of state for human readable consumption.
fn panic_message(trace: &[Self]) -> Cow<'static, str>;
}
#[derive(Clone)]
pub struct MutexDep<T>(T);
/// Use a unit as tracing data: no tracing.
///
/// This should have no runtime overhead for capturing traces and should therefore be cheap enough
/// for most purposes.
impl Reportable for MutexDep<()> {
fn capture() -> Self {
Self(())
}
fn panic_message(_trace: &[Self]) -> Cow<'static, str> {
Cow::Borrowed(BASE_MESSAGE)
}
}
/// Use a full backtrace as tracing data
///
/// Capture the entire backtrace which may be expensive. This implementation does not force capture
/// in the event that backtraces are disabled at runtime, so the exact overhead can still be
/// controlled a little.
///
/// N.B. the [`Backtrace`] needs to be wrapped in an Arc as backtraces are not [`Clone`].
impl Reportable for MutexDep<Arc<Backtrace>> {
fn capture() -> Self {
Self(Arc::new(Backtrace::capture()))
}
fn panic_message(trace: &[Self]) -> Cow<'static, str> {
let mut message = format!("{BASE_MESSAGE}\n");
for entry in trace {
let _ = writeln!(message, "{}", entry.0);
}
message.into()
}
}

636
src/stdsync.rs
View File

@@ -1,625 +1,43 @@
//! Tracing mutex wrappers for locks found in `std::sync`.
//!
//! This module provides wrappers for `std::sync` primitives with exactly the same API and
//! functionality as their counterparts, with the exception that their acquisition order is
//! tracked.
//! functionality as their counterparts, with the exception that their acquisition order is tracked.
//!
//! Dedicated wrappers that provide the dependency tracing can be found in the [`tracing`] module.
//! The original primitives are available from [`std::sync`], imported as [`raw`] for convenience.
//!
//! If debug assertions are enabled, this module imports the primitives from [`tracing`], otherwise
//! it will import from [`raw`].
//!
//! ```rust
//! # use tracing_mutex::stdsync::TracingMutex;
//! # use tracing_mutex::stdsync::TracingRwLock;
//! let mutex = TracingMutex::new(());
//! # use tracing_mutex::stdsync::tracing::Mutex;
//! # use tracing_mutex::stdsync::tracing::RwLock;
//! let mutex = Mutex::new(());
//! mutex.lock().unwrap();
//!
//! let rwlock = TracingRwLock::new(());
//! let rwlock = RwLock::new(());
//! rwlock.read().unwrap();
//! ```
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;
use std::sync::Once;
use std::sync::OnceState;
use std::sync::PoisonError;
use std::sync::RwLock;
use std::sync::RwLockReadGuard;
use std::sync::RwLockWriteGuard;
use std::sync::TryLockError;
use std::sync::TryLockResult;
use std::sync::WaitTimeoutResult;
use std::time::Duration;
pub use std::sync as raw;
use crate::BorrowedMutex;
use crate::LazyMutexId;
use crate::MutexId;
/// Debug-only tracing `Mutex`.
///
/// Type alias that resolves to [`TracingMutex`] when debug assertions are enabled and to
/// [`std::sync::Mutex`] when they're not. Use this if you want to have the benefits of cycle
/// detection in development but do not want to pay the performance penalty in release.
#[cfg(debug_assertions)]
pub type DebugMutex<T> = TracingMutex<T>;
// Skip reformatting the combined imports as it duplicates the guards
#[rustfmt::skip]
#[cfg(not(debug_assertions))]
pub type DebugMutex<T> = Mutex<T>;
pub use std::sync::{
Condvar, Mutex, MutexGuard, Once, OnceLock, RwLock, RwLockReadGuard, RwLockWriteGuard,
};
/// Mutex guard for [`DebugMutex`].
#[rustfmt::skip]
#[cfg(debug_assertions)]
pub type DebugMutexGuard<'a, T> = TracingMutexGuard<'a, T>;
#[cfg(not(debug_assertions))]
pub type DebugMutexGuard<'a, T> = MutexGuard<'a, T>;
pub use tracing::{
Condvar, Mutex, MutexGuard, Once, OnceLock, RwLock, RwLockReadGuard, RwLockWriteGuard,
};
/// 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;
#[cfg(all(has_std__sync__LazyLock, debug_assertions))]
pub use tracing::LazyLock;
/// Debug-only tracing `RwLock`.
///
/// Type alias that resolves to [`TracingRwLock`] when debug assertions are enabled and to
/// [`std::sync::RwLock`] when they're not. Use this if you want to have the benefits of cycle
/// detection in development but do not want to pay the performance penalty in release.
#[cfg(debug_assertions)]
pub type DebugRwLock<T> = TracingRwLock<T>;
#[cfg(not(debug_assertions))]
pub type DebugRwLock<T> = RwLock<T>;
#[cfg(all(has_std__sync__LazyLock, not(debug_assertions)))]
pub use std::sync::LazyLock;
/// Read guard for [`DebugRwLock`].
#[cfg(debug_assertions)]
pub type DebugReadGuard<'a, T> = TracingReadGuard<'a, T>;
#[cfg(not(debug_assertions))]
pub type DebugReadGuard<'a, T> = RwLockReadGuard<'a, T>;
/// Write guard for [`DebugRwLock`].
#[cfg(debug_assertions)]
pub type DebugWriteGuard<'a, T> = TracingWriteGuard<'a, T>;
#[cfg(not(debug_assertions))]
pub type DebugWriteGuard<'a, T> = RwLockWriteGuard<'a, T>;
/// Debug-only tracing `Once`.
///
/// Type alias that resolves to [`TracingOnce`] when debug assertions are enabled and to
/// [`std::sync::Once`] when they're not. Use this if you want to have the benefits of cycle
/// detection in development but do not want to pay the performance penalty in release.
#[cfg(debug_assertions)]
pub type DebugOnce = TracingOnce;
#[cfg(not(debug_assertions))]
pub type DebugOnce = Once;
/// Wrapper for [`std::sync::Mutex`].
///
/// Refer to the [crate-level][`crate`] documentaiton for the differences between this struct and
/// the one it wraps.
#[derive(Debug, Default)]
pub struct TracingMutex<T> {
inner: Mutex<T>,
id: MutexId,
}
/// Wrapper for [`std::sync::MutexGuard`].
///
/// Refer to the [crate-level][`crate`] documentaiton for the differences between this struct and
/// the one it wraps.
#[derive(Debug)]
pub struct TracingMutexGuard<'a, T> {
inner: MutexGuard<'a, T>,
_mutex: BorrowedMutex<'a>,
}
fn map_lockresult<T, I, F>(result: LockResult<I>, mapper: F) -> LockResult<T>
where
F: FnOnce(I) -> T,
{
match result {
Ok(inner) => Ok(mapper(inner)),
Err(poisoned) => Err(PoisonError::new(mapper(poisoned.into_inner()))),
}
}
fn map_trylockresult<T, I, F>(result: TryLockResult<I>, mapper: F) -> TryLockResult<T>
where
F: FnOnce(I) -> T,
{
match result {
Ok(inner) => Ok(mapper(inner)),
Err(TryLockError::WouldBlock) => Err(TryLockError::WouldBlock),
Err(TryLockError::Poisoned(poisoned)) => {
Err(PoisonError::new(mapper(poisoned.into_inner())).into())
}
}
}
impl<T> TracingMutex<T> {
/// Create a new tracing mutex with the provided value.
pub fn new(t: T) -> Self {
Self {
inner: Mutex::new(t),
id: MutexId::new(),
}
}
/// Wrapper for [`std::sync::Mutex::lock`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn lock(&self) -> LockResult<TracingMutexGuard<T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.lock();
let mapper = |guard| TracingMutexGuard {
_mutex: mutex,
inner: guard,
};
map_lockresult(result, mapper)
}
/// Wrapper for [`std::sync::Mutex::try_lock`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn try_lock(&self) -> TryLockResult<TracingMutexGuard<T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.try_lock();
let mapper = |guard| TracingMutexGuard {
_mutex: mutex,
inner: guard,
};
map_trylockresult(result, mapper)
}
/// Wrapper for [`std::sync::Mutex::is_poisoned`].
pub fn is_poisoned(&self) -> bool {
self.inner.is_poisoned()
}
/// Return a mutable reference to the underlying data.
///
/// This method does not block as the locking is handled compile-time by the type system.
pub fn get_mut(&mut self) -> LockResult<&mut T> {
self.inner.get_mut()
}
/// Unwrap the mutex and return its inner value.
pub fn into_inner(self) -> LockResult<T> {
self.inner.into_inner()
}
}
impl<T> From<T> for TracingMutex<T> {
fn from(t: T) -> Self {
Self::new(t)
}
}
impl<'a, T> Deref for TracingMutexGuard<'a, T> {
type Target = T;
fn deref(&self) -> &Self::Target {
&self.inner
}
}
impl<'a, T> DerefMut for TracingMutexGuard<'a, T> {
fn deref_mut(&mut self) -> &mut Self::Target {
&mut self.inner
}
}
impl<'a, T: fmt::Display> fmt::Display for TracingMutexGuard<'a, T> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.inner.fmt(f)
}
}
/// 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> {
inner: RwLock<T>,
id: MutexId,
}
/// Hybrid wrapper for both [`std::sync::RwLockReadGuard`] and [`std::sync::RwLockWriteGuard`].
///
/// Please refer to [`TracingReadGuard`] and [`TracingWriteGuard`] for usable types.
#[derive(Debug)]
pub struct TracingRwLockGuard<'a, L> {
inner: L,
_mutex: BorrowedMutex<'a>,
}
/// Wrapper around [`std::sync::RwLockReadGuard`].
pub type TracingReadGuard<'a, T> = TracingRwLockGuard<'a, RwLockReadGuard<'a, T>>;
/// Wrapper around [`std::sync::RwLockWriteGuard`].
pub type TracingWriteGuard<'a, T> = TracingRwLockGuard<'a, RwLockWriteGuard<'a, T>>;
impl<T> TracingRwLock<T> {
pub fn new(t: T) -> Self {
Self {
inner: RwLock::new(t),
id: MutexId::new(),
}
}
/// Wrapper for [`std::sync::RwLock::read`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn read(&self) -> LockResult<TracingReadGuard<T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.read();
map_lockresult(result, |inner| TracingRwLockGuard {
inner,
_mutex: mutex,
})
}
/// Wrapper for [`std::sync::RwLock::write`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn write(&self) -> LockResult<TracingWriteGuard<T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.write();
map_lockresult(result, |inner| TracingRwLockGuard {
inner,
_mutex: mutex,
})
}
/// Wrapper for [`std::sync::RwLock::try_read`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn try_read(&self) -> TryLockResult<TracingReadGuard<T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.try_read();
map_trylockresult(result, |inner| TracingRwLockGuard {
inner,
_mutex: mutex,
})
}
/// Wrapper for [`std::sync::RwLock::try_write`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn try_write(&self) -> TryLockResult<TracingWriteGuard<T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.try_write();
map_trylockresult(result, |inner| TracingRwLockGuard {
inner,
_mutex: mutex,
})
}
/// Return a mutable reference to the underlying data.
///
/// This method does not block as the locking is handled compile-time by the type system.
pub fn get_mut(&mut self) -> LockResult<&mut T> {
self.inner.get_mut()
}
/// Unwrap the mutex and return its inner value.
pub fn into_inner(self) -> LockResult<T> {
self.inner.into_inner()
}
}
impl<T> From<T> for TracingRwLock<T> {
fn from(t: T) -> Self {
Self::new(t)
}
}
impl<'a, L, T> Deref for TracingRwLockGuard<'a, L>
where
L: Deref<Target = T>,
{
type Target = T;
fn deref(&self) -> &Self::Target {
self.inner.deref()
}
}
impl<'a, T, L> DerefMut for TracingRwLockGuard<'a, L>
where
L: Deref<Target = T> + DerefMut,
{
fn deref_mut(&mut self) -> &mut Self::Target {
self.inner.deref_mut()
}
}
/// Wrapper around [`std::sync::Once`].
///
/// Refer to the [crate-level][`crate`] documentaiton for the differences between this struct and
/// the one it wraps.
#[derive(Debug)]
pub struct TracingOnce {
inner: Once,
mutex_id: LazyMutexId,
}
impl TracingOnce {
/// Create a new `Once` value.
pub const fn new() -> Self {
Self {
inner: Once::new(),
mutex_id: LazyMutexId::new(),
}
}
/// Wrapper for [`std::sync::Once::call_once`].
///
/// # Panics
///
/// In addition to the panics that `Once` can cause, this method will panic if calling it
/// introduces a cycle in the lock dependency graph.
pub fn call_once<F>(&self, f: F)
where
F: FnOnce(),
{
let _guard = self.mutex_id.get_borrowed();
self.inner.call_once(f);
}
/// Performs the same operation as [`call_once`][TracingOnce::call_once] except it ignores
/// poisoning.
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
pub fn call_once_force<F>(&self, f: F)
where
F: FnOnce(&OnceState),
{
let _guard = self.mutex_id.get_borrowed();
self.inner.call_once_force(f);
}
/// Returns true if some `call_once` has completed successfully.
pub fn is_completed(&self) -> bool {
self.inner.is_completed()
}
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use std::thread;
use super::*;
#[test]
fn test_mutex_usage() {
let mutex = Arc::new(TracingMutex::new(0));
assert_eq!(*mutex.lock().unwrap(), 0);
*mutex.lock().unwrap() = 1;
assert_eq!(*mutex.lock().unwrap(), 1);
let mutex_clone = mutex.clone();
let _guard = mutex.lock().unwrap();
// Now try to cause a blocking exception in another thread
let handle = thread::spawn(move || {
let result = mutex_clone.try_lock().unwrap_err();
assert!(matches!(result, TryLockError::WouldBlock));
});
handle.join().unwrap();
}
#[test]
fn test_rwlock_usage() {
let rwlock = Arc::new(TracingRwLock::new(0));
assert_eq!(*rwlock.read().unwrap(), 0);
assert_eq!(*rwlock.write().unwrap(), 0);
*rwlock.write().unwrap() = 1;
assert_eq!(*rwlock.read().unwrap(), 1);
assert_eq!(*rwlock.write().unwrap(), 1);
let rwlock_clone = rwlock.clone();
let _read_lock = rwlock.read().unwrap();
// Now try to cause a blocking exception in another thread
let handle = thread::spawn(move || {
let write_result = rwlock_clone.try_write().unwrap_err();
assert!(matches!(write_result, TryLockError::WouldBlock));
// Should be able to get a read lock just fine.
let _read_lock = rwlock_clone.read().unwrap();
});
handle.join().unwrap();
}
#[test]
fn test_once_usage() {
let once = Arc::new(TracingOnce::new());
let once_clone = once.clone();
assert!(!once.is_completed());
let handle = thread::spawn(move || {
assert!(!once_clone.is_completed());
once_clone.call_once(|| {});
assert!(once_clone.is_completed());
});
handle.join().unwrap();
assert!(once.is_completed());
}
#[test]
#[should_panic(expected = "Mutex order graph should not have cycles")]
fn test_detect_cycle() {
let a = TracingMutex::new(());
let b = TracingMutex::new(());
let hold_a = a.lock().unwrap();
let _ = b.lock();
drop(hold_a);
let _hold_b = b.lock().unwrap();
let _ = a.lock();
}
}
/// Dependency tracing versions of [`std::sync`].
pub mod tracing;

748
src/stdsync/tracing.rs Normal file
View File

@@ -0,0 +1,748 @@
use std::fmt;
use std::ops::Deref;
use std::ops::DerefMut;
use std::sync;
use std::sync::LockResult;
use std::sync::OnceState;
use std::sync::PoisonError;
use std::sync::TryLockError;
use std::sync::TryLockResult;
use std::sync::WaitTimeoutResult;
use std::time::Duration;
use crate::BorrowedMutex;
use crate::LazyMutexId;
use crate::util::PrivateTraced;
#[cfg(has_std__sync__LazyLock)]
pub use lazy_lock::LazyLock;
#[cfg(has_std__sync__LazyLock)]
mod lazy_lock;
/// Wrapper for [`std::sync::Mutex`].
///
/// Refer to the [crate-level][`crate`] documentation for the differences between this struct and
/// the one it wraps.
#[derive(Debug, Default)]
pub struct Mutex<T: ?Sized> {
id: LazyMutexId,
inner: sync::Mutex<T>,
}
/// Wrapper for [`std::sync::MutexGuard`].
///
/// Refer to the [crate-level][`crate`] documentation for the differences between this struct and
/// the one it wraps.
pub struct MutexGuard<'a, T: ?Sized> {
inner: sync::MutexGuard<'a, T>,
_mutex: BorrowedMutex<'a>,
}
fn map_lockresult<T, I, F>(result: LockResult<I>, mapper: F) -> LockResult<T>
where
F: FnOnce(I) -> T,
{
match result {
Ok(inner) => Ok(mapper(inner)),
Err(poisoned) => Err(PoisonError::new(mapper(poisoned.into_inner()))),
}
}
fn map_trylockresult<T, I, F>(result: TryLockResult<I>, mapper: F) -> TryLockResult<T>
where
F: FnOnce(I) -> T,
{
match result {
Ok(inner) => Ok(mapper(inner)),
Err(TryLockError::WouldBlock) => Err(TryLockError::WouldBlock),
Err(TryLockError::Poisoned(poisoned)) => {
Err(PoisonError::new(mapper(poisoned.into_inner())).into())
}
}
}
impl<T> Mutex<T> {
/// Create a new tracing mutex with the provided value.
pub const fn new(t: T) -> Self {
Self {
inner: sync::Mutex::new(t),
id: LazyMutexId::new(),
}
}
}
impl<T: ?Sized> Mutex<T> {
/// Wrapper for [`std::sync::Mutex::lock`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn lock(&self) -> LockResult<MutexGuard<'_, T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.lock();
let mapper = |guard| MutexGuard {
_mutex: mutex,
inner: guard,
};
map_lockresult(result, mapper)
}
/// Wrapper for [`std::sync::Mutex::try_lock`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn try_lock(&self) -> TryLockResult<MutexGuard<'_, T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.try_lock();
let mapper = |guard| MutexGuard {
_mutex: mutex,
inner: guard,
};
map_trylockresult(result, mapper)
}
/// Wrapper for [`std::sync::Mutex::is_poisoned`].
pub fn is_poisoned(&self) -> bool {
self.inner.is_poisoned()
}
/// Return a mutable reference to the underlying data.
///
/// This method does not block as the locking is handled compile-time by the type system.
pub fn get_mut(&mut self) -> LockResult<&mut T> {
self.inner.get_mut()
}
/// Unwrap the mutex and return its inner value.
pub fn into_inner(self) -> LockResult<T>
where
T: Sized,
{
self.inner.into_inner()
}
}
impl<T: ?Sized> PrivateTraced for Mutex<T> {
fn get_id(&self) -> &crate::MutexId {
&self.id
}
}
impl<T> From<T> for Mutex<T> {
fn from(t: T) -> Self {
Self::new(t)
}
}
impl<T: ?Sized> Deref for MutexGuard<'_, T> {
type Target = T;
#[inline]
fn deref(&self) -> &Self::Target {
&self.inner
}
}
impl<T: ?Sized> DerefMut for MutexGuard<'_, T> {
#[inline]
fn deref_mut(&mut self) -> &mut Self::Target {
&mut self.inner
}
}
impl<T: ?Sized + fmt::Debug> fmt::Debug for MutexGuard<'_, T> {
#[inline]
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.inner.fmt(f)
}
}
impl<T: fmt::Display + ?Sized> fmt::Display for MutexGuard<'_, T> {
#[inline]
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.inner.fmt(f)
}
}
/// 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::tracing::{Condvar, Mutex};
///
/// let pair = Arc::new((Mutex::new(false), Condvar::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 Condvar(sync::Condvar);
impl Condvar {
/// Creates a new condition variable which is ready to be waited on and notified.
pub const fn new() -> Self {
Self(sync::Condvar::new())
}
/// Wrapper for [`std::sync::Condvar::wait`].
pub fn wait<'a, T>(&self, guard: MutexGuard<'a, T>) -> LockResult<MutexGuard<'a, T>> {
let MutexGuard { _mutex, inner } = guard;
map_lockresult(self.0.wait(inner), |inner| MutexGuard { _mutex, inner })
}
/// Wrapper for [`std::sync::Condvar::wait_while`].
pub fn wait_while<'a, T, F>(
&self,
guard: MutexGuard<'a, T>,
condition: F,
) -> LockResult<MutexGuard<'a, T>>
where
F: FnMut(&mut T) -> bool,
{
let MutexGuard { _mutex, inner } = guard;
map_lockresult(self.0.wait_while(inner, condition), |inner| MutexGuard {
_mutex,
inner,
})
}
/// Wrapper for [`std::sync::Condvar::wait_timeout`].
pub fn wait_timeout<'a, T>(
&self,
guard: MutexGuard<'a, T>,
dur: Duration,
) -> LockResult<(MutexGuard<'a, T>, WaitTimeoutResult)> {
let MutexGuard { _mutex, inner } = guard;
map_lockresult(self.0.wait_timeout(inner, dur), |(inner, result)| {
(MutexGuard { _mutex, inner }, result)
})
}
/// Wrapper for [`std::sync::Condvar::wait_timeout_while`].
pub fn wait_timeout_while<'a, T, F>(
&self,
guard: MutexGuard<'a, T>,
dur: Duration,
condition: F,
) -> LockResult<(MutexGuard<'a, T>, WaitTimeoutResult)>
where
F: FnMut(&mut T) -> bool,
{
let MutexGuard { _mutex, inner } = guard;
map_lockresult(
self.0.wait_timeout_while(inner, dur, condition),
|(inner, result)| (MutexGuard { _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 RwLock<T: ?Sized> {
id: LazyMutexId,
inner: sync::RwLock<T>,
}
/// Hybrid wrapper for both [`std::sync::RwLockReadGuard`] and [`std::sync::RwLockWriteGuard`].
///
/// Please refer to [`RwLockReadGuard`] and [`RwLockWriteGuard`] for usable types.
pub struct TracingRwLockGuard<'a, L> {
inner: L,
_mutex: BorrowedMutex<'a>,
}
/// Wrapper around [`std::sync::RwLockReadGuard`].
pub type RwLockReadGuard<'a, T> = TracingRwLockGuard<'a, sync::RwLockReadGuard<'a, T>>;
/// Wrapper around [`std::sync::RwLockWriteGuard`].
pub type RwLockWriteGuard<'a, T> = TracingRwLockGuard<'a, sync::RwLockWriteGuard<'a, T>>;
impl<T> RwLock<T> {
pub const fn new(t: T) -> Self {
Self {
inner: sync::RwLock::new(t),
id: LazyMutexId::new(),
}
}
}
impl<T: ?Sized> RwLock<T> {
/// Wrapper for [`std::sync::RwLock::read`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn read(&self) -> LockResult<RwLockReadGuard<'_, T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.read();
map_lockresult(result, |inner| TracingRwLockGuard {
inner,
_mutex: mutex,
})
}
/// Wrapper for [`std::sync::RwLock::write`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn write(&self) -> LockResult<RwLockWriteGuard<'_, T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.write();
map_lockresult(result, |inner| TracingRwLockGuard {
inner,
_mutex: mutex,
})
}
/// Wrapper for [`std::sync::RwLock::try_read`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<'_, T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.try_read();
map_trylockresult(result, |inner| TracingRwLockGuard {
inner,
_mutex: mutex,
})
}
/// Wrapper for [`std::sync::RwLock::try_write`].
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
#[track_caller]
pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<'_, T>> {
let mutex = self.id.get_borrowed();
let result = self.inner.try_write();
map_trylockresult(result, |inner| TracingRwLockGuard {
inner,
_mutex: mutex,
})
}
/// Return a mutable reference to the underlying data.
///
/// This method does not block as the locking is handled compile-time by the type system.
pub fn get_mut(&mut self) -> LockResult<&mut T> {
self.inner.get_mut()
}
/// Unwrap the mutex and return its inner value.
pub fn into_inner(self) -> LockResult<T>
where
T: Sized,
{
self.inner.into_inner()
}
}
impl<T: ?Sized> PrivateTraced for RwLock<T> {
fn get_id(&self) -> &crate::MutexId {
&self.id
}
}
impl<T> From<T> for RwLock<T> {
fn from(t: T) -> Self {
Self::new(t)
}
}
impl<L, T> Deref for TracingRwLockGuard<'_, L>
where
T: ?Sized,
L: Deref<Target = T>,
{
type Target = T;
#[inline]
fn deref(&self) -> &Self::Target {
self.inner.deref()
}
}
impl<L, T> DerefMut for TracingRwLockGuard<'_, L>
where
T: ?Sized,
L: Deref<Target = T> + DerefMut,
{
#[inline]
fn deref_mut(&mut self) -> &mut Self::Target {
self.inner.deref_mut()
}
}
impl<L> fmt::Debug for TracingRwLockGuard<'_, L>
where
L: fmt::Debug,
{
#[inline]
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.inner.fmt(f)
}
}
impl<L> fmt::Display for TracingRwLockGuard<'_, L>
where
L: fmt::Display,
{
#[inline]
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.inner.fmt(f)
}
}
/// Wrapper around [`std::sync::Once`].
///
/// Refer to the [crate-level][`crate`] documentaiton for the differences between this struct
/// and the one it wraps.
#[derive(Debug)]
pub struct Once {
inner: sync::Once,
mutex_id: LazyMutexId,
}
// New without default is intentional, `std::sync::Once` doesn't implement it either
#[allow(clippy::new_without_default)]
impl Once {
/// Create a new `Once` value.
pub const fn new() -> Self {
Self {
inner: sync::Once::new(),
mutex_id: LazyMutexId::new(),
}
}
/// Wrapper for [`std::sync::Once::call_once`].
///
/// # Panics
///
/// In addition to the panics that `Once` can cause, this method will panic if calling it
/// introduces a cycle in the lock dependency graph.
pub fn call_once<F>(&self, f: F)
where
F: FnOnce(),
{
self.mutex_id.with_held(|| self.inner.call_once(f))
}
/// Performs the same operation as [`call_once`][Once::call_once] except it ignores
/// poisoning.
///
/// # Panics
///
/// This method participates in lock dependency tracking. If acquiring this lock introduces a
/// dependency cycle, this method will panic.
pub fn call_once_force<F>(&self, f: F)
where
F: FnOnce(&OnceState),
{
self.mutex_id.with_held(|| self.inner.call_once_force(f))
}
/// Returns true if some `call_once` has completed successfully.
pub fn is_completed(&self) -> bool {
self.inner.is_completed()
}
}
impl PrivateTraced for Once {
fn get_id(&self) -> &crate::MutexId {
&self.mutex_id
}
}
/// Wrapper for [`std::sync::OnceLock`]
///
/// The exact locking behaviour of [`std::sync::OnceLock`] is currently undefined, but may
/// deadlock in the event of reentrant initialization attempts. This wrapper participates in
/// cycle detection as normal and will therefore panic in the event of reentrancy.
///
/// Most of this primitive's methods do not involve locking and as such are simply passed
/// through to the inner implementation.
///
/// # Examples
///
/// ```
/// use tracing_mutex::stdsync::tracing::OnceLock;
///
/// static LOCK: OnceLock<i32> = OnceLock::new();
/// assert!(LOCK.get().is_none());
///
/// std::thread::spawn(|| {
/// let value: &i32 = LOCK.get_or_init(|| 42);
/// assert_eq!(value, &42);
/// }).join().unwrap();
///
/// let value: Option<&i32> = LOCK.get();
/// assert_eq!(value, Some(&42));
/// ```
#[derive(Debug)]
pub struct OnceLock<T> {
id: LazyMutexId,
inner: sync::OnceLock<T>,
}
// N.B. this impl inlines everything that directly calls the inner implementation as there
// should be 0 overhead to doing so.
impl<T> OnceLock<T> {
/// Creates a new empty cell
pub const fn new() -> Self {
Self {
id: LazyMutexId::new(),
inner: sync::OnceLock::new(),
}
}
/// Gets a reference to the underlying value.
///
/// This method does not attempt to lock and therefore does not participate in cycle
/// detection.
#[inline]
pub fn get(&self) -> Option<&T> {
self.inner.get()
}
/// Gets a mutable reference to the underlying value.
///
/// This method does not attempt to lock and therefore does not participate in cycle
/// detection.
#[inline]
pub fn get_mut(&mut self) -> Option<&mut T> {
self.inner.get_mut()
}
/// Sets the contents of this cell to the underlying value
///
/// As this method may block until initialization is complete, it participates in cycle
/// detection.
pub fn set(&self, value: T) -> Result<(), T> {
self.id.with_held(|| self.inner.set(value))
}
/// Gets the contents of the cell, initializing it with `f` if the cell was empty.
///
/// This method participates in cycle detection. Reentrancy is considered a cycle.
pub fn get_or_init<F>(&self, f: F) -> &T
where
F: FnOnce() -> T,
{
self.id.with_held(|| self.inner.get_or_init(f))
}
/// Takes the value out of this `OnceLock`, moving it back to an uninitialized state.
///
/// This method does not attempt to lock and therefore does not participate in cycle
/// detection.
#[inline]
pub fn take(&mut self) -> Option<T> {
self.inner.take()
}
/// Consumes the `OnceLock`, returning the wrapped value. Returns None if the cell was
/// empty.
///
/// This method does not attempt to lock and therefore does not participate in cycle
/// detection.
#[inline]
pub fn into_inner(mut self) -> Option<T> {
self.take()
}
}
impl<T> PrivateTraced for OnceLock<T> {
fn get_id(&self) -> &crate::MutexId {
&self.id
}
}
impl<T> Default for OnceLock<T> {
#[inline]
fn default() -> Self {
Self::new()
}
}
impl<T: PartialEq> PartialEq for OnceLock<T> {
#[inline]
fn eq(&self, other: &Self) -> bool {
self.inner == other.inner
}
}
impl<T: Eq> Eq for OnceLock<T> {}
impl<T: Clone> Clone for OnceLock<T> {
fn clone(&self) -> Self {
Self {
id: LazyMutexId::new(),
inner: self.inner.clone(),
}
}
}
impl<T> From<T> for OnceLock<T> {
#[inline]
fn from(value: T) -> Self {
Self {
id: LazyMutexId::new(),
inner: sync::OnceLock::from(value),
}
}
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use std::thread;
use super::*;
#[test]
fn test_mutex_usage() {
let mutex = Arc::new(Mutex::new(0));
assert_eq!(*mutex.lock().unwrap(), 0);
*mutex.lock().unwrap() = 1;
assert_eq!(*mutex.lock().unwrap(), 1);
let mutex_clone = mutex.clone();
let _guard = mutex.lock().unwrap();
// Now try to cause a blocking exception in another thread
let handle = thread::spawn(move || {
let result = mutex_clone.try_lock().unwrap_err();
assert!(matches!(result, TryLockError::WouldBlock));
});
handle.join().unwrap();
}
#[test]
fn test_rwlock_usage() {
let rwlock = Arc::new(RwLock::new(0));
assert_eq!(*rwlock.read().unwrap(), 0);
assert_eq!(*rwlock.write().unwrap(), 0);
*rwlock.write().unwrap() = 1;
assert_eq!(*rwlock.read().unwrap(), 1);
assert_eq!(*rwlock.write().unwrap(), 1);
let rwlock_clone = rwlock.clone();
let _read_lock = rwlock.read().unwrap();
// Now try to cause a blocking exception in another thread
let handle = thread::spawn(move || {
let write_result = rwlock_clone.try_write().unwrap_err();
assert!(matches!(write_result, TryLockError::WouldBlock));
// Should be able to get a read lock just fine.
let _read_lock = rwlock_clone.read().unwrap();
});
handle.join().unwrap();
}
#[test]
fn test_once_usage() {
let once = Arc::new(Once::new());
let once_clone = once.clone();
assert!(!once.is_completed());
let handle = thread::spawn(move || {
assert!(!once_clone.is_completed());
once_clone.call_once(|| {});
assert!(once_clone.is_completed());
});
handle.join().unwrap();
assert!(once.is_completed());
}
#[test]
#[should_panic(expected = "Found cycle in mutex dependency graph")]
fn test_detect_cycle() {
let a = Mutex::new(());
let b = Mutex::new(());
let hold_a = a.lock().unwrap();
let _ = b.lock();
drop(hold_a);
let _hold_b = b.lock().unwrap();
let _ = a.lock();
}
}

117
src/stdsync/tracing/lazy_lock.rs Normal file
View File

@@ -0,0 +1,117 @@
//! Wrapper implementation for LazyLock
//!
//! This lives in a separate module as LazyLock would otherwise raise our MSRV to 1.80. Reevaluate
//! this in the future.
use std::fmt;
use std::fmt::Debug;
use std::ops::Deref;
use crate::LazyMutexId;
/// Wrapper for [`std::sync::LazyLock`]
///
/// This wrapper participates in cycle detection like all other primitives in this crate. It should
/// only be possible to encounter cycles when acquiring mutexes in the initialisation function.
///
/// # Examples
///
/// ```
/// use tracing_mutex::stdsync::tracing::LazyLock;
///
/// static LOCK: LazyLock<i32> = LazyLock::new(|| {
/// println!("Hello, world!");
/// 42
/// });
///
/// // This should print "Hello, world!"
/// println!("{}", *LOCK);
/// // This should not.
/// println!("{}", *LOCK);
/// ```
pub struct LazyLock<T, F = fn() -> T> {
// MSRV violation is fine, this is gated behind a cfg! check
#[allow(clippy::incompatible_msrv)]
inner: std::sync::LazyLock<T, F>,
id: LazyMutexId,
}
impl<T, F: FnOnce() -> T> LazyLock<T, F> {
/// Creates a new lazy value with the given initializing function.
pub const fn new(f: F) -> LazyLock<T, F> {
Self {
id: LazyMutexId::new(),
// MSRV violation is fine, this is gated behind a cfg! check
#[allow(clippy::incompatible_msrv)]
inner: std::sync::LazyLock::new(f),
}
}
/// Force this lazy lock to be evaluated.
///
/// This is equivalent to dereferencing, but is more explicit.
pub fn force(this: &LazyLock<T, F>) -> &T {
this
}
}
impl<T, F: FnOnce() -> T> Deref for LazyLock<T, F> {
type Target = T;
fn deref(&self) -> &Self::Target {
self.id.with_held(|| &*self.inner)
}
}
impl<T: Default> Default for LazyLock<T> {
/// Return a `LazyLock` that is initialized through [`Default`].
fn default() -> Self {
Self::new(Default::default)
}
}
impl<T: Debug, F> Debug for LazyLock<T, F> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Cannot implement this ourselves because the get() used is nightly, so delegate.
self.inner.fmt(f)
}
}
#[cfg(test)]
mod tests {
use crate::stdsync::Mutex;
use super::*;
#[test]
fn test_only_init_once() {
let mut init_counter = 0;
let lock = LazyLock::new(|| {
init_counter += 1;
42
});
assert_eq!(*lock, 42);
LazyLock::force(&lock);
// Ensure we can access the init counter
drop(lock);
assert_eq!(init_counter, 1);
}
#[test]
#[should_panic(expected = "Found cycle")]
fn test_panic_with_cycle() {
let mutex = Mutex::new(());
let lock = LazyLock::new(|| *mutex.lock().unwrap());
// Establish the relation from lock to mutex
LazyLock::force(&lock);
// Now do it the other way around, which should crash
let _guard = mutex.lock().unwrap();
LazyLock::force(&lock);
}
}

67
src/util.rs Normal file
View File

@@ -0,0 +1,67 @@
//! Utilities related to the internals of dependency tracking.
use crate::MutexId;
/// Reset the dependencies for the given entity.
///
/// # Performance
///
/// This function locks the dependency graph to remove the item from it. This is an `O(E)` operation
/// with `E` being the number of dependencies directly associated with this particular instance. As
/// such, it is not advisable to call this method from a hot loop.
///
/// # Safety
///
/// Use of this method invalidates the deadlock prevention guarantees that this library makes. As
/// such, it should only be used when it is absolutely certain this will not introduce deadlocks
/// later.
///
/// Other than deadlocks, no undefined behaviour can result from the use of this function.
///
/// # Example
///
/// ```
/// use tracing_mutex::stdsync::Mutex;
/// use tracing_mutex::util;
///
/// let first = Mutex::new(());
/// let second = Mutex::new(());
///
/// {
/// let _first_lock = first.lock().unwrap();
/// second.lock().unwrap();
/// }
///
/// // Reset the dependencies for the first mutex
/// unsafe { util::reset_dependencies(&first) };
///
/// // Now we can unlock the mutexes in the opposite order without a panic.
/// let _second_lock = second.lock().unwrap();
/// first.lock().unwrap();
/// ```
#[cfg(feature = "experimental")]
#[cfg_attr(docsrs, doc(cfg(feature = "experimental")))]
pub unsafe fn reset_dependencies<T: Traced>(traced: &T) {
crate::get_dependency_graph().remove_node(traced.get_id().value());
}
/// Types that participate in dependency tracking
///
/// This trait is a public marker trait and is automatically implemented fore all types that
/// implement the internal dependency tracking features.
#[cfg(feature = "experimental")]
#[cfg_attr(docsrs, doc(cfg(feature = "experimental")))]
#[allow(private_bounds)]
pub trait Traced: PrivateTraced {}
#[cfg(feature = "experimental")]
#[cfg_attr(docsrs, doc(cfg(feature = "experimental")))]
impl<T: PrivateTraced> Traced for T {}
/// Private implementation of the traced marker.
///
/// This trait is private (and seals the outer trait) to avoid exposing the MutexId type.
#[cfg_attr(not(feature = "experimental"), allow(unused))]
pub(crate) trait PrivateTraced {
/// Get the mutex id associated with this traced item.
fn get_id(&self) -> &MutexId;
}