Struct Semaphore 

pub struct Semaphore { /* private fields */ }

A Semaphore maintains the number of permits it is still allowed to give.

• When acquire() is called and the semaphore still has permits to give, it will return a Permit. If there are no permits that can be given, it will wait for one permit to be given back from a thread so that it can return a new Permit.
• When try_acquire() is called and the semaphore still has permits to give, it will return Some(Permit). If there are no permits that can be given, it will return None.

Implementations

impl Semaphore

pub fn new(permits: usize) -> Arc<Self>

Returns a new Arc<Semaphore> with the limit of permits chosen by you.

Examples found in repository

examples/main.rs (line 7)

fn main() {
    let semaphore = simple_semaphore::Semaphore::new(2);

    for _ in 0..5 {
        let semaphore = Arc::clone(&semaphore);
        thread::spawn(move || {
            let permit = semaphore.acquire();
            thread::sleep(Duration::from_millis(500));
            drop(permit);
        });
    }
    thread::sleep(Duration::from_millis(3000));

    let available_machine_parallelism = available_parallelism().unwrap().get();

    let semaphore = simple_semaphore::Semaphore::new_available_parallelism().unwrap(); // Also uses `available_parallelism()` internally
    for _ in 0..(available_machine_parallelism + 2) {
        let semaphore = Arc::clone(&semaphore);
        thread::spawn(move || {
            if let Some(permit) = semaphore.try_acquire() {
                thread::sleep(Duration::from_millis(500));
                drop(permit);
            } else {
                println!("Too many permits given, exiting the thread"); // Will be printed twice
            }
        });
    }
    thread::sleep(Duration::from_millis(
        (((available_machine_parallelism + 1) * 1000) / 2) as u64,
    ));
}

pub fn new_available_parallelism() -> Result<Arc<Self>, String>

Returns a new Arc<Semaphore> with the limit of permits set to the machine’s parallelism value, usually CPU cores.

Examples found in repository

examples/main.rs (line 21)

fn main() {
    let semaphore = simple_semaphore::Semaphore::new(2);

    for _ in 0..5 {
        let semaphore = Arc::clone(&semaphore);
        thread::spawn(move || {
            let permit = semaphore.acquire();
            thread::sleep(Duration::from_millis(500));
            drop(permit);
        });
    }
    thread::sleep(Duration::from_millis(3000));

    let available_machine_parallelism = available_parallelism().unwrap().get();

    let semaphore = simple_semaphore::Semaphore::new_available_parallelism().unwrap(); // Also uses `available_parallelism()` internally
    for _ in 0..(available_machine_parallelism + 2) {
        let semaphore = Arc::clone(&semaphore);
        thread::spawn(move || {
            if let Some(permit) = semaphore.try_acquire() {
                thread::sleep(Duration::from_millis(500));
                drop(permit);
            } else {
                println!("Too many permits given, exiting the thread"); // Will be printed twice
            }
        });
    }
    thread::sleep(Duration::from_millis(
        (((available_machine_parallelism + 1) * 1000) / 2) as u64,
    ));
}

pub fn available_permits(self: &Arc<Self>) -> usize

Returns the number of available permits

pub fn acquire(self: &Arc<Self>) -> Permit

Tries to get a Permit. If no more permits can be given, it will wait for one permit to be given back from a thread so that it can return a new Permit.

Examples found in repository

examples/main.rs (line 12)

fn main() {
    let semaphore = simple_semaphore::Semaphore::new(2);

    for _ in 0..5 {
        let semaphore = Arc::clone(&semaphore);
        thread::spawn(move || {
            let permit = semaphore.acquire();
            thread::sleep(Duration::from_millis(500));
            drop(permit);
        });
    }
    thread::sleep(Duration::from_millis(3000));

    let available_machine_parallelism = available_parallelism().unwrap().get();

    let semaphore = simple_semaphore::Semaphore::new_available_parallelism().unwrap(); // Also uses `available_parallelism()` internally
    for _ in 0..(available_machine_parallelism + 2) {
        let semaphore = Arc::clone(&semaphore);
        thread::spawn(move || {
            if let Some(permit) = semaphore.try_acquire() {
                thread::sleep(Duration::from_millis(500));
                drop(permit);
            } else {
                println!("Too many permits given, exiting the thread"); // Will be printed twice
            }
        });
    }
    thread::sleep(Duration::from_millis(
        (((available_machine_parallelism + 1) * 1000) / 2) as u64,
    ));
}

pub fn try_acquire(self: &Arc<Self>) -> Option<Permit>

Tries to get a Option<Permit>. If no more permits can be given, it will return None.

Examples found in repository

examples/main.rs (line 25)

fn main() {
    let semaphore = simple_semaphore::Semaphore::new(2);

    for _ in 0..5 {
        let semaphore = Arc::clone(&semaphore);
        thread::spawn(move || {
            let permit = semaphore.acquire();
            thread::sleep(Duration::from_millis(500));
            drop(permit);
        });
    }
    thread::sleep(Duration::from_millis(3000));

    let available_machine_parallelism = available_parallelism().unwrap().get();

    let semaphore = simple_semaphore::Semaphore::new_available_parallelism().unwrap(); // Also uses `available_parallelism()` internally
    for _ in 0..(available_machine_parallelism + 2) {
        let semaphore = Arc::clone(&semaphore);
        thread::spawn(move || {
            if let Some(permit) = semaphore.try_acquire() {
                thread::sleep(Duration::from_millis(500));
                drop(permit);
            } else {
                println!("Too many permits given, exiting the thread"); // Will be printed twice
            }
        });
    }
    thread::sleep(Duration::from_millis(
        (((available_machine_parallelism + 1) * 1000) / 2) as u64,
    ));
}

pub fn release(&self)

Releases a permit. This is what drop() on Permit calls, ideally use drop(permit).

Trait Implementations

impl Debug for Semaphore

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

Formats the value using the given formatter.