1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
//! Fixed-capacity, FIFO virtual semaphores.
use super::gate::Gate;
use crate::{Error, Result, SuspensionReason};
/// A fixed pool of permits with FIFO selection and bounded outstanding waits.
pub struct Semaphore {
pub(super) gate: Gate,
}
/// One permit; dropping it returns capacity even during task reclamation.
#[must_use = "dropping a permit immediately returns its capacity"]
pub struct Permit<'a> {
semaphore: &'a Semaphore,
}
impl Semaphore {
/// Creates a positive fixed permit pool using [`super::DEFAULT_WAIT_CAPACITY`].
pub fn new(permits: usize) -> Result<Self> {
Self::with_wait_capacity(permits, super::DEFAULT_WAIT_CAPACITY)
}
/// Creates a positive fixed permit pool and positive waiter limit.
pub fn with_wait_capacity(permits: usize, wait_capacity: usize) -> Result<Self> {
if permits == 0 {
return Err(Error::invalid_configuration(
crate::error::ConfigurationField::Permits,
"must be positive",
));
}
Ok(Self {
gate: Gate::new(permits, permits, wait_capacity)?,
})
}
/// Acquires one permit, parking the virtual caller when necessary.
pub fn acquire(&self) -> Result<Permit<'_>> {
self.acquire_for(SuspensionReason::Semaphore)
}
pub(super) fn acquire_for(&self, reason: SuspensionReason) -> Result<Permit<'_>> {
self.gate.take(reason)?;
Ok(Permit { semaphore: self })
}
/// Acquires immediately without bypassing previously selected waiters.
pub fn try_acquire(&self) -> Result<Permit<'_>> {
self.gate.try_take()?;
Ok(Permit { semaphore: self })
}
/// Stops acquisitions and wakes waiters with `Error::Closed`.
/// Existing permits remain valid until dropped.
pub fn close(&self) {
self.gate.close();
}
/// Whether new acquisitions are closed.
pub fn is_closed(&self) -> bool {
self.gate.is_closed()
}
/// Unreserved capacity, excluding selected tickets and held permits.
pub fn available_permits(&self) -> usize {
self.gate.available()
}
/// Outstanding wait tickets, including selected but unconsumed permits.
pub fn waiting(&self) -> usize {
self.gate.waiting()
}
/// Configured outstanding-wait limit, including selected waiters.
pub fn wait_capacity(&self) -> usize {
self.gate.wait_capacity()
}
}
impl Drop for Permit<'_> {
fn drop(&mut self) {
self.semaphore.gate.signal();
}
}
#[cfg(test)]
#[path = "semaphore_test.rs"]
mod semaphore_test;