Struct futures_intrusive::sync::GenericSemaphore
source · pub struct GenericSemaphore<MutexType: RawMutex> { /* private fields */ }Expand description
A futures-aware semaphore.
Implementations
sourceimpl<MutexType: RawMutex> GenericSemaphore<MutexType>
impl<MutexType: RawMutex> GenericSemaphore<MutexType>
sourcepub fn new(is_fair: bool, permits: usize) -> GenericSemaphore<MutexType>
pub fn new(is_fair: bool, permits: usize) -> GenericSemaphore<MutexType>
Creates a new futures-aware semaphore.
is_fair defines whether the Semaphore should behave be fair regarding the
order of waiters. A fair Semaphore will only allow the oldest waiter on
a Semaphore to retry acquiring it once it’s available again.
Other waiters must wait until either this acquire attempt completes, and
the Semaphore has enough permits after that, or until the
SemaphoreAcquireFuture which tried to acquire the Semaphore is dropped.
If the Semaphore isn’t fair, waiters that wait for a high amount of
permits might never succeed since the permits might be stolen in between
by other waiters. Therefore use-cases which make use of very different
amount of permits per acquire should use fair semaphores.
For use-cases where each acquire() tries to acquire the same amount of
permits an unfair Semaphore might provide throughput advantages.
permits is the amount of permits that a semaphore should hold when
created.
sourcepub fn acquire(
&self,
nr_permits: usize
) -> GenericSemaphoreAcquireFuture<'_, MutexType>ⓘNotable traits for GenericSemaphoreAcquireFuture<'a, MutexType>impl<'a, MutexType: RawMutex> Future for GenericSemaphoreAcquireFuture<'a, MutexType> type Output = GenericSemaphoreReleaser<'a, MutexType>;
pub fn acquire(
&self,
nr_permits: usize
) -> GenericSemaphoreAcquireFuture<'_, MutexType>ⓘNotable traits for GenericSemaphoreAcquireFuture<'a, MutexType>impl<'a, MutexType: RawMutex> Future for GenericSemaphoreAcquireFuture<'a, MutexType> type Output = GenericSemaphoreReleaser<'a, MutexType>;
Acquire a certain amount of permits on a semaphore asynchronously.
This method returns a future that will resolve once the given amount of
permits have been acquired.
The Future will resolve to a GenericSemaphoreReleaser, which will
release all acquired permits automatically when dropped.
sourcepub fn try_acquire(
&self,
nr_permits: usize
) -> Option<GenericSemaphoreReleaser<'_, MutexType>>
pub fn try_acquire(
&self,
nr_permits: usize
) -> Option<GenericSemaphoreReleaser<'_, MutexType>>
Tries to acquire a certain amount of permits on a semaphore.
If acquiring the permits is successful, a GenericSemaphoreReleaser
will be returned, which will release all acquired permits automatically
when dropped.
Otherwise None will be returned.
sourcepub fn release(&self, nr_permits: usize)
pub fn release(&self, nr_permits: usize)
Releases the given amount of permits back to the semaphore.
This method should in most cases not be used, since the
GenericSemaphoreReleaser which is obtained when acquiring a Semaphore
will automatically release the obtained permits again.
Therefore this method should only be used if the automatic release was
disabled by calling GenericSemaphoreReleaser::disarm,
or when the amount of permits in the Semaphore
should increase from the initial amount.