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}