Struct futures_intrusive::sync::GenericSemaphore

pub struct GenericSemaphore<MutexType: RawMutex> { /* fields omitted */ }

A futures-aware semaphore.

Methods

impl<MutexType: RawMutex> 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.

Important 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>

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.

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.

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.

pub fn permits(&self) -> usize

Returns the amount of permits that are available on the semaphore

Trait Implementations

impl<MutexType: RawMutex + Sync> Sync for GenericSemaphore<MutexType>

impl<MutexType: RawMutex + Send> Send for GenericSemaphore<MutexType>

impl<MutexType: RawMutex> Debug for GenericSemaphore<MutexType>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.