Struct tokio::sync::Semaphore [−][src]
pub struct Semaphore { /* fields omitted */ }
sync
only.Expand description
Counting semaphore performing asynchronous permit acquisition.
A semaphore maintains a set of permits. Permits are used to synchronize access to a shared resource. A semaphore differs from a mutex in that it can allow more than one concurrent caller to access the shared resource at a time.
When acquire
is called and the semaphore has remaining permits, the
function immediately returns a permit. However, if no remaining permits are
available, acquire
(asynchronously) waits until an outstanding permit is
dropped. At this point, the freed permit is assigned to the caller.
This Semaphore
is fair, which means that permits are given out in the order
they were requested. This fairness is also applied when acquire_many
gets
involved, so if a call to acquire_many
at the front of the queue requests
more permits than currently available, this can prevent a call to acquire
from completing, even if the semaphore has enough permits complete the call
to acquire
.
To use the Semaphore
in a poll function, you can use the PollSemaphore
utility.
Implementations
impl Semaphore
[src]
impl Semaphore
[src]pub const fn const_new(permits: usize) -> Self
[src]
This is supported on crate feature parking_lot
only.
pub const fn const_new(permits: usize) -> Self
[src]parking_lot
only.Creates a new semaphore with the initial number of permits.
pub fn available_permits(&self) -> usize
[src]
pub fn available_permits(&self) -> usize
[src]Returns the current number of available permits.
pub fn add_permits(&self, n: usize)
[src]
pub fn add_permits(&self, n: usize)
[src]Adds n
new permits to the semaphore.
The maximum number of permits is usize::MAX >> 3
, and this function will panic if the limit is exceeded.
pub async fn acquire(&self) -> Result<SemaphorePermit<'_>, AcquireError>
[src]
pub async fn acquire(&self) -> Result<SemaphorePermit<'_>, AcquireError>
[src]Acquires a permit from the semaphore.
If the semaphore has been closed, this returns an AcquireError
.
Otherwise, this returns a SemaphorePermit
representing the
acquired permit.
pub async fn acquire_many(
&self,
n: u32
) -> Result<SemaphorePermit<'_>, AcquireError>
[src]
pub async fn acquire_many(
&self,
n: u32
) -> Result<SemaphorePermit<'_>, AcquireError>
[src]Acquires n
permits from the semaphore.
If the semaphore has been closed, this returns an AcquireError
.
Otherwise, this returns a SemaphorePermit
representing the
acquired permits.
pub fn try_acquire(&self) -> Result<SemaphorePermit<'_>, TryAcquireError>
[src]
pub fn try_acquire(&self) -> Result<SemaphorePermit<'_>, TryAcquireError>
[src]Tries to acquire a permit from the semaphore.
If the semaphore has been closed, this returns a TryAcquireError::Closed
and a TryAcquireError::NoPermits
if there are no permits left. Otherwise,
this returns a SemaphorePermit
representing the acquired permits.
pub fn try_acquire_many(
&self,
n: u32
) -> Result<SemaphorePermit<'_>, TryAcquireError>
[src]
pub fn try_acquire_many(
&self,
n: u32
) -> Result<SemaphorePermit<'_>, TryAcquireError>
[src]Tries to acquire n
permits from the semaphore.
If the semaphore has been closed, this returns a TryAcquireError::Closed
and a TryAcquireError::NoPermits
if there are no permits left. Otherwise,
this returns a SemaphorePermit
representing the acquired permits.
pub async fn acquire_owned(
self: Arc<Self>
) -> Result<OwnedSemaphorePermit, AcquireError>
[src]
pub async fn acquire_owned(
self: Arc<Self>
) -> Result<OwnedSemaphorePermit, AcquireError>
[src]Acquires a permit from the semaphore.
The semaphore must be wrapped in an Arc
to call this method.
If the semaphore has been closed, this returns an AcquireError
.
Otherwise, this returns a OwnedSemaphorePermit
representing the
acquired permit.
pub async fn acquire_many_owned(
self: Arc<Self>,
n: u32
) -> Result<OwnedSemaphorePermit, AcquireError>
[src]
pub async fn acquire_many_owned(
self: Arc<Self>,
n: u32
) -> Result<OwnedSemaphorePermit, AcquireError>
[src]Acquires n
permits from the semaphore.
The semaphore must be wrapped in an Arc
to call this method.
If the semaphore has been closed, this returns an AcquireError
.
Otherwise, this returns a OwnedSemaphorePermit
representing the
acquired permit.
pub fn try_acquire_owned(
self: Arc<Self>
) -> Result<OwnedSemaphorePermit, TryAcquireError>
[src]
pub fn try_acquire_owned(
self: Arc<Self>
) -> Result<OwnedSemaphorePermit, TryAcquireError>
[src]Tries to acquire a permit from the semaphore.
The semaphore must be wrapped in an Arc
to call this method. If
the semaphore has been closed, this returns a TryAcquireError::Closed
and a TryAcquireError::NoPermits
if there are no permits left.
Otherwise, this returns a OwnedSemaphorePermit
representing the
acquired permit.
pub fn try_acquire_many_owned(
self: Arc<Self>,
n: u32
) -> Result<OwnedSemaphorePermit, TryAcquireError>
[src]
pub fn try_acquire_many_owned(
self: Arc<Self>,
n: u32
) -> Result<OwnedSemaphorePermit, TryAcquireError>
[src]Tries to acquire n
permits from the semaphore.
The semaphore must be wrapped in an Arc
to call this method. If
the semaphore has been closed, this returns a TryAcquireError::Closed
and a TryAcquireError::NoPermits
if there are no permits left.
Otherwise, this returns a OwnedSemaphorePermit
representing the
acquired permit.
pub fn close(&self)
[src]
pub fn close(&self)
[src]Closes the semaphore.
This prevents the semaphore from issuing new permits and notifies all pending waiters.
Examples
use tokio::sync::Semaphore; use std::sync::Arc; use tokio::sync::TryAcquireError; #[tokio::main] async fn main() { let semaphore = Arc::new(Semaphore::new(1)); let semaphore2 = semaphore.clone(); tokio::spawn(async move { let permit = semaphore.acquire_many(2).await; assert!(permit.is_err()); println!("waiter received error"); }); println!("closing semaphore"); semaphore2.close(); // Cannot obtain more permits assert_eq!(semaphore2.try_acquire().err(), Some(TryAcquireError::Closed)) }