Crate ranked_semaphore

ranked-semaphore

A priority-aware semaphore for async Rust.

Features

• Priority scheduling: Configurable priority-based task ordering
• No runtime dependency: Works with any async runtime (Tokio, async-std, smol, etc.)
• Flexible queue strategies: FIFO/LIFO and custom strategy

Quick Start

use ranked_semaphore::RankedSemaphore;

#[tokio::main]
async fn main() {
    // Create a semaphore with 3 permits, FIFO strategy
    let sem = RankedSemaphore::new_fifo(3);

    // Acquire a permit (default priority)
    let permit = sem.acquire().await.unwrap();

    // Acquire with custom priority
    let high = sem.acquire_with_priority(10).await.unwrap();

    // Release permits automatically on drop
    drop(permit);
    drop(high);
}

Advanced Usage

Use PriorityConfig and QueueStrategy for fine-grained control:

use ranked_semaphore::{RankedSemaphore, PriorityConfig, QueueStrategy};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let config = PriorityConfig::new()
        .default_strategy(QueueStrategy::Fifo)
        .exact(10, QueueStrategy::Lifo);

    let limiter = Arc::new(RankedSemaphore::new_with_config(2, config));

    let _admin = limiter.acquire_with_priority(10).await.unwrap();
    let _guest = limiter.acquire_with_priority(0).await.unwrap();
}

See the README and API docs for more details.

Structs

Acquire

Acquire operation Future

AcquireError

Error returned from acquire operations when the semaphore has been closed.

AcquireOwned

Owned acquire operation Future

OwnedRankedSemaphorePermit

Semaphore permit (owned version)

PriorityConfig

Configuration for priority-based queue strategies.

RankedSemaphore

High-performance priority semaphore

RankedSemaphorePermit

Semaphore permit (borrowed version)

Enums

QueueStrategy

Queue strategy for waiters at a given priority level.

TryAcquireError

Error returned from try_acquire operations.