Skip to main content

coven_foundation/files/
file_budget.rs

1//! The app's budget of open files: places that every open of a user's file
2//! takes, sized under the process's descriptor limit, so the app cannot run
3//! out of descriptors through those opens.
4//!
5//! A piece of work waits on the budget in one place, `FileBudget::lease`,
6//! and takes every place it will hold in that one wait. A lease hands its
7//! places out to the work's own opens, which wait only for a place one of the
8//! work's own files gives back. The budget's line is first come, first
9//! served, so a waiting lease of several places is never passed by later
10//! leases of one.
11
12use std::{io, num::NonZeroUsize, path::Path, sync::Arc};
13use tokio::sync::{OwnedSemaphorePermit, Semaphore};
14
15#[path = "file_budget_tally.rs"]
16mod tally;
17#[cfg(any(test, feature = "test-utils"))]
18pub use tally::FileBudgetWatch;
19use tally::Tally;
20
21/// The descriptor limit a platform with no limit counts as: macOS's
22/// `OPEN_MAX`.
23const UNLIMITED_DESCRIPTORS: u64 = 10240;
24
25/// The installation's places for open files, shared by every store its app
26/// opens. Cloning shares them. The app makes one when it starts, and each
27/// piece of work takes a lease of places from it (E1).
28#[derive(Clone)]
29pub struct FileBudget {
30    shared: Arc<BudgetShared>,
31}
32
33struct BudgetShared {
34    places: Arc<Semaphore>,
35    size: NonZeroUsize,
36    tally: Tally,
37}
38
39/// A lease asked for more places than the budget has, so no wait could
40/// grant it.
41#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
42#[error("a lease of {requested} places asks for more than the budget's {size}")]
43pub struct LeaseTooLarge {
44    /// The places the lease asked for.
45    pub requested: usize,
46    /// The places the budget has.
47    pub size: usize,
48}
49
50/// Places taken from a budget in one wait, for one piece of work. The work's
51/// openers share it by cloning it. The places go back to the budget once the
52/// lease, every place taken from it and every file opened in one are gone.
53#[derive(Clone)]
54pub struct FileLease {
55    shared: Arc<LeaseShared>,
56}
57
58struct LeaseShared {
59    places: Arc<Semaphore>,
60    count: usize,
61    budget: Arc<BudgetShared>,
62    // Returns the places to the budget after the lease's own accounting.
63    _held: OwnedSemaphorePermit,
64}
65
66/// One place of a lease, taken for one open: a file of a user, or a stream
67/// whose bytes come from no such file. It goes back to its lease when it
68/// drops.
69pub struct LeasePlace {
70    // Drops first, before the lease it returns to.
71    _permit: OwnedSemaphorePermit,
72    lease: Arc<LeaseShared>,
73}
74
75/// An open file holding its place. The file closes before the place goes
76/// back.
77pub struct LeasedFile<F> {
78    // Declared first: fields drop in order, so the file closes before its
79    // place goes back.
80    file: F,
81    _place: LeasePlace,
82}
83
84impl FileBudget {
85    /// A budget of `size` places, at most `u32::MAX`. The app makes one
86    /// with `under_descriptor_limit`; a test that needs a size makes it here.
87    pub fn new(size: NonZeroUsize) -> Self {
88        let size = size.min(NonZeroUsize::new(u32::MAX as usize).expect("u32::MAX is not zero"));
89        Self {
90            shared: Arc::new(BudgetShared {
91                places: Arc::new(Semaphore::new(size.get())),
92                size,
93                tally: Tally::new(),
94            }),
95        }
96    }
97
98    /// A budget of an eighth of the process's descriptor limit, at least 1:
99    /// 32 places under a macOS app's limit of 256, 128 under 1024. A
100    /// process with no limit counts as 10240, macOS's `OPEN_MAX`, and so does
101    /// Windows, where the handles `std::fs` and SQLite open have no limit.
102    ///
103    /// One place stands for at most 4 descriptors: the file it opens, or the
104    /// cache files a stream's reads in flight open (at most 3), and one file
105    /// the work writes beside it. The places therefore take at most half the
106    /// limit, and the other half holds what the budget doesn't count: each open
107    /// store's database files, locks, sockets and the platform's own
108    /// descriptors. The limit is read once, here.
109    pub fn under_descriptor_limit() -> Self {
110        Self::new(size_for_limit(soft_descriptor_limit()))
111    }
112
113    /// How many places the budget has.
114    pub fn size(&self) -> usize {
115        self.shared.size.get()
116    }
117
118    /// Take `count` places in one wait, behind every lease that began
119    /// waiting before. Call it only while holding no place of this budget:
120    /// a holder that waits here can wait forever. A `count` above the
121    /// budget's size fails at once.
122    pub async fn lease(&self, count: usize) -> Result<FileLease, LeaseTooLarge> {
123        let size = self.size();
124        let wanted = u32::try_from(count)
125            .ok()
126            .filter(|_| count <= size)
127            .ok_or(LeaseTooLarge { requested: count, size })?;
128        // The first poll of the acquire puts this lease in the line, so the
129        // wait is recorded only after it: a test that sees the wait knows
130        // every lease it counts is already behind the ones before it.
131        let mut acquire = Box::pin(self.shared.places.clone().acquire_many_owned(wanted));
132        let held = match futures_lite::future::poll_once(&mut acquire).await {
133            Some(held) => held,
134            None => {
135                self.shared.tally.waited();
136                acquire.await
137            }
138        }
139        .expect("the budget's semaphore is never closed");
140        Ok(self.granted(count, held))
141    }
142
143    /// [`Self::lease`], blocking this thread in the same line as the async
144    /// leases. Call it only off the async workers: on the blocking pool or a
145    /// thread of the caller's own.
146    pub fn lease_blocking(&self, count: usize) -> Result<FileLease, LeaseTooLarge> {
147        futures_lite::future::block_on(self.lease(count))
148    }
149
150    fn granted(&self, count: usize, held: OwnedSemaphorePermit) -> FileLease {
151        self.shared.tally.leased(count);
152        FileLease {
153            shared: Arc::new(LeaseShared {
154                places: Arc::new(Semaphore::new(count)),
155                count,
156                budget: self.shared.clone(),
157                _held: held,
158            }),
159        }
160    }
161
162    /// What a test reads of this budget's use.
163    #[cfg(any(test, feature = "test-utils"))]
164    pub fn watch(&self) -> FileBudgetWatch {
165        FileBudgetWatch::of(self.shared.clone())
166    }
167}
168
169/// The places of a budget a test's installation has.
170#[cfg(any(test, feature = "in-memory-keychain"))]
171const TEST_PLACES: usize = 64;
172
173#[cfg(any(test, feature = "in-memory-keychain"))]
174impl FileBudget {
175    /// A budget of 64 places, as an installation made for a test has, with
176    /// no other budget's work competing for them.
177    pub fn for_test() -> Self {
178        Self::new(NonZeroUsize::new(TEST_PLACES).expect("64 is not zero"))
179    }
180}
181
182#[cfg(any(test, feature = "test-utils"))]
183impl FileLease {
184    /// All 64 places of a budget of its own, for a test that opens files
185    /// without a budget to watch.
186    pub async fn for_test() -> Self {
187        FileBudget::for_test().lease(TEST_PLACES).await.expect("a test budget holds its own size")
188    }
189}
190
191#[cfg(any(test, feature = "test-utils"))]
192impl LeasePlace {
193    /// One place of a budget of its own, for a test that opens a file without
194    /// a budget to watch.
195    pub async fn for_test() -> Self {
196        FileLease::for_test().await.place().await
197    }
198}
199
200impl std::fmt::Debug for FileBudget {
201    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
202        f.debug_struct("FileBudget").field("size", &self.shared.size).finish_non_exhaustive()
203    }
204}
205
206impl FileLease {
207    /// One place of this lease, for one open. It waits only for a place the
208    /// work's own files give back, never for the budget.
209    pub async fn place(&self) -> LeasePlace {
210        let permit = self
211            .shared
212            .places
213            .clone()
214            .acquire_owned()
215            .await
216            .expect("a lease's semaphore is never closed");
217        LeasePlace::taken(permit, self.shared.clone())
218    }
219
220    /// [`Self::place`], blocking this thread. Call it only off the async
221    /// workers: on the blocking pool or a thread of the caller's own.
222    pub fn place_blocking(&self) -> LeasePlace {
223        futures_lite::future::block_on(self.place())
224    }
225
226    /// How many places the lease took.
227    pub fn count(&self) -> usize {
228        self.shared.count
229    }
230}
231
232impl std::fmt::Debug for FileLease {
233    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
234        f.debug_struct("FileLease").field("count", &self.shared.count).finish_non_exhaustive()
235    }
236}
237
238impl Drop for LeaseShared {
239    fn drop(&mut self) {
240        self.budget.tally.returned(self.count);
241    }
242}
243
244impl LeasePlace {
245    fn taken(permit: OwnedSemaphorePermit, lease: Arc<LeaseShared>) -> Self {
246        lease.budget.tally.holding();
247        Self { _permit: permit, lease }
248    }
249
250    /// Open the file at `path` in this place. A failed open gives the place
251    /// back.
252    pub fn open(self, path: &Path) -> io::Result<LeasedFile<std::fs::File>> {
253        Ok(LeasedFile { file: std::fs::File::open(path)?, _place: self })
254    }
255
256    /// Open the file at `path` in this place, as [`Self::open`].
257    pub async fn open_async(self, path: &Path) -> io::Result<LeasedFile<tokio::fs::File>> {
258        Ok(LeasedFile { file: tokio::fs::File::open(path).await?, _place: self })
259    }
260}
261
262impl Drop for LeasePlace {
263    fn drop(&mut self) {
264        self.lease.budget.tally.released();
265    }
266}
267
268impl<F> std::ops::Deref for LeasedFile<F> {
269    type Target = F;
270    fn deref(&self) -> &F {
271        &self.file
272    }
273}
274
275impl<F> std::ops::DerefMut for LeasedFile<F> {
276    fn deref_mut(&mut self) -> &mut F {
277        &mut self.file
278    }
279}
280
281/// The soft limit on the process's open descriptors; `None` for no limit,
282/// and on Windows, which has none for the handles coven opens.
283fn soft_descriptor_limit() -> Option<u64> {
284    #[cfg(unix)]
285    {
286        rustix::process::getrlimit(rustix::process::Resource::Nofile).current
287    }
288    #[cfg(not(unix))]
289    {
290        None
291    }
292}
293
294/// The size of a budget under a descriptor limit: an eighth of it, at least
295/// 1. No limit counts as 10240.
296fn size_for_limit(limit: Option<u64>) -> NonZeroUsize {
297    let places = limit.unwrap_or(UNLIMITED_DESCRIPTORS) / 8;
298    let places = usize::try_from(places).unwrap_or(usize::MAX);
299    NonZeroUsize::new(places).unwrap_or(NonZeroUsize::MIN)
300}
301
302#[cfg(test)]
303#[path = "file_budget_tests.rs"]
304mod tests;