Struct glommio::sync::Semaphore [−][src]
pub struct Semaphore { /* fields omitted */ }
An implementation of semaphore that doesn’t use helper threads, condition variables, and is friendly to single-threaded execution.
Implementations
impl Semaphore
[src]
impl Semaphore
[src]pub fn new(avail: u64) -> Semaphore
[src]
Creates a new semaphore with the specified amount of units
Examples
use glommio::sync::Semaphore; let _ = Semaphore::new(1);
pub fn available(&self) -> u64
[src]
Returns the amount of units currently available in this semaphore
Examples
use glommio::sync::Semaphore; let sem = Semaphore::new(1); assert_eq!(sem.available(), 1);
pub async fn acquire_permit(&self, units: u64) -> Result<Permit<'_>, ()>
[src]
Suspends until a permit can be acquired with the specified amount of units.
Returns Err() if the semaphore is closed during the wait.
Similar to acquire_static_permit
, except that it requires the permit
never to be passed to contexts that require a static lifetime. As
this is cheaper than acquire_static_permit
, it is useful in
situations where the permit tracks an a asynchronous operation whose
lifetime is simple and well-defined.
Examples
use glommio::{sync::Semaphore, LocalExecutor}; let sem = Semaphore::new(1); let ex = LocalExecutor::default(); ex.run(async move { { let permit = sem.acquire_permit(1).await.unwrap(); // once it is dropped it can be acquired again // going out of scope will drop } let _guard = sem.acquire_permit(1).await.unwrap(); });
pub async fn acquire_static_permit(
self: &Rc<Self>,
units: u64
) -> Result<StaticPermit, ()>
[src]
self: &Rc<Self>,
units: u64
) -> Result<StaticPermit, ()>
Suspends until a permit can be acquired with the specified amount of units.
Returns Err() if the semaphore is closed during the wait.
Similar to acquire_permit
, except that it requires the semaphore to
be contained in an Rc
. This is useful in situations where the
permit tracks a long-lived asynchronous operation whose lifetime is
complex.
Examples
use glommio::{sync::Semaphore, timer::sleep, Local, LocalExecutor}; use std::{rc::Rc, time::Duration}; let sem = Rc::new(Semaphore::new(1)); let ex = LocalExecutor::default(); ex.run(async move { { let permit = sem.acquire_static_permit(1).await.unwrap(); Local::local(async move { let _guard = permit; sleep(Duration::from_secs(1)).await; }) .detach(); // once it is dropped it can be acquired again // going out of scope will drop } let _guard = sem.acquire_permit(1).await.unwrap(); });
pub async fn acquire(&self, units: u64) -> Result<(), ()>
[src]
Acquires the specified amount of units from this semaphore.
The caller is then responsible to release units. Whenever possible, prefer acquire_permit().
Examples
use glommio::{sync::Semaphore, LocalExecutor}; let sem = Semaphore::new(1); let ex = LocalExecutor::default(); ex.run(async move { sem.acquire(1).await.unwrap(); sem.signal(1); // Has to be signaled explicitly. Be careful });
pub fn try_acquire(&self, units: u64) -> Result<bool, ()>
[src]
Acquires the given number of units, if they are available, and returns immediately, with the value true, reducing the number of available units by the given amount.
If insufficient units are available then this method will return
immediately with the value false
and the number of available
permits is unchanged.
This method does not suspend.
The caller is then responsible to release units. Whenever possible,
prefer try_acquire_permit
.
Errors
If semaphore is closed Err(io::Error(BrokenPipe))
will be returned.
Examples
use glommio::{sync::Semaphore, LocalExecutor}; let sem = Semaphore::new(1); let ex = LocalExecutor::default(); ex.run(async move { assert!(sem.try_acquire(1).unwrap()); sem.signal(1); // Has to be signaled explicitly. Be careful });
pub fn try_acquire_permit(&self, units: u64) -> Result<Permit<'_>, ()>
[src]
Acquires the given number of units, if they are available, and returns immediately, with the RAAI guard, reducing the number of available units by the given amount.
If insufficient units are available then this method will return
Err
and the number of available permits is unchanged.
This method does not suspend.
Errors
If semaphore is closed
Err(GlommioError::Closed(ResourceType::Semaphore { .. }))
will be
returned. If semaphore does not have sufficient amount of units
Err(GlommioError::WouldBlock(ResourceType::Semaphore { requested: u64, available: u64 }))
will be returned.
Examples
use glommio::{sync::Semaphore, LocalExecutor}; let sem = Semaphore::new(1); let ex = LocalExecutor::default(); ex.run(async move { let permit = sem.acquire_permit(1).await.unwrap(); // once it is dropped it can be acquired again // going out of scope will drop });
pub fn signal(&self, units: u64)
[src]
Signals the semaphore to release the specified amount of units.
This needs to be paired with a call to acquire(). You should not call this if the units were acquired with acquire_permit().
Examples
use glommio::{sync::Semaphore, LocalExecutor}; let sem = Semaphore::new(0); let ex = LocalExecutor::default(); ex.run(async move { // Note that we can signal to expand to more units than the original capacity had. sem.signal(1); sem.acquire(1).await.unwrap(); });
pub fn close(&self)
[src]
Closes the semaphore
All existing waiters will return Err(), and no new waiters are allowed.
Examples
use glommio::{sync::Semaphore, LocalExecutor}; let sem = Semaphore::new(0); let ex = LocalExecutor::default(); ex.run(async move { // Note that we can signal to expand to more units than the original capacity had. sem.close(); if let Ok(_) = sem.acquire(1).await { panic!("a closed semaphore should have errored"); } });
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Semaphore
impl !RefUnwindSafe for Semaphore
impl !UnwindSafe for Semaphore
impl !UnwindSafe for Semaphore