Struct AdjustableSemaphore 

pub struct AdjustableSemaphore { /* private fields */ }

An adjustable semaphore in which the total number of permits can be adjusted at any time between a minimum and a maximum bound.

Unlike the tokio Semaphore, decreasing the number of permits may be done at any time and are resolved lazily if needed; any permits currently issued remain valid, but no new permits are issued until any requested decreases are resolved.

When max_permits exceeds the platform semaphore limit, a scaling basis is automatically computed so that all permit operations are transparently mapped to a smaller number of internal permits. On 64-bit platforms the basis is 1 for any practical permit count.

Implementations

impl AdjustableSemaphore

pub fn new(initial_permits: u64, permit_range: (u64, u64)) -> Arc<Self>

pub fn total_permits(&self) -> u64

pub fn available_permits(&self) -> u64

pub fn active_permits(&self) -> u64

pub fn basis(&self) -> u64

The scaling basis. Each internal permit represents this many logical permits. On 64-bit platforms this is 1 for any practical permit count.

pub async fn acquire( self: &Arc<Self>, ) -> Result<AdjustableSemaphorePermit, AcquireError>

Acquire a single permit.

pub async fn acquire_many( self: &Arc<Self>, n: u64, ) -> Result<AdjustableSemaphorePermit, AcquireError>

Acquire n logical permits. The request is scaled and clamped to the total permit count so that a single acquire can always succeed once enough permits are freed.

pub fn decrement_total_permits(&self, n: u64) -> Option<u64>

Decrement the total number of permits by up to n (logical) down to the minimum bound. Note that this does not affect any permits currently issued; in the case where all permits are currently issued, no new permits will be issued until the adjustment has been resolved.

Returns the logical amount decreased, or None if no adjustment occurred.

pub fn decrement_permits_to_target(&self, target: u64) -> Option<u64>

Adjust total permits downward to target (logical) if the current total is above it. Returns the logical amount that was requested to be decreased, or None if no adjustment was needed.

Acquires an internal lock to serialize with other target-based adjustments, preventing read-then-modify races. The underlying decrement_total_permits handles clamping at the minimum bound.

pub fn increment_total_permits( self: &Arc<Self>, n: u64, ) -> Option<AdjustableSemaphorePermit>

Increment the total number of permits by up to n (logical) up to the maximum bound.

Returns a permit holding the newly added capacity, or None if no permits could be added (already at max). The permits enter the semaphore when the returned permit is dropped. This allows a user to acquire a permit immediately that bypasses the FIFO queue so the caller can hold them without contention. If the returned permit is dropped immediately, then this simply increments the available permits in the semaphore.

pub fn increment_permits_to_target( self: &Arc<Self>, target: u64, ) -> Option<AdjustableSemaphorePermit>

Adjust total permits upward to target (logical) if the current total is below it. Returns a virtual permit holding the increase, or None if no adjustment was needed or possible.

Acquires an internal lock to serialize with other target-based adjustments, preventing read-then-modify races. The underlying increment_total_permits handles clamping at the maximum bound.

Trait Implementations

impl Debug for AdjustableSemaphore

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

Formats the value using the given formatter.