Struct BatchSemaphore 

pub struct BatchSemaphore { /* private fields */ }

Counting semaphore

Implementations

impl BatchSemaphore

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

Creates a new semaphore with the initial number of permits.

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

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

Creates a new semaphore with the initial number of permits.

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

pub fn available_permits(&self) -> usize

Returns the current number of available permits.

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

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

Formats the value using the given formatter.

impl Default for BatchSemaphore

fn default() -> Self

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>) -> Self

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>) -> Self

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.