[][src]Struct async_weighted_semaphore::Semaphore

pub struct Semaphore { /* fields omitted */ }

An async weighted semaphore. See crate documentation for usage.

Implementations

impl Semaphore[src]

pub const MAX_AVAILABLE: usize[src]

The maximum number of permits that can be made available. This is slightly smaller than usize::MAX. If the number of available permits exceeds this number, it may poison the semaphore.

Examples

struct ReadWriteLock(Semaphore);
impl ReadWriteLock {
    fn new() -> Self {
        ReadWriteLock(Semaphore::new(Semaphore::MAX_AVAILABLE))
    }
    // Acquire one permit, allowing up to MAX_AVAILABLE concurrent readers.
    async fn read(&self) -> SemaphoreGuard<'_> {
        self.0.acquire(1).await.unwrap()
    }
    // The writer acquires all the permits, prevent any concurrent writers or readers. The
    // first-in-first-out priority policy prevents writer starvation.
    async fn write(&self) -> SemaphoreGuard<'_> {
        self.0.acquire(Semaphore::MAX_AVAILABLE).await.unwrap()
    }
}

pub fn new(initial: usize) -> Self[src]

Create a new semaphore with an initial number of permits.

Examples

use async_weighted_semaphore::Semaphore;
let semaphore = Semaphore::new(1024);

pub fn acquire(&self, amount: usize) -> AcquireFuture<'_>

Notable traits for AcquireFuture<'a>

impl<'a> Future for AcquireFuture<'a> type Output = Result<SemaphoreGuard<'a>, PoisonError>;
[src]

Wait until there are no older pending calls to acquire and at least amount permits available. Then consume the requested permits and return a SemaphoreGuard.

Errors

Returns PoisonError is the semaphore is poisoned.

Examples

use async_weighted_semaphore::Semaphore;
async fn limit_concurrency(semaphore: &Semaphore, future: impl Future<Output=()>) {
    let guard = semaphore.acquire(1).await.unwrap();
    future.await
}

pub fn try_acquire(
    &self,
    amount: usize
) -> Result<SemaphoreGuard<'_>, TryAcquireError>
[src]

Like acquire, but fails if the call would block.

Errors

Examples

use async_weighted_semaphore::Semaphore;
async fn run_if_safe(semaphore: &Semaphore, future: impl Future<Output=()>) {
    if semaphore.try_acquire(1).is_ok() {
        future.await
    }
}

pub fn acquire_arc(self: &Arc<Self>, amount: usize) -> AcquireFutureArc[src]

Like acquire, but takes an Arc <Semaphore> and returns a guard that is 'static, Send and Sync.

Examples

use async_channel::{Sender, SendError};
// Limit size of a producer-consumer queue
async fn send<T>(semaphore: &Arc<Semaphore>,
                 sender: &Sender<(SemaphoreGuardArc, T)>,
                 message: T
        ) -> Result<(), SendError<T>>{
    match semaphore.acquire_arc(1).await {
        // A semaphore can be poisoned to prevent deadlock when a channel closes.
        Err(PoisonError) => Err(SendError(message)),
        Ok(guard) => match sender.send((guard, message)).await{
            Err(SendError((guard, message))) => Err(SendError(message)),
            Ok(()) => Ok(())
        }
    }
}

pub fn try_acquire_arc(
    self: &Arc<Self>,
    amount: usize
) -> Result<SemaphoreGuardArc, TryAcquireError>
[src]

Like try_acquire, but takes an Arc <Semaphore>, and returns a guard that is 'static, Send and Sync.

Examples

use async_channel::{Sender, TrySendError};
// Limit size of a producer-consumer queue
async fn try_send<T>(semaphore: &Arc<Semaphore>,
                 sender: &Sender<(SemaphoreGuardArc, T)>,
                 message: T
        ) -> Result<(), TrySendError<T>>{
    match semaphore.try_acquire_arc(1) {
        Err(TryAcquireError::WouldBlock) => Err(TrySendError::Full(message)),
        // A semaphore can be poisoned to prevent deadlock when a channel closes.
        Err(TryAcquireError::Poisoned) => Err(TrySendError::Closed(message)),
        Ok(guard) => match sender.try_send((guard, message)) {
            Err(TrySendError::Closed((guard, message))) => Err(TrySendError::Closed(message)),
            Err(TrySendError::Full((guard, message))) => Err(TrySendError::Full(message)),
            Ok(()) => Ok(())
        }
    }
}

pub fn release(&self, amount: usize)[src]

Return amount permits to the semaphore. This will eventually wake any calls to acquire that can succeed with the additional permits. Calling release often makes sense after calling SemaphoreGuard::forget or when using the semaphore to signal the number of elements that are available for processing.

Examples

use async_channel::{Receiver, RecvError};
// Limit size of a producer-consumer queue
async fn recv<T>(semaphore: &Semaphore, recv: &Receiver<T>) -> Result<T, RecvError>{
    let result = recv.recv().await?;
    // Note that this only guards elements in the queue, not those being processed after the
    // queue.
    semaphore.release(1);
    Ok(result)
}

pub fn poison(&self)[src]

Poison the semaphore, causing all pending and future calls to acquire to fail immediately. This can be used to unblock pending acquires when the guarded operation would fail anyway.

Examples

use async_channel::{Receiver, RecvError};
async fn consume(semaphore: &Semaphore, receiver: Receiver<usize>){
    while let Ok(x) = receiver.recv().await {
        println!("{:?}", x);
        semaphore.release(1);
    }
    // There will be no more calls to recv, so unblock all senders.
    semaphore.poison();
}

Trait Implementations

impl Debug for Semaphore[src]

impl RefUnwindSafe for Semaphore[src]

impl Send for Semaphore[src]

impl Sync for Semaphore[src]

impl UnwindSafe for Semaphore[src]

Auto Trait Implementations

impl Unpin for Semaphore

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.