tracing_mutex/
parkinglot.rs

1//! Wrapper types and type aliases for tracing [`parking_lot`] mutexes.
2//!
3//! This module provides type aliases that use the [`lockapi`][crate::lockapi] module to provide
4//! tracing variants of the `parking_lot` primitives. The [`tracing`] module contains type aliases
5//! that use dependency tracking, while the main `parking_lot` primitives are reexported as [`raw`].
6//!
7//! This main module imports from [`tracing`] when `debug_assertions` are enabled, and from [`raw`]
8//! when they're not. Note that primitives for which no tracing wrapper exists are not imported into
9//! the main module.
10//!
11//! # Usage
12//!
13//! ```
14//! # use std::sync::Arc;
15//! # use std::thread;
16//! use tracing_mutex::parkinglot::Mutex;
17//! let mutex = Arc::new(Mutex::new(0));
18//!
19//! let handles: Vec<_> = (0..10).map(|_| {
20//!    let mutex = Arc::clone(&mutex);
21//!    thread::spawn(move || *mutex.lock() += 1)
22//! }).collect();
23//!
24//! handles.into_iter().for_each(|handle| handle.join().unwrap());
25//!
26//! // All threads completed so the value should be 10.
27//! assert_eq!(10, *mutex.lock());
28//! ```
29//!
30//! # Limitations
31//!
32//! The main lock for the global state is still provided by `std::sync` and the tracing primitives
33//! are larger than the `parking_lot` primitives they wrap, so there can be a performance
34//! degradation between using this and using `parking_lot` directly. If this is of concern to you,
35//! try using the `DebugX`-structs, which provide cycle detection only when `debug_assertions` are
36//! enabled and have no overhead when they're not.
37//!
38//! In addition, the mutex guards returned by the tracing wrappers are `!Send`, regardless of
39//! whether `parking_lot` is configured to have `Send` mutex guards. This is a limitation of the
40//! current bookkeeping system.
41
42pub use parking_lot as raw;
43
44pub use parking_lot::OnceState;
45pub use parking_lot::RawThreadId;
46pub use parking_lot::WaitTimeoutResult;
47
48pub mod tracing;
49
50#[cfg(debug_assertions)]
51pub use tracing::{
52    FairMutex, FairMutexGuard, MappedFairMutexGuard, MappedMutexGuard, MappedReentrantMutexGuard,
53    MappedRwLockReadGuard, MappedRwLockWriteGuard, Mutex, MutexGuard, Once, RawFairMutex, RawMutex,
54    RawRwLock, ReentrantMutex, ReentrantMutexGuard, RwLock, RwLockReadGuard,
55    RwLockUpgradableReadGuard, RwLockWriteGuard, const_fair_mutex, const_mutex,
56    const_reentrant_mutex, const_rwlock,
57};
58
59#[cfg(not(debug_assertions))]
60pub use parking_lot::{
61    FairMutex, FairMutexGuard, MappedFairMutexGuard, MappedMutexGuard, MappedReentrantMutexGuard,
62    MappedRwLockReadGuard, MappedRwLockWriteGuard, Mutex, MutexGuard, Once, RawFairMutex, RawMutex,
63    RawRwLock, ReentrantMutex, ReentrantMutexGuard, RwLock, RwLockReadGuard,
64    RwLockUpgradableReadGuard, RwLockWriteGuard, const_fair_mutex, const_mutex,
65    const_reentrant_mutex, const_rwlock,
66};
tracing_mutex/parkinglot.rs

tracing_mutex/
parkinglot.rs
