Skip to main content

mnemo_engine/shared/
lock.rs

1//! The per-call lock loop (12.4 design note, "The protocol" steps 2 to 4 and
2//! 9, "Writer preference", "Long operations"): one deadline and a cancel per
3//! call, jittered backoff, writer preference through the sidecar's intent
4//! lock with a reader that holds it for one try only, and the identity check
5//! once the main lock is held.
6//!
7//! Every lock here goes through [`LockedFile`], so it's unlocked explicitly
8//! before its descriptor closes (FLAKE-1).
9
10use std::fs::{File, OpenOptions};
11use std::path::{Path, PathBuf};
12use std::sync::Arc;
13use std::time::{Duration, SystemTime, UNIX_EPOCH};
14
15use fs4::fs_std::FileExt;
16
17use super::call::{Call, CancelToken};
18use super::fscheck;
19use super::sidecar::{self, Sidecar, SidecarState, INTENT};
20use crate::error::{MnemoError, Result};
21use crate::pager::LockedFile;
22use crate::store::{is_file_at, is_lock_conflict};
23
24/// Options for a shared-mode handle (12.4).
25#[derive(Clone, Debug)]
26#[non_exhaustive]
27pub struct SharedOptions {
28    /// How long one call may wait for the file's lock before it fails with
29    /// [`MnemoError::Locked`]. One deadline covers both locks and the
30    /// retries after a compaction. Default 10 s; hooks pass 2 s.
31    pub deadline: Duration,
32    /// Use shared mode on a network or synced filesystem anyway, where the
33    /// lock may not reach every process that opens the file.
34    ///
35    /// The check refuses network filesystems (on Linux, anything but ext4,
36    /// xfs, btrfs, tmpfs, f2fs, overlayfs and zfs; overlayfs assumes Linux
37    /// 4.19 or later) and, on macOS, iCloud Drive and File Provider folders.
38    /// On Windows it refuses UNC paths; a drive letter mapped to a network
39    /// share may not be detected.
40    pub allow_network_fs: bool,
41    /// Cancels the handle's waiting calls from another thread.
42    pub cancel: Option<CancelToken>,
43}
44
45impl Default for SharedOptions {
46    fn default() -> Self {
47        SharedOptions {
48            deadline: Duration::from_secs(10),
49            allow_network_fs: false,
50            cancel: None,
51        }
52    }
53}
54
55/// Which lock a call takes.
56#[derive(Clone, Copy, PartialEq, Eq, Debug)]
57pub(crate) enum LockKind {
58    /// Reads.
59    Shared,
60    /// Writes.
61    Exclusive,
62}
63
64/// The lock layer for one brain: where it is, its sidecar, and the notices
65/// to give once.
66#[derive(Debug)]
67pub(crate) struct BrainLocks {
68    /// The path as given (made absolute), which the locks open and the
69    /// identity check compares.
70    path: PathBuf,
71    /// The path with symlinks resolved, where the sidecar directory lives.
72    resolved: PathBuf,
73    sidecar: Option<Arc<Sidecar>>,
74    notices: Vec<String>,
75}
76
77/// The Windows refusal before Rust 1.85 (see `build.rs`).
78pub(crate) const WINDOWS_OLD_RENAME: bool = cfg!(mnemo_windows_old_rename);
79
80impl BrainLocks {
81    /// Set up the lock layer for the brain at `path`. Refuses a Windows
82    /// build before Rust 1.85, a missing file (never creates one), and a
83    /// network or synced filesystem unless `allow_network_fs`.
84    pub(crate) fn new(path: &Path, opts: &SharedOptions) -> Result<Self> {
85        Self::with_sidecar(path, opts, true)
86    }
87
88    /// [`BrainLocks::new`] for a plain long operation (compaction, an
89    /// import, a rekey): it uses the sidecar directory only if one is
90    /// already there. A shared handle makes it when it opens, so without
91    /// one there's no shared caller to queue against, and a brain nobody
92    /// opens in shared mode gains no sibling.
93    pub(crate) fn for_plain(path: &Path, opts: &SharedOptions) -> Result<Self> {
94        Self::with_sidecar(path, opts, false)
95    }
96
97    fn with_sidecar(path: &Path, opts: &SharedOptions, create: bool) -> Result<Self> {
98        if WINDOWS_OLD_RENAME {
99            return Err(MnemoError::Unsupported(
100                "shared mode on Windows needs a build with Rust 1.85 or later (this one was \
101                 built with an older compiler, whose std::fs::rename can't replace an open \
102                 file)"
103                    .into(),
104            ));
105        }
106        let path = if path.is_absolute() {
107            path.to_path_buf()
108        } else {
109            std::env::current_dir()?.join(path)
110        };
111        // Symlinks resolved, so two paths through a symlinked directory find
112        // one sidecar. A missing file is an error here: shared mode never
113        // creates the brain.
114        let resolved = std::fs::canonicalize(&path)?;
115        let mut notices = fscheck::check(&resolved, opts.allow_network_fs)?;
116        let present = std::fs::symlink_metadata(sidecar::sidecar_path(&resolved)).is_ok();
117        let sidecar = if !create && !present {
118            None
119        } else {
120            match sidecar::open(&resolved) {
121                SidecarState::Ready(s) => Some(Arc::new(s)),
122                SidecarState::Unavailable(why) => {
123                    notices.push(format!(
124                        "not using the sidecar directory: {why}; each call takes the main \
125                         lock alone, without writer preference or a lock-info note"
126                    ));
127                    None
128                }
129            }
130        };
131        Ok(BrainLocks {
132            path,
133            resolved,
134            sidecar,
135            notices,
136        })
137    }
138
139    /// The warnings to show once: a sidecar that can't be used, a synced
140    /// folder, an allowed network filesystem.
141    pub(crate) fn notices(&self) -> &[String] {
142        &self.notices
143    }
144
145    /// Whether the sidecar directory is in use.
146    pub(crate) fn has_sidecar(&self) -> bool {
147        self.sidecar.is_some()
148    }
149
150    /// The sidecar directory, when in use.
151    pub(crate) fn sidecar_path(&self) -> Option<&Path> {
152        self.sidecar.as_deref().map(Sidecar::path)
153    }
154
155    /// Take the main lock for one call, within the call's deadline, unless
156    /// cancelled. Writers queue on the intent lock: a writer holds it
157    /// exclusively while it waits for the main lock, so new readers queue
158    /// behind it. But readers already waiting go first, so readers looping
159    /// back to back slow a writer, and enough of them can keep it out past
160    /// its deadline (`Locked`; `docs/shared-mode.md`, "How busy a file can
161    /// get"; LOCK-2 is the planned fix).
162    ///
163    /// A reader takes the intent lock shared and tries the main lock. When
164    /// the main lock is free or held shared, it gets in (RB-006.4 rec. 1).
165    /// When the main lock is held exclusively (a shared try fails only
166    /// then), the reader **keeps** the intent lock shared while it waits
167    /// for that writer (since step 5): the next writer can't take the intent
168    /// lock and queues behind the waiting readers, which get in together
169    /// when the commit ends. Writers and batches of readers alternate, so a
170    /// writer committing back to back can't starve readers either.
171    ///
172    /// One [`Call`] covers every lock a shared handle's window takes, so a
173    /// read that has to take the exclusive lock to heal the file still
174    /// waits one deadline in all (RB-007.8 item 2).
175    pub(crate) fn acquire(&mut self, kind: LockKind, call: &mut Call) -> Result<Held> {
176        let mut replaced_once = false;
177        'call: loop {
178            call.check()?;
179            let intent = match self.try_intent(kind, call)? {
180                Intent::Held(f) => Some(f),
181                Intent::NotUsed => None,
182                Intent::Busy => {
183                    self.wait(call)?;
184                    continue;
185                }
186            };
187            loop {
188                #[cfg(any(test, feature = "failpoints"))]
189                crate::__failpoints::count_shared_main_try();
190                match self.try_main(kind)? {
191                    Main::Got(file) => {
192                        drop(intent);
193                        return Ok(Held {
194                            file: Some(file),
195                            sidecar: self.sidecar.clone(),
196                            announced: false,
197                        });
198                    }
199                    // A compaction renamed a new file over the path between
200                    // our open and our lock: open the new one, at once the
201                    // first time, then with the backoff, so a path that
202                    // keeps failing the check can't spin a core until the
203                    // deadline. The backoff sleeps without the intent lock
204                    // (RB-007.8 item 3): a reader holds it for one try only,
205                    // and a writer queues for it again.
206                    Main::Replaced => {
207                        call.check()?;
208                        if call.past_deadline() {
209                            return Err(self.locked());
210                        }
211                        if replaced_once {
212                            drop(intent);
213                            self.wait(call)?;
214                            continue 'call;
215                        }
216                        replaced_once = true;
217                        continue;
218                    }
219                    Main::Busy => {}
220                }
221                if intent.is_none() {
222                    break;
223                }
224                // A writer keeps the intent lock while it waits, so new
225                // readers queue behind it. A reader keeps it too, shared,
226                // while a writer holds the main lock (the only time its
227                // shared try fails), so the next writer queues behind it
228                // (step 5; before, readers let it go and starved).
229                self.wait(call)?;
230            }
231            drop(intent);
232            self.wait(call)?;
233        }
234    }
235
236    /// One backoff; past the deadline, `Locked` with what holds the file.
237    fn wait(&self, call: &mut Call) -> Result<()> {
238        if call.back_off()? {
239            Ok(())
240        } else {
241            Err(self.locked())
242        }
243    }
244
245    fn locked(&self) -> MnemoError {
246        MnemoError::Locked {
247            path: self.path.clone(),
248            holder: self.holder(),
249        }
250    }
251
252    fn try_intent(&mut self, kind: LockKind, call: &mut Call) -> Result<Intent> {
253        let Some(side) = &self.sidecar else {
254            return Ok(Intent::NotUsed);
255        };
256        let f = match side.lock_file(INTENT) {
257            Ok(f) => f,
258            // The directory may have been removed (`git clean -fdx`) or
259            // replaced since the handle opened it, and the handle's
260            // descriptor still names the old one. Open it again by path,
261            // with every check, once per call (RB-007.7).
262            Err(_) if !call.sidecar_reopened => {
263                call.sidecar_reopened = true;
264                match sidecar::open(&self.resolved) {
265                    SidecarState::Ready(s) => {
266                        let s = Arc::new(s);
267                        self.sidecar = Some(s.clone());
268                        match s.lock_file(INTENT) {
269                            Ok(f) => f,
270                            Err(e) => {
271                                self.notice(format!(
272                                    "can't use {}: {e}; this call takes the main lock alone, \
273                                     without writer preference",
274                                    s.path().join(INTENT).display()
275                                ));
276                                return Ok(Intent::NotUsed);
277                            }
278                        }
279                    }
280                    SidecarState::Unavailable(why) => {
281                        self.notice(format!(
282                            "not using the sidecar directory: {why}; calls take the main \
283                             lock alone, without writer preference or a lock-info note"
284                        ));
285                        return Ok(Intent::NotUsed);
286                    }
287                }
288            }
289            // A lock file that can't be opened safely (something else is at
290            // the name) costs writer preference for this call, never the
291            // call.
292            Err(_) => return Ok(Intent::NotUsed),
293        };
294        match try_lock(&f, kind) {
295            Ok(()) => Ok(Intent::Held(LockedFile::new(f))),
296            Err(e) if is_lock_conflict(&e) => Ok(Intent::Busy),
297            Err(e) => Err(MnemoError::Io(e)),
298        }
299    }
300
301    /// Add `text` to the notices, once.
302    fn notice(&mut self, text: String) {
303        if !self.notices.contains(&text) {
304            self.notices.push(text);
305        }
306    }
307
308    fn try_main(&self, kind: LockKind) -> Result<Main> {
309        let mut o = OpenOptions::new();
310        o.read(true);
311        if kind == LockKind::Exclusive {
312            o.write(true);
313        }
314        // Never creates: a missing file is an error (`NotFound`).
315        let f = match o.open(&self.path) {
316            Ok(f) => f,
317            // A file this process can only read (RB-007.8 item 5).
318            Err(e) if kind == LockKind::Exclusive && is_permission_denied(&e) => {
319                return Err(MnemoError::Io(std::io::Error::new(
320                    std::io::ErrorKind::PermissionDenied,
321                    format!(
322                        "{} isn't writable by this process ({e}), so a shared-mode write \
323                         can't take its lock; reads still work",
324                        self.path.display()
325                    ),
326                )))
327            }
328            Err(e) => return Err(MnemoError::Io(e)),
329        };
330        match try_lock(&f, kind) {
331            Ok(()) => {
332                let f = LockedFile::new(f);
333                #[cfg(any(test, feature = "failpoints"))]
334                if crate::__failpoints::take_shared_replaced() {
335                    return Ok(Main::Replaced);
336                }
337                if is_file_at(&f, &self.path)? {
338                    Ok(Main::Got(f))
339                } else {
340                    Ok(Main::Replaced)
341                }
342            }
343            Err(e) if is_lock_conflict(&e) => Ok(Main::Busy),
344            Err(e) => Err(MnemoError::Io(e)),
345        }
346    }
347
348    /// The live holder's note, if there is one and its process still runs.
349    fn holder(&self) -> Option<String> {
350        let line = self.sidecar.as_ref()?.read_lock_info()?;
351        let info = LockInfo::parse(&line)?;
352        sidecar::pid_alive(info.pid).then(|| info.describe())
353    }
354}
355
356enum Intent {
357    Held(LockedFile),
358    Busy,
359    NotUsed,
360}
361
362enum Main {
363    Got(LockedFile),
364    Busy,
365    Replaced,
366}
367
368/// Whether opening the brain for writing failed for lack of permission.
369pub(crate) fn is_permission_denied(e: &std::io::Error) -> bool {
370    e.kind() == std::io::ErrorKind::PermissionDenied
371}
372
373fn try_lock(f: &File, kind: LockKind) -> std::io::Result<()> {
374    match kind {
375        LockKind::Shared => FileExt::try_lock_shared(f),
376        LockKind::Exclusive => FileExt::try_lock_exclusive(f),
377    }
378}
379
380/// The main lock for one call. Dropping it removes this call's `lock-info`
381/// note, if it wrote one, and then unlocks.
382pub(crate) struct Held {
383    file: Option<LockedFile>,
384    sidecar: Option<Arc<Sidecar>>,
385    announced: bool,
386}
387
388impl Held {
389    /// The locked file.
390    pub(crate) fn file(&self) -> &File {
391        self.file.as_ref().expect("held until dropped")
392    }
393
394    /// Hand the locked file to the caller (a shared handle's pager), which
395    /// then owns the lock. Drop this `Held` first, so its `lock-info` note
396    /// goes before the caller's unlock.
397    pub(crate) fn take_file(&mut self) -> LockedFile {
398        self.file.take().expect("taken once")
399    }
400
401    /// Say what this exclusive call is doing, for callers that time out
402    /// waiting: written after the lock is held, by temp name and rename,
403    /// and removed before the unlock. A note that can't be written is
404    /// skipped (it's a hint).
405    pub(crate) fn announce(&mut self, op: &str) {
406        if let Some(side) = &self.sidecar {
407            let line = LockInfo::current(op).encode();
408            if side.write_lock_info(&line).is_ok() {
409                self.announced = true;
410            }
411        }
412    }
413}
414
415impl Drop for Held {
416    fn drop(&mut self) {
417        if self.announced {
418            if let Some(side) = &self.sidecar {
419                side.remove_lock_info();
420            }
421        }
422        drop(self.file.take());
423    }
424}
425
426/// The `lock-info` line: operation, pid, start time, tool, tab-separated.
427struct LockInfo {
428    op: String,
429    pid: u32,
430    since: u64,
431    tool: String,
432}
433
434impl LockInfo {
435    fn current(op: &str) -> Self {
436        let tool = std::env::current_exe()
437            .ok()
438            .and_then(|p| p.file_stem().map(|s| s.to_string_lossy().into_owned()))
439            .unwrap_or_else(|| "mnemo".into());
440        LockInfo {
441            op: clean(op),
442            pid: std::process::id(),
443            since: SystemTime::now()
444                .duration_since(UNIX_EPOCH)
445                .map_or(0, |d| d.as_secs()),
446            tool: clean(&tool),
447        }
448    }
449
450    fn encode(&self) -> String {
451        format!("{}\t{}\t{}\t{}", self.op, self.pid, self.since, self.tool)
452    }
453
454    fn parse(line: &str) -> Option<Self> {
455        let mut f = line.split('\t');
456        Some(LockInfo {
457            op: clean(f.next()?),
458            pid: f.next()?.parse().ok()?,
459            since: f.next()?.parse().ok()?,
460            tool: clean(f.next()?),
461        })
462    }
463
464    /// "compact since 12:01:05 UTC (pid 4242, mnemo)".
465    fn describe(&self) -> String {
466        let s = self.since % 86_400;
467        format!(
468            "{} since {:02}:{:02}:{:02} UTC (pid {}, {})",
469            self.op,
470            s / 3600,
471            s % 3600 / 60,
472            s % 60,
473            self.pid,
474            self.tool
475        )
476    }
477}
478
479/// Printable, short, no tabs or line breaks: the note is shown in error
480/// messages, and another process wrote it.
481fn clean(s: &str) -> String {
482    s.chars().filter(|c| !c.is_control()).take(64).collect()
483}