Struct BatchSemaphore 

pub struct BatchSemaphore { /* private fields */ }

Counting semaphore

Implementations

impl BatchSemaphore

pub fn new(num_permits: usize, fairness: Fairness) -> BatchSemaphore

Creates a new semaphore with the initial number of permits.

pub fn new_with_signature( num_permits: usize, fairness: Fairness, signature: ResourceSignature, ) -> BatchSemaphore

pub const fn const_new(num_permits: usize, fairness: Fairness) -> BatchSemaphore

Creates a new semaphore with the initial number of permits.

pub const fn const_new_with_signature( num_permits: usize, fairness: Fairness, signature: ResourceSignature, ) -> BatchSemaphore

pub fn available_permits(&self) -> usize

Returns the current number of available permits. While a reservation holds the semaphore (see BatchSemaphore::acquire_reserving), this is zero: the available permits are kept for the holder.

pub fn close(&self)

Closes the semaphore. This prevents the semaphore from issuing new permits and notifies all pending waiters.

pub fn close_no_scheduling_point(&self)

Closes the semaphore without invoking thread::switch

pub fn is_closed(&self) -> bool

Returns true iff the semaphore is closed.

pub fn try_acquire(&self, num_permits: usize) -> Result<(), TryAcquireError>

Try to acquire the specified number of permits from the Semaphore. If the permits are available, returns Ok(()) If the semaphore is closed, returns Err(TryAcquireError::Closed) If there aren’t enough permits, returns Err(TryAcquireError::NoPermits)

pub fn acquire(&self, num_permits: usize) -> Acquire<'_>

Acquire the specified number of permits (async API)

pub fn acquire_blocking(&self, num_permits: usize) -> Result<(), AcquireError>

Acquire the specified number of permits (blocking API)

pub fn acquire_reserving( &self, min_permits: usize, num_permits: usize, ) -> Acquire<'_>

Acquire num_permits permits, and reserve the semaphore for this request as soon as at least min_permits permits are available (async API). Only an unfair semaphore supports this.

Until min_permits permits are available, the request waits like one from BatchSemaphore::acquire: it holds nothing and stops no other request. As soon as they are, it reserves the semaphore in the same step. From then on, no other request can take a permit, and this request takes its num_permits as soon as that many are available. The reservation ends when the request is granted, or when the returned future is dropped. While it lasts, BatchSemaphore::available_permits is zero.

The motivating use case is a parking_lot RwLock writer. parking_lot sets WRITER_BIT only when no writer or upgradable reader holds the lock, and from then on, the bit stops new readers while the writer waits for the current ones to leave. With min_permits above the permits that are left while an upgradable reader holds the lock, the reservation is that bit.

At most one request can hold the reservation. Another reserving request waits like any other until the reservation ends.

Panics

Panics if the semaphore is strictly fair (its queue already keeps the permits for its first waiter), if num_permits is zero, or if min_permits > num_permits.

pub fn release(&self, num_permits: usize)

Release num_permits back to the Semaphore

pub fn upgrade( &self, permits_currently_held: usize, permits_to_be_held: usize, ) -> Acquire<'_>

Atomically upgrade from holding permits_currently_held permits to holding permits_to_be_held, without ever dropping below permits_currently_held in between. The motivating use case is parking_lot’s RwLockUpgradableReadGuard::upgrade, which must take a read guard to a write guard without letting any writer in along the way.

This is implemented by acquiring only the missing permits (permits_to_be_held - permits_currently_held), with priority over any waiter already queued, so that the request overtakes the queue. Both halves of that matter:

• Keeping the held permits means no other task can claim the resource mid-upgrade. Releasing them first (even for an instant) would hand the resource to a queued waiter, which for an RwLock means a writer mutating the data an upgradable reader had already observed.
• Overtaking the queue is what makes that safe rather than deadlock-prone. Since we hold permits we will not release, a queued waiter ahead of us may be unsatisfiable (an RwLock writer wants all permits), so waiting our turn behind it could deadlock. Queued waiters hold no permits, so overtaking them costs nothing but their place in line – which is exactly the priority a real upgradable read lock gives an upgrade.

The upgrade therefore blocks only on tasks that currently hold permits, and is granted as soon as they release. The returned future must be driven to completion; if it is dropped first, the caller still holds permits_currently_held.

An unfair semaphore has no queue to overtake, so there the upgrade reserves the semaphore instead (see BatchSemaphore::acquire_reserving), at once unless another request holds the reservation. From then on, no other request can take a permit, so the upgrade again waits only for the tasks that hold permits, and nothing can overtake it.

At most one upgrade may be in flight on a semaphore at a time. Two concurrent upgraders could each be waiting for permits the other holds, which no queue discipline can resolve. Callers are expected to enforce this (an RwLock does: there is only ever one upgradable reader).

pub fn try_upgrade( &self, permits_currently_held: usize, permits_to_be_held: usize, ) -> Result<(), TryAcquireError>

The non-blocking analogue of BatchSemaphore::upgrade: succeeds only if the missing permits are available right now, and never blocks or queues.

Like upgrade, this ignores queued waiters (they hold no permits, so they cannot be the reason the upgrade is short of permits). A try_upgrade therefore fails only when some other task actually holds permits the upgrade needs.

impl BatchSemaphore

pub fn signature(&self) -> &ResourceSignature

Returns a reference to this semaphore’s resource signature.

Trait Implementations

impl Debug for BatchSemaphore

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for BatchSemaphore

fn default() -> BatchSemaphore

Returns the “default value” for a type.

impl Send for BatchSemaphore

impl Sync for BatchSemaphore

impl WithName for &BatchSemaphore

fn with_name_and_kind( self, name: Option<&str>, kind: Option<&str>, ) -> &BatchSemaphore

Set the name and kind (full type path) of this object.

fn with_name(self, name: &str) -> Self

where Self: Sized,

Set the name of this object.

fn with_kind(self, kind: &str) -> Self

where Self: Sized,

Set the kind (full type path) of this object.

impl WithName for BatchSemaphore

fn with_name_and_kind( self, name: Option<&str>, kind: Option<&str>, ) -> BatchSemaphore

Set the name and kind (full type path) of this object.

fn with_name(self, name: &str) -> Self

where Self: Sized,

Set the name of this object.

fn with_kind(self, kind: &str) -> Self

where Self: Sized,

Set the kind (full type path) of this object.