mirror of
https://github.com/bertptrs/tracing-mutex.git
synced 2025-12-25 20:50:32 +01:00
Compare commits
30 Commits
9cfd407f16
...
master
| Author | SHA1 | Date | |
|---|---|---|---|
|
476e249be3 | ||
| a05739810d | |||
| ed6676d345 | |||
| 003f6a02d7 | |||
| d72827a74d | |||
| df0f28b386 | |||
|
|
8dec9db799 | ||
| 28d67e871c | |||
| 90843416e3 | |||
| 522ee3ffe5 | |||
| 1791ef5243 | |||
| 4b872c1262 | |||
| 99bca9852c | |||
| b396016224 | |||
| c29ccc4f4d | |||
| 8ec32bdf16 | |||
| ccc4c98791 | |||
| 9a79b53147 | |||
| af366ca3af | |||
| 1ad0b2756e | |||
| d1a6b93ea8 | |||
| ebdb6a18fe | |||
| 4666923972 | |||
| 7ae0bd3989 | |||
| 0f201989e0 | |||
| 3dd73fa7ff | |||
| 914320a91c | |||
| 095279aa62 | |||
| d93879fcf2 | |||
| 4b17c45a4a |
7
.github/dependabot.yml
vendored
Normal file
7
.github/dependabot.yml
vendored
Normal file
@@ -0,0 +1,7 @@
|
||||
---
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
38
.github/workflows/ci.yml
vendored
38
.github/workflows/ci.yml
vendored
@@ -15,50 +15,64 @@ jobs:
|
||||
strategy:
|
||||
matrix:
|
||||
rust:
|
||||
- "1.74" # Current minimum for experimental features
|
||||
- stable
|
||||
- beta
|
||||
- nightly
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/checkout@v6
|
||||
|
||||
- uses: dtolnay/rust-toolchain@v1
|
||||
- uses: dtolnay/rust-toolchain@master
|
||||
with:
|
||||
toolchain: ${{ matrix.rust }}
|
||||
components: rustfmt, clippy
|
||||
components: clippy
|
||||
|
||||
# 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
|
||||
- run: cargo fmt --all -- --check
|
||||
# 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
|
||||
|
||||
msrv:
|
||||
name: MSRV
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/checkout@v6
|
||||
|
||||
- uses: dtolnay/rust-toolchain@v1
|
||||
- uses: dtolnay/rust-toolchain@1.74
|
||||
with:
|
||||
toolchain: "1.70"
|
||||
|
||||
- run: cargo test --all-features
|
||||
# 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:
|
||||
components: rustfmt
|
||||
- run: cargo fmt --check
|
||||
|
||||
docs:
|
||||
name: Documentation build
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/checkout@v6
|
||||
|
||||
- uses: dtolnay/rust-toolchain@v1
|
||||
with:
|
||||
toolchain: nightly
|
||||
- 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
|
||||
|
||||
41
CHANGELOG.md
41
CHANGELOG.md
@@ -6,10 +6,47 @@ 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
|
||||
@@ -97,7 +134,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
Initial release.
|
||||
|
||||
[Unreleased]: https://github.com/bertptrs/tracing-mutex/compare/v0.3.0...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
|
||||
|
||||
135
Cargo.lock
generated
135
Cargo.lock
generated
@@ -53,15 +53,6 @@ version = "0.3.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
|
||||
|
||||
[[package]]
|
||||
name = "cc"
|
||||
version = "1.0.83"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f1174fb0b6ec23863f8b971027804a42614e347eafb0a95bf0b12cdae21fc4d0"
|
||||
dependencies = [
|
||||
"libc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "cfg-if"
|
||||
version = "1.0.0"
|
||||
@@ -207,23 +198,12 @@ checksum = "a26ae43d7bcc3b814de94796a5e736d4029efb0ee900c12e2d54c993ad1a1e07"
|
||||
|
||||
[[package]]
|
||||
name = "errno"
|
||||
version = "0.3.2"
|
||||
version = "0.3.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6b30f669a7961ef1631673d2766cc92f52d64f7ef354d4fe0ddfd30ed52f0f4f"
|
||||
checksum = "33d852cb9b869c2a9b3df2f71a3074817f01e1844f839a144f5fcef059a4eb5d"
|
||||
dependencies = [
|
||||
"errno-dragonfly",
|
||||
"libc",
|
||||
"windows-sys",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "errno-dragonfly"
|
||||
version = "0.1.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "aa68f1b12764fab894d2755d2518754e71b4fd80ecfb822714a1206c2aab39bf"
|
||||
dependencies = [
|
||||
"cc",
|
||||
"libc",
|
||||
"windows-sys 0.59.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -257,7 +237,7 @@ checksum = "cb0889898416213fab133e1d33a0e5858a48177452750691bde3666d0fdbaf8b"
|
||||
dependencies = [
|
||||
"hermit-abi",
|
||||
"rustix",
|
||||
"windows-sys",
|
||||
"windows-sys 0.48.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -286,15 +266,15 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "libc"
|
||||
version = "0.2.147"
|
||||
version = "0.2.169"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b4668fb0ea861c1df094127ac5f1da3409a82116a4ba74fca2e58ef927159bb3"
|
||||
checksum = "b5aba8db14291edd000dfcc4d620c7ebfb122c613afb886ca8803fa4e128a20a"
|
||||
|
||||
[[package]]
|
||||
name = "linux-raw-sys"
|
||||
version = "0.4.5"
|
||||
version = "0.4.15"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "57bcfdad1b858c2db7c38303a6d2ad4dfaf5eb53dfeb0910128b2c26d6158503"
|
||||
checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
|
||||
|
||||
[[package]]
|
||||
name = "lock_api"
|
||||
@@ -378,7 +358,7 @@ dependencies = [
|
||||
"libc",
|
||||
"redox_syscall",
|
||||
"smallvec",
|
||||
"windows-targets",
|
||||
"windows-targets 0.48.5",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -525,15 +505,15 @@ checksum = "dbb5fb1acd8a1a18b3dd5be62d25485eb770e05afb408a9627d14d451bae12da"
|
||||
|
||||
[[package]]
|
||||
name = "rustix"
|
||||
version = "0.38.9"
|
||||
version = "0.38.43"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9bfe0f2582b4931a45d1fa608f8a8722e8b3c7ac54dd6d5f3b3212791fedef49"
|
||||
checksum = "a78891ee6bf2340288408954ac787aa063d8e8817e9f53abb37c695c6d834ef6"
|
||||
dependencies = [
|
||||
"bitflags 2.4.0",
|
||||
"errno",
|
||||
"libc",
|
||||
"linux-raw-sys",
|
||||
"windows-sys",
|
||||
"windows-sys 0.59.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -617,7 +597,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "tracing-mutex"
|
||||
version = "0.3.0"
|
||||
version = "0.3.2"
|
||||
dependencies = [
|
||||
"autocfg",
|
||||
"criterion",
|
||||
@@ -749,7 +729,16 @@ version = "0.48.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9"
|
||||
dependencies = [
|
||||
"windows-targets",
|
||||
"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]]
|
||||
@@ -758,13 +747,29 @@ version = "0.48.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9a2fa6e2155d7247be68c096456083145c183cbbbc2764150dda45a87197940c"
|
||||
dependencies = [
|
||||
"windows_aarch64_gnullvm",
|
||||
"windows_aarch64_msvc",
|
||||
"windows_i686_gnu",
|
||||
"windows_i686_msvc",
|
||||
"windows_x86_64_gnu",
|
||||
"windows_x86_64_gnullvm",
|
||||
"windows_x86_64_msvc",
|
||||
"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]]
|
||||
@@ -773,38 +778,86 @@ 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"
|
||||
|
||||
18
Cargo.toml
18
Cargo.toml
@@ -1,10 +1,8 @@
|
||||
[package]
|
||||
name = "tracing-mutex"
|
||||
version = "0.3.0"
|
||||
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."
|
||||
@@ -30,12 +28,20 @@ rand = "0.8"
|
||||
name = "mutex"
|
||||
harness = false
|
||||
|
||||
[[example]]
|
||||
name = "drop_in_parking_lot"
|
||||
required-features = ["parkinglot"]
|
||||
|
||||
[features]
|
||||
default = ["backtraces"]
|
||||
backtraces = []
|
||||
# Feature names do not match crate names pending namespaced features.
|
||||
lockapi = ["lock_api"]
|
||||
parkinglot = ["parking_lot", "lockapi"]
|
||||
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"
|
||||
|
||||
@@ -36,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.
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
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::tracing::Mutex as TracingMutex;
|
||||
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
status = [
|
||||
'Rust project (1.70)',
|
||||
'Rust project (stable)',
|
||||
'Rust project (beta)',
|
||||
'Documentation build',
|
||||
]
|
||||
32
examples/drop_in_parking_lot.rs
Normal file
32
examples/drop_in_parking_lot.rs
Normal 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);
|
||||
}
|
||||
2
rustfmt.toml
Normal file
2
rustfmt.toml
Normal file
@@ -0,0 +1,2 @@
|
||||
style_edition="2024"
|
||||
imports_granularity="Item"
|
||||
@@ -1,7 +1,7 @@
|
||||
use std::cell::Cell;
|
||||
use std::collections::hash_map::Entry;
|
||||
use std::collections::HashMap;
|
||||
use std::collections::HashSet;
|
||||
use std::collections::hash_map::Entry;
|
||||
use std::hash::Hash;
|
||||
|
||||
type Order = usize;
|
||||
|
||||
48
src/lib.rs
48
src/lib.rs
@@ -30,12 +30,17 @@
|
||||
//!
|
||||
//! - `backtraces`: Enables capturing backtraces of mutex dependencies, to make it easier to
|
||||
//! determine what sequence of events would trigger a deadlock. This is enabled by default, but if
|
||||
//! the performance overhead is unaccceptable, it can be disabled by disabling default features.
|
||||
//! 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
|
||||
//!
|
||||
//! Tracing a mutex adds overhead to certain mutex operations in order to do the required
|
||||
@@ -72,33 +77,44 @@ use std::fmt;
|
||||
use std::marker::PhantomData;
|
||||
use std::ops::Deref;
|
||||
use std::ops::DerefMut;
|
||||
use std::sync::atomic::AtomicUsize;
|
||||
use std::sync::atomic::Ordering;
|
||||
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;
|
||||
|
||||
#[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 graph::DiGraph;
|
||||
use reporting::Dep;
|
||||
use reporting::Reportable;
|
||||
|
||||
use crate::graph::DiGraph;
|
||||
|
||||
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;
|
||||
pub mod util;
|
||||
|
||||
thread_local! {
|
||||
/// Stack to track which locks are held
|
||||
@@ -147,7 +163,7 @@ 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 {
|
||||
id: self,
|
||||
@@ -335,9 +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(), Dep::capture)
|
||||
.is_ok());
|
||||
assert!(
|
||||
get_dependency_graph()
|
||||
.add_edge(c.value(), a.value(), Dep::capture)
|
||||
.is_ok()
|
||||
);
|
||||
}
|
||||
|
||||
/// Test creating a cycle, then panicking.
|
||||
|
||||
@@ -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,6 +89,12 @@ 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,
|
||||
|
||||
@@ -41,194 +41,29 @@
|
||||
|
||||
pub use parking_lot as raw;
|
||||
|
||||
pub use parking_lot::OnceState;
|
||||
pub use parking_lot::RawThreadId;
|
||||
pub use parking_lot::WaitTimeoutResult;
|
||||
|
||||
pub mod tracing;
|
||||
|
||||
// Skip reformatting the combined imports as it duplicates the guards
|
||||
#[rustfmt::skip]
|
||||
#[cfg(debug_assertions)]
|
||||
pub use tracing::{
|
||||
FairMutex, FairMutexGuard, MappedFairMutexGuard, MappedMutexGuard, MappedReentrantMutexGuard,
|
||||
MappedRwLockReadGuard, MappedRwLockWriteGuard, Mutex, MutexGuard, Once, OnceState,
|
||||
ReentrantMutex, ReentrantMutexGuard, RwLock, RwLockReadGuard, RwLockUpgradableReadGuard,
|
||||
RwLockWriteGuard,
|
||||
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 use parking_lot::{
|
||||
FairMutex, FairMutexGuard, MappedFairMutexGuard, MappedMutexGuard, MappedReentrantMutexGuard,
|
||||
MappedRwLockReadGuard, MappedRwLockWriteGuard, Mutex, MutexGuard, Once, OnceState,
|
||||
ReentrantMutex, ReentrantMutexGuard, RwLock, RwLockReadGuard, RwLockUpgradableReadGuard,
|
||||
RwLockWriteGuard,
|
||||
MappedRwLockReadGuard, MappedRwLockWriteGuard, Mutex, MutexGuard, Once, RawFairMutex, RawMutex,
|
||||
RawRwLock, ReentrantMutex, ReentrantMutexGuard, RwLock, RwLockReadGuard,
|
||||
RwLockUpgradableReadGuard, RwLockWriteGuard, const_fair_mutex, const_mutex,
|
||||
const_reentrant_mutex, const_rwlock,
|
||||
};
|
||||
|
||||
/// Dependency tracing wrappers for [`parking_lot`].
|
||||
pub mod tracing {
|
||||
pub use parking_lot::OnceState;
|
||||
|
||||
use crate::lockapi::TracingWrapper;
|
||||
use crate::LazyMutexId;
|
||||
|
||||
type RawFairMutex = TracingWrapper<parking_lot::RawFairMutex>;
|
||||
type RawMutex = TracingWrapper<parking_lot::RawMutex>;
|
||||
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));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use std::sync::Arc;
|
||||
use std::thread;
|
||||
|
||||
use super::tracing;
|
||||
|
||||
#[test]
|
||||
fn test_mutex_usage() {
|
||||
let mutex = Arc::new(tracing::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 = [
|
||||
tracing::Mutex::new(()),
|
||||
tracing::Mutex::new(()),
|
||||
tracing::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(tracing::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 = tracing::RwLock::new(());
|
||||
|
||||
// Should be able to acquire an upgradable read lock.
|
||||
let upgradable_guard: tracing::RwLockUpgradableReadGuard<'_, _> = lock.upgradable_read();
|
||||
|
||||
// Should be able to upgrade the guard.
|
||||
let _write_guard: tracing::RwLockWriteGuard<'_, _> =
|
||||
tracing::RwLockUpgradableReadGuard::upgrade(upgradable_guard);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_once_usage() {
|
||||
let once = Arc::new(tracing::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());
|
||||
}
|
||||
}
|
||||
|
||||
193
src/parkinglot/tracing.rs
Normal file
193
src/parkinglot/tracing.rs
Normal 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());
|
||||
}
|
||||
}
|
||||
687
src/stdsync.rs
687
src/stdsync.rs
@@ -20,11 +20,14 @@
|
||||
//! ```
|
||||
pub use std::sync as raw;
|
||||
|
||||
// Skip reformatting the combined imports as it duplicates the guards
|
||||
#[rustfmt::skip]
|
||||
#[cfg(not(debug_assertions))]
|
||||
pub use std::sync::{
|
||||
Condvar, Mutex, MutexGuard, Once, OnceLock, RwLock, RwLockReadGuard, RwLockWriteGuard,
|
||||
};
|
||||
|
||||
#[rustfmt::skip]
|
||||
#[cfg(debug_assertions)]
|
||||
pub use tracing::{
|
||||
Condvar, Mutex, MutexGuard, Once, OnceLock, RwLock, RwLockReadGuard, RwLockWriteGuard,
|
||||
@@ -37,686 +40,4 @@ pub use tracing::LazyLock;
|
||||
pub use std::sync::LazyLock;
|
||||
|
||||
/// Dependency tracing versions of [`std::sync`].
|
||||
pub mod tracing {
|
||||
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;
|
||||
|
||||
#[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> {
|
||||
inner: sync::Mutex<T>,
|
||||
id: LazyMutexId,
|
||||
}
|
||||
|
||||
/// Wrapper for [`std::sync::MutexGuard`].
|
||||
///
|
||||
/// Refer to the [crate-level][`crate`] documentation for the differences between this struct and
|
||||
/// the one it wraps.
|
||||
#[derive(Debug)]
|
||||
pub struct MutexGuard<'a, T> {
|
||||
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(),
|
||||
}
|
||||
}
|
||||
|
||||
/// 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> {
|
||||
self.inner.into_inner()
|
||||
}
|
||||
}
|
||||
|
||||
impl<T> From<T> for Mutex<T> {
|
||||
fn from(t: T) -> Self {
|
||||
Self::new(t)
|
||||
}
|
||||
}
|
||||
|
||||
impl<T> Deref for MutexGuard<'_, T> {
|
||||
type Target = T;
|
||||
|
||||
fn deref(&self) -> &Self::Target {
|
||||
&self.inner
|
||||
}
|
||||
}
|
||||
|
||||
impl<T> DerefMut for MutexGuard<'_, T> {
|
||||
fn deref_mut(&mut self) -> &mut Self::Target {
|
||||
&mut self.inner
|
||||
}
|
||||
}
|
||||
|
||||
impl<T: fmt::Display> fmt::Display for MutexGuard<'_, 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::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> {
|
||||
inner: sync::RwLock<T>,
|
||||
id: LazyMutexId,
|
||||
}
|
||||
|
||||
/// Hybrid wrapper for both [`std::sync::RwLockReadGuard`] and [`std::sync::RwLockWriteGuard`].
|
||||
///
|
||||
/// Please refer to [`RwLockReadGuard`] and [`RwLockWriteGuard`] for usable types.
|
||||
#[derive(Debug)]
|
||||
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(),
|
||||
}
|
||||
}
|
||||
|
||||
/// 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> {
|
||||
self.inner.into_inner()
|
||||
}
|
||||
}
|
||||
|
||||
impl<T> From<T> for RwLock<T> {
|
||||
fn from(t: T) -> Self {
|
||||
Self::new(t)
|
||||
}
|
||||
}
|
||||
|
||||
impl<L, T> Deref for TracingRwLockGuard<'_, L>
|
||||
where
|
||||
L: Deref<Target = T>,
|
||||
{
|
||||
type Target = T;
|
||||
|
||||
fn deref(&self) -> &Self::Target {
|
||||
self.inner.deref()
|
||||
}
|
||||
}
|
||||
|
||||
impl<T, L> DerefMut for TracingRwLockGuard<'_, 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 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()
|
||||
}
|
||||
}
|
||||
|
||||
/// 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> 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();
|
||||
}
|
||||
}
|
||||
}
|
||||
pub mod tracing;
|
||||
|
||||
748
src/stdsync/tracing.rs
Normal file
748
src/stdsync/tracing.rs
Normal 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();
|
||||
}
|
||||
}
|
||||
67
src/util.rs
Normal file
67
src/util.rs
Normal 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;
|
||||
}
|
||||
Reference in New Issue
Block a user