Struct Semaphore 

pub struct Semaphore { /* private fields */ }

A tracked semaphore that automatically records acquisition metrics and integrates with deadlock detection.

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

Example

use async_inspect::sync::Semaphore;

#[tokio::main]
async fn main() {
    // Allow up to 3 concurrent operations
    let semaphore = Semaphore::new(3, "connection_pool");
    let semaphore = std::sync::Arc::new(semaphore);

    let mut handles = vec![];

    for i in 0..10 {
        let sem = semaphore.clone();
        handles.push(tokio::spawn(async move {
            let _permit = sem.acquire().await.unwrap();
            println!("Task {} acquired permit", i);
            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
        }));
    }

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

    // Check acquisition metrics
    let metrics = semaphore.metrics();
    println!("Total acquisitions: {}", metrics.acquisitions);
    println!("Contentions: {}", metrics.contentions);
}

Implementations

impl Semaphore

pub fn new(permits: usize, name: impl Into<String>) -> Self

Create a new tracked semaphore with the given number of permits.

Arguments

• permits - The number of permits available
• name - A descriptive name for debugging and metrics

Example

use async_inspect::sync::Semaphore;

// Create a semaphore limiting to 5 concurrent operations
let semaphore = Semaphore::new(5, "rate_limiter");

pub async fn acquire(&self) -> Result<SemaphorePermit<'_>, AcquireError>

Acquire a permit, blocking until one is available.

Returns

Returns Ok(SemaphorePermit) if a permit was acquired, or Err(AcquireError) if the semaphore was closed.

Example

use async_inspect::sync::Semaphore;

let semaphore = Semaphore::new(3, "pool");
let permit = semaphore.acquire().await.unwrap();
// ... use the resource ...
drop(permit); // Release the permit

pub async fn acquire_many( &self, n: u32, ) -> Result<SemaphorePermit<'_>, AcquireError>

Acquire multiple permits at once.

Arguments

• n - Number of permits to acquire

Example

use async_inspect::sync::Semaphore;

let semaphore = Semaphore::new(10, "batch_pool");
let permit = semaphore.acquire_many(5).await.unwrap();
// ... use 5 resources at once ...

pub fn try_acquire(&self) -> Result<SemaphorePermit<'_>, TryAcquireError>

Try to acquire a permit immediately.

Returns None if no permits are available.

Example

use async_inspect::sync::Semaphore;

let semaphore = Semaphore::new(1, "exclusive");
let result = semaphore.try_acquire();
if let Ok(permit) = result {
    println!("Got the permit!");
    drop(permit);
} else {
    println!("No permits available");
}

pub fn try_acquire_many( &self, n: u32, ) -> Result<SemaphorePermit<'_>, TryAcquireError>

Try to acquire multiple permits immediately.

pub fn available_permits(&self) -> usize

Get the current number of available permits.

pub fn add_permits(&self, n: usize)

Add permits to the semaphore.

Arguments

• n - Number of permits to add

pub fn close(&self)

Close the semaphore.

All pending acquire operations will fail with an error.

pub fn is_closed(&self) -> bool

Check if the semaphore is closed.

pub fn metrics(&self) -> LockMetrics

Get the current acquisition metrics for this semaphore.

Example

use async_inspect::sync::Semaphore;

let semaphore = Semaphore::new(5, "pool");
// ... some operations ...
let metrics = semaphore.metrics();
println!("Acquisitions: {}", metrics.acquisitions);
println!("Contention rate: {:.1}%", metrics.contention_rate() * 100.0);

pub fn reset_metrics(&self)

Reset the acquisition metrics.

pub fn name(&self) -> &str

Get the name of this semaphore.

pub fn resource_id(&self) -> ResourceId

Get the resource ID for deadlock detection.

pub fn initial_permits(&self) -> usize

Get the initial number of permits.

Trait Implementations

impl Debug for Semaphore

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

Formats the value using the given formatter.