Struct async_weighted_semaphore::Semaphore [−][src]
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]
Notable traits for AcquireFuture<'a>
impl<'a> Future for AcquireFuture<'a> type Output = Result<SemaphoreGuard<'a>, PoisonError>;
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]
&self,
amount: usize
) -> Result<SemaphoreGuard<'_>, TryAcquireError>
Like acquire, but fails if the call would block.
Errors
- Returns
TryAcquireError::Poisoned
is the semaphore is poisoned. - Returns
TryAcquireError::WouldBlock
if a call toacquire
would have blocked. This can occur if there are insufficient available permits or if there is another pending call to acquire.
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ⓘNotable traits for AcquireFutureArc
impl Future for AcquireFutureArc type Output = Result<SemaphoreGuardArc, PoisonError>;
[src]
Notable traits for AcquireFutureArc
impl Future for AcquireFutureArc type Output = Result<SemaphoreGuardArc, PoisonError>;
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]
self: &Arc<Self>,
amount: usize
) -> Result<SemaphoreGuardArc, TryAcquireError>
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
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,