Struct Mutex 

pub struct Mutex<T> { /* private fields */ }

A tracked mutex that automatically records contention metrics and integrates with deadlock detection.

This is a drop-in replacement for tokio::sync::Mutex with additional observability features.

Example

use async_inspect::sync::Mutex;

#[tokio::main]
async fn main() {
    let mutex = Mutex::new(0, "counter");

    // Spawn multiple tasks that contend for the lock
    let mutex = std::sync::Arc::new(mutex);
    let mut handles = vec![];

    for i in 0..10 {
        let m = mutex.clone();
        handles.push(tokio::spawn(async move {
            let mut guard = m.lock().await;
            *guard += 1;
        }));
    }

    for h in handles {
        h.await.unwrap();
    }

    // Check contention metrics
    let metrics = mutex.metrics();
    println!("Total acquisitions: {}", metrics.acquisitions);
    println!("Contentions: {}", metrics.contentions);
    println!("Contention rate: {:.1}%", metrics.contention_rate() * 100.0);
}

Implementations

impl<T> Mutex<T>

pub fn new(value: T, name: impl Into<String>) -> Self

Create a new tracked mutex with a name for identification.

Arguments

• value - The initial value to protect
• name - A descriptive name for debugging and metrics

Example

use async_inspect::sync::Mutex;

let mutex = Mutex::new(vec![1, 2, 3], "shared_vector");

pub async fn lock(&self) -> MutexGuard<'_, T>

Acquire the lock, blocking until it’s available.

This method automatically:

• Records wait time if there’s contention
• Notifies the deadlock detector
• Tracks acquisition metrics

Example

use async_inspect::sync::Mutex;

let mutex = Mutex::new(42, "my_value");
let guard = mutex.lock().await;
println!("Value: {}", *guard);

pub fn try_lock(&self) -> Option<MutexGuard<'_, T>>

Try to acquire the lock immediately.

Returns None if the lock is already held.

Example

use async_inspect::sync::Mutex;

let mutex = Mutex::new(42, "my_value");
let result = mutex.try_lock();
if let Some(guard) = result {
    println!("Got the lock: {}", *guard);
} else {
    println!("Lock is held by another task");
}

pub fn metrics(&self) -> LockMetrics

Get the current contention metrics for this mutex.

Example

use async_inspect::sync::Mutex;

let mutex = Mutex::new(42, "my_value");
// ... some operations ...
let metrics = mutex.metrics();
println!("Acquisitions: {}", metrics.acquisitions);
println!("Contention rate: {:.1}%", metrics.contention_rate() * 100.0);

pub fn reset_metrics(&self)

Reset the contention metrics.

pub fn name(&self) -> &str

Get the name of this mutex.

pub fn resource_id(&self) -> ResourceId

Get the resource ID for deadlock detection.

pub fn into_inner(self) -> T

Consume the mutex and return the inner value.

Panics

This method will panic if the mutex is poisoned.

pub fn get_mut(&mut self) -> &mut T

Get a mutable reference to the inner value without locking.

This is safe because we have exclusive access via &mut self.

Trait Implementations

impl<T: Debug> Debug for Mutex<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.