Struct OwnedRankedSemaphorePermit

Source

pub struct OwnedRankedSemaphorePermit { /* private fields */ }

Expand description

An owned permit that grants access to a resource protected by a semaphore.

This permit owns a reference to the semaphore (via Arc) and represents one or more permits that have been acquired. When the permit is dropped, the permits are automatically returned to the semaphore.

§Examples

use ranked_semaphore::RankedSemaphore;
use std::sync::Arc;

let sem = Arc::new(RankedSemaphore::new_fifo(3));
let permit = sem.acquire_owned().await.unwrap();
assert_eq!(permit.num_permits(), 1);
// Permit is automatically returned when dropped

Implementations§

Source §

impl OwnedRankedSemaphorePermit

Source

pub fn forget(self)

Forgets this permit without releasing it back to the semaphore.

This effectively removes the permits from circulation permanently. Use this method when you want to prevent the permits from being returned to the semaphore when the permit is dropped.

§Examples

use ranked_semaphore::RankedSemaphore;
use std::sync::Arc;

let sem = Arc::new(RankedSemaphore::new_fifo(3));
let permit = sem.clone().acquire_owned().await.unwrap();
 
assert_eq!(sem.available_permits(), 2);
permit.forget(); // Permit is not returned to semaphore
assert_eq!(sem.available_permits(), 2);

Source

pub fn num_permits(&self) -> usize

Returns the number of permits held by this permit object.

§Examples

use ranked_semaphore::RankedSemaphore;
use std::sync::Arc;

let sem = Arc::new(RankedSemaphore::new_fifo(5));
let permit = sem.acquire_many_owned(3).await.unwrap();
assert_eq!(permit.num_permits(), 3);

Source

pub fn merge(&mut self, other: Self)

Merges another permit into this one, combining their permit counts.

Both permits must belong to the same semaphore instance. After merging, the other permit becomes invalid (holds 0 permits) and this permit holds the combined count.

§Arguments

other - Another permit from the same semaphore to merge

§Panics

Panics if the permits belong to different semaphores.

§Examples

use ranked_semaphore::RankedSemaphore;
use std::sync::Arc;

let sem = Arc::new(RankedSemaphore::new_fifo(5));
let mut permit1 = sem.clone().acquire_many_owned(2).await.unwrap();
let permit2 = sem.acquire_many_owned(1).await.unwrap();
 
permit1.merge(permit2);
assert_eq!(permit1.num_permits(), 3);

Source

pub fn split(&mut self, n: usize) -> Option<Self>

Splits off a specified number of permits into a new owned permit.

This reduces the current permit’s count by n and returns a new owned permit holding n permits. If there are insufficient permits, returns None.

§Arguments

n - The number of permits to split off

§Returns

Some(OwnedRankedSemaphorePermit) - New permit holding n permits
None - If this permit holds fewer than n permits or n doesn’t fit in u32

§Examples

use ranked_semaphore::RankedSemaphore;
use std::sync::Arc;

let sem = Arc::new(RankedSemaphore::new_fifo(5));
let mut permit = sem.acquire_many_owned(3).await.unwrap();
 
let split_permit = permit.split(2).unwrap();
assert_eq!(permit.num_permits(), 1);
assert_eq!(split_permit.num_permits(), 2);

Source

pub fn semaphore(&self) -> &Arc<RankedSemaphore>

Returns a reference to the semaphore from which this permit was acquired.

§Examples

use ranked_semaphore::RankedSemaphore;
use std::sync::Arc;

let sem = Arc::new(RankedSemaphore::new_fifo(3));
let permit = sem.acquire_owned().await.unwrap();
 
let sem_ref = permit.semaphore();
assert_eq!(sem_ref.available_permits(), 2);