Struct Semaphore 

pub struct Semaphore { /* private fields */ }

A counting semaphore whose waits are futures, for the tasks of one shard.

A request for n permits waits in line behind the requests that arrived before it, and is granted when it reaches the front and n permits are free. A large request at the front is therefore never bypassed by smaller ones behind it, and try_acquire fails while anyone waits. close ends every wait with an AcquireError.

It is !Send and !Sync: share it between the tasks of a shard with an Rc.

use nuclei::sync::TryAcquireError;
use nuclei::sync::local::Semaphore;

let budget = Semaphore::new(4);
let first = budget.try_acquire_many(3).expect("three of four are free");
assert_eq!(budget.try_acquire_many(2).unwrap_err(), TryAcquireError::NoPermits);
drop(first);
assert_eq!(budget.available_permits(), 4);

Implementations

impl Semaphore

pub const MAX_PERMITS: usize

The most permits a semaphore can hold: usize::MAX >> 3.

pub const fn new(permits: usize) -> Self

A semaphore holding permits permits.

Panics

When permits exceeds MAX_PERMITS.

pub fn available_permits(&self) -> usize

The permits free right now, including the ones kept for the front waiter until its request fits.

pub fn add_permits(&self, n: usize)

Adds n new permits, handing them to waiters first. Permits added to a closed semaphore are counted, but nothing is handed out.

Panics

When the semaphore would hold more than MAX_PERMITS.

pub fn forget_permits(&self, n: usize) -> usize

Removes up to n free permits for good and returns how many it removed, which is fewer than n when fewer are free. Permits held by outstanding SemaphorePermits are not touched.

pub fn acquire(&self) -> Acquire<'_>

Waits for one permit.

Completes with an AcquireError once the semaphore is closed.

pub fn acquire_many(&self, n: u32) -> Acquire<'_>

Waits for n permits, which it takes together.

Completes with an AcquireError once the semaphore is closed.

Panics

When n exceeds MAX_PERMITS, which only a target with a word narrower than 64 bits allows and which no semaphore can ever satisfy.

pub fn try_acquire(&self) -> Result<SemaphorePermit<'_>, TryAcquireError>

Takes one permit if it is free and nobody waits.

pub fn try_acquire_many( &self, n: u32, ) -> Result<SemaphorePermit<'_>, TryAcquireError>

Takes n permits together if they are free and nobody waits.

Panics

When n exceeds MAX_PERMITS, as for acquire_many.

pub fn close(&self)

Closes the semaphore. Every wait still queued ends in an AcquireError, and every later acquire fails at once: try_acquire and its sibling return TryAcquireError::Closed, whatever permits are free. A wait that was granted its permits before the close keeps them. Permits returned or added afterwards are counted, and available_permits shows them, but none is ever handed out. Closing twice does nothing.

pub fn is_closed(&self) -> bool

Whether close was called.

Trait Implementations

impl Debug for Semaphore

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

Formats the value using the given formatter.