Skip to main content

fslock_guard/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![doc = include_str!("../README.md")]
3// @@ begin lint list maintained by maint/add_warning @@
4#![allow(renamed_and_removed_lints)] // @@REMOVE_WHEN(ci_arti_stable)
5#![allow(unknown_lints)] // @@REMOVE_WHEN(ci_arti_nightly)
6#![warn(missing_docs)]
7#![warn(noop_method_call)]
8#![warn(unreachable_pub)]
9#![warn(clippy::all)]
10#![deny(clippy::await_holding_lock)]
11#![deny(clippy::cargo_common_metadata)]
12#![deny(clippy::cast_lossless)]
13#![deny(clippy::checked_conversions)]
14#![allow(clippy::cognitive_complexity)] // See arti#2556
15#![deny(clippy::debug_assert_with_mut_call)]
16#![deny(clippy::exhaustive_enums)]
17#![deny(clippy::exhaustive_structs)]
18#![deny(clippy::expl_impl_clone_on_copy)]
19#![deny(clippy::fallible_impl_from)]
20#![deny(clippy::implicit_clone)]
21#![deny(clippy::large_stack_arrays)]
22#![warn(clippy::manual_ok_or)]
23#![deny(clippy::missing_docs_in_private_items)]
24#![warn(clippy::needless_borrow)]
25#![warn(clippy::needless_pass_by_value)]
26#![warn(clippy::option_option)]
27#![warn(clippy::or_fun_call)]
28#![deny(clippy::print_stderr)]
29#![deny(clippy::print_stdout)]
30#![warn(clippy::rc_buffer)]
31#![deny(clippy::ref_option_ref)]
32#![warn(clippy::semicolon_if_nothing_returned)]
33#![warn(clippy::trait_duplication_in_bounds)]
34#![deny(clippy::unchecked_time_subtraction)]
35#![deny(clippy::unnecessary_wraps)]
36#![warn(clippy::unseparated_literal_suffix)]
37#![deny(clippy::unwrap_used)]
38#![deny(clippy::mod_module_files)]
39#![allow(clippy::let_unit_value)] // This can reasonably be done for explicitness
40#![allow(clippy::uninlined_format_args)]
41#![allow(clippy::significant_drop_in_scrutinee)] // arti/-/merge_requests/588/#note_2812945
42#![allow(clippy::result_large_err)] // temporary workaround for arti#587
43#![allow(clippy::needless_raw_string_hashes)] // complained-about code is fine, often best
44#![allow(clippy::needless_lifetimes)] // See arti#1765
45#![allow(mismatched_lifetime_syntaxes)] // temporary workaround for arti#2060
46#![allow(clippy::collapsible_if)] // See arti#2342
47#![deny(clippy::unused_async)]
48#![deny(clippy::string_slice)] // See arti#2571
49#![allow(recursion_depth_exceeding_limit)] // arti#2715, rust/issues/159228
50//! <!-- @@ end lint list maintained by maint/add_warning @@ -->
51
52// TODO: add to the list maintained by maint/add_warning once it's available on all crates
53#![warn(unnameable_types)]
54
55use std::{fs, path::Path};
56
57/// A lock-file for which we hold the lock.
58///
59/// So long as this object exists, we hold the lock on this file.
60/// When it is dropped, we will release the lock.
61///
62/// # Semantics
63///
64///  * Only one `LockFileGuard` can exist at one time
65///    for any particular `path`.
66///  * This applies across all tasks and threads in all programs;
67///    other acquisitions of the lock in the same process are prevented.
68///  * This applies across even separate machines, if `path` is on a shared filesystem.
69///
70/// # Restrictions
71///
72///  * **`path` must only be deleted (or renamed) via the APIs in this module**
73///  * This restriction applies to all programs on the computer,
74///    so for example automatic file cleaning with `find` and `rm` is forbidden.
75///  * Cross-filesystem locking is broken on Linux before 2.6.12.
76#[derive(Debug)]
77pub struct LockFileGuard {
78    /// A [`File`](fs::File) with its exclusive lock held.
79    ///
80    /// This `File` instance will remain locked for as long as this
81    /// LockFileGuard exists.
82    locked_file: fs::File,
83}
84
85impl LockFileGuard {
86    /// Try to open `path` with options suitable for using it as a lockfile,
87    /// creating it as necessary.
88    fn open<P>(path: P) -> Result<fs::File, std::io::Error>
89    where
90        P: AsRef<Path>,
91    {
92        fs::OpenOptions::new()
93            .read(true)
94            .write(true)
95            .create(true)
96            .truncate(false)
97            .open(&path)
98    }
99
100    /// Try to construct a new [`LockFileGuard`] representing a lock we hold on
101    /// the file `path`.
102    ///
103    /// Blocks until we can get the lock.
104    pub fn lock<P>(path: P) -> Result<Self, std::io::Error>
105    where
106        P: AsRef<Path>,
107    {
108        let path = path.as_ref();
109        loop {
110            let file = Self::open(path)?;
111            do_lock(&file)?;
112
113            if os::lockfile_has_path(&file, path)? {
114                return Ok(Self { locked_file: file });
115            }
116        }
117    }
118
119    /// Try to construct a new [`LockFileGuard`] representing a lock we hold on
120    /// the file `path`.
121    ///
122    /// Does not block; returns Ok(None) if somebody else holds the lock.
123    pub fn try_lock<P>(path: P) -> Result<Option<Self>, std::io::Error>
124    where
125        P: AsRef<Path>,
126    {
127        let path = path.as_ref();
128        let file = Self::open(path)?;
129        match do_try_lock(&file) {
130            Ok(()) => {
131                if os::lockfile_has_path(&file, path)? {
132                    Ok(Some(Self { locked_file: file }))
133                } else {
134                    Ok(None)
135                }
136            }
137            Err(fs::TryLockError::WouldBlock) => Ok(None),
138            Err(fs::TryLockError::Error(e)) => Err(e),
139        }
140    }
141
142    /// Try to delete the lock file that we hold.
143    ///
144    /// The provided `path` must be the same as was passed to `lock`.
145    pub fn delete_lock_file<P>(self, path: P) -> Result<(), std::io::Error>
146    where
147        P: AsRef<Path>,
148    {
149        let path = path.as_ref();
150        if os::lockfile_has_path(&self.locked_file, path)? {
151            std::fs::remove_file(path)
152        } else {
153            Err(std::io::Error::other(MismatchedPathError {}))
154        }
155    }
156}
157
158impl Drop for LockFileGuard {
159    // We pro-actively unlock the file rather than relying on drop of the File closing it.
160    //
161    // This is necessary on Unix because otherwise the following scenario is possible:
162    //   0. The process has multiple threads
163    //   1. Thread A executes fork (eg as part of spawn), and the child gets a copy of the fd,
164    //   2. Thread B drops the `LockFileGuard` and calls close() on its copy of the fd
165    //   3. Thread B tries to re-acquire the same lock with try_lock and fails
166    //   4. Thread A closes the fd (via exec, or otherwise)
167    // We want to prevent the error in step 3, which arises from a race which is possible
168    // due to us violating the expected semantics of a guard (namely, that the lock is
169    // synchronously released when the guard is dropped).
170    #[allow(clippy::unnecessary_lazy_evaluations)] // we want to write the discarded error type
171    fn drop(&mut self) {
172        self.locked_file
173            .unlock()
174            // Ignore errors from unlock.  There shouldn't be any, but if there are we
175            // don't have anything sensible we could do with them.
176            .unwrap_or_else(|_: std::io::Error| ());
177    }
178}
179
180/// Try to lock `f`, blocking if need be.
181///
182/// On non-android, this just calls [`fs::File::lock`].
183#[cfg(not(target_os = "android"))]
184fn do_lock(f: &fs::File) -> std::io::Result<()> {
185    f.lock()
186}
187
188/// Try to lock `f`, without blocking.
189///
190/// On non-android, this just calls [`fs::File::try_lock`].
191#[cfg(not(target_os = "android"))]
192fn do_try_lock(f: &fs::File) -> Result<(), std::fs::TryLockError> {
193    f.try_lock()
194}
195
196/// Try to lock `f`, blocking if need be.
197///
198/// On android, we need to use flock manually, since Rust (as of May 2026)
199/// always returns "not implemented" for `lock()` and `try_lock()`.
200///
201/// See <https://github.com/rust-lang/rust/issues/148325>.
202/// Apparently,
203/// although there are filesystems (specifically FUSE filesystems)
204/// where flock won't work, it will correctly report ENOSYS
205/// on those filesystems.
206//
207// TODO MSRV ????: we can remove this once Rust supports file locking on Android
208// at our MSRV.  As of May 2026, https://github.com/rust-lang/rust/pull/157038/
209// seems like the likeliest MR for that, but it has not been merged.
210#[cfg(target_os = "android")]
211fn do_lock(f: &fs::File) -> std::io::Result<()> {
212    use std::os::fd::AsRawFd;
213
214    let fd = f.as_raw_fd();
215    // SAFETY: Since `f` is a file, it has a valid fd.
216    let success = unsafe { libc::flock(fd, libc::LOCK_EX) } == 0;
217
218    if success {
219        Ok(())
220    } else {
221        Err(std::io::Error::last_os_error())
222    }
223}
224
225/// Try to lock `f`, without blocking.
226///
227/// On android, we need to use flock manually, since Rust (as of May 2026)
228/// always returns "not implemented" for `lock()` and `try_lock()`.
229///
230/// See <https://github.com/rust-lang/rust/issues/148325>.
231/// Apparently,
232/// although there are filesystems (specifically FUSE filesystems)
233/// where flock won't work, it will correctly report ENOSYS
234/// on those filesystems.
235//
236// TODO MSRV ????: See 'TODO MSRV' on do_lock above.
237#[cfg(target_os = "android")]
238fn do_try_lock(f: &fs::File) -> Result<(), std::fs::TryLockError> {
239    use std::os::fd::AsRawFd;
240
241    let fd = f.as_raw_fd();
242    // SAFETY: Since `f` is a file, it has a valid fd.
243    let success = unsafe { libc::flock(fd, libc::LOCK_EX | libc::LOCK_NB) } == 0;
244
245    if success {
246        Ok(())
247    } else {
248        let err = std::io::Error::last_os_error();
249        if err.kind() == std::io::ErrorKind::WouldBlock {
250            Err(std::fs::TryLockError::WouldBlock)
251        } else {
252            Err(std::fs::TryLockError::Error(err))
253        }
254    }
255}
256
257/// An error that we return when the path given to `delete_lock_file` does not
258/// match the file we have.
259///
260/// Since we wrap this in an `io::Error`, it doesn't need to be public or fancy.
261#[derive(thiserror::Error, Debug, Clone)]
262#[error("Called delete_lock_file with a mismatched path.")]
263struct MismatchedPathError {}
264
265/// Platform module for locking protocol on Unix.
266///
267/// ### Locking protocol on Unix
268///
269/// The lock is held by an open-file iff:
270///
271///  * that open-file holds an `flock` `LOCK_EX` lock; and
272///  * the directory entry for `path` refers to the same file as the open-file
273///
274/// `path` may only refer to a plain file, or `ENOENT`.
275/// If `path` refers to a file,
276/// only the lockholder may cause it to no longer refer to that file.
277///
278/// In principle the open-file might be shared with subprocesses.
279/// Even a naive program can safely and correctly inherit and hold the lock,
280/// since the lockholder only needs to not close an fd.
281/// However uncontrolled leaking of the fd into other processes is undesirable,
282/// as it might cause delays or even deadlocks, if those processes' inheritors live too long.
283/// In our Rust implementation we don't support sharing the held lock
284/// with subprocesses or different process images (ie across exec);
285/// we use `O_CLOEXEC`.
286///
287/// #### Locking algorithm
288///
289///  1. open the file with `O_CREAT|O_RDWR`
290///  2. `flock LOCK_EX`
291///  3. `fstat` the open-file and `lstat` the path
292///  4. If the inode and device numbers don't match,
293///     close the fd and go back to the start.
294///  5. Now we hold the lock.
295///
296/// Proof sketch:
297///
298/// If we get to point 5, we see that at point 3, we had the lock.
299/// No-one else could cause the conditions to become false
300/// in the meantime:
301/// no-one else ~~can~~ may make `path` refer to a different file
302/// since they don't hold the lock.
303/// And, no-one else can `flock` it since the kernel prevents
304/// a conflicting lock.
305/// So at step 5 we must still hold the lock.
306///
307/// #### Unlocking algorithm
308///
309///  1. Close the fd.
310///  2. Now we no longer hold the lock and others can acquire it.
311///
312/// This drops the open-file and
313/// leaves the lock available for another caller.
314///
315/// #### Deletion algorithm
316///
317///  0. The lock must already be held
318///  1. `unlink` the file
319///  2. close the fd
320///  3. Now we no longer hold the lock and others can acquire it.
321///
322/// Step 1 atomically falsifies the lock-holding condition.
323/// We are allowed to perform it because we hold the lock.
324///
325/// Concurrent lockers might open the old file,
326/// which we are about to delete.
327/// They will acquire their `flock` (locking step 2)
328/// after we close (deletion step 2)
329/// and then see that they have a stale file.
330#[cfg(unix)]
331mod os {
332    use std::{fs::File, os::unix::fs::MetadataExt as _, path::Path};
333
334    /// Return true if `lf` currently exists with the given `path`, and false otherwise.
335    pub(crate) fn lockfile_has_path(lf: &File, path: &Path) -> std::io::Result<bool> {
336        let m1 = std::fs::metadata(path)?;
337        let m2 = lf.metadata()?;
338
339        Ok(m1.ino() == m2.ino() && m1.dev() == m2.dev())
340    }
341}
342
343/// Platform module for locking protocol on Windows.
344///
345/// The argument for correctness on Windows proceeds as for Unix, but with a
346/// higher degree of uncertainty, since we are not sufficient Windows experts to
347/// determine if our assumptions hold.
348///
349/// Here we assume as follows:
350/// * When `File::open` calls `CreateFileW`, it gets a `HANDLE` to an open file.
351///   As we use them, the `HANDLE` behaves
352///   similarly to the "fd" in the Unix argument above,
353///   and the open file behaves similarly to the "open-file".
354///   * We assume that any differences that exist in their behavior do not
355///     affect our correctness above.
356/// * When `File::lock` calls `LockFileEx`, and it completes successfully,
357///   we now have a lock on the file.
358///   Only one lock can exist on a file at a time.
359/// * When we compare members of `handle.metadata()` and `path.metadata()`,
360///   the comparison will return equal if ~~and only if~~
361///   the two files are truly the same.
362///   * We rely on the property that a file cannot change its file_index while it is
363///     open.
364/// * Deleting the lock file will actually work, since `File::open` opened it with
365///   FILE_SHARE_DELETE.  (This is the default according to the documentation
366///   for `OpenOptionsExt::share_mode`.)
367/// * When we delete the lock file, possibly-asynchronous ("deferred") deletion
368///   definitely won't mean that the OS kernel violates our rule that no-one but the lockholder
369///   is allowed to delete the file.
370/// * The above is true even if someone with read
371///   access to the file - eg the human user - opens it without the FILE_SHARE options.
372/// * The same is true even if there is a virus scanner.
373/// * The same is true even on a remote filesystem.
374/// * If someone with read access to the file - eg the human user - opens it for reading
375///   without FILE_SHARE options, the algorithm will still work and not fail
376///   with a file sharing violation io error.
377///   (Or, every program the user might use to randomly peer at files in arti's
378///   state directory, including the equivalents of `grep -R` and backup programs,
379///   will use suitable FILE_SHARE options.)
380///   (If this assumption is false, the consequence is not data loss;
381///   rather, arti would fall over.  So that would be tolerable if we don't
382///   know how to do better, or if doing better is hard.)
383#[cfg(windows)]
384mod os {
385    use std::{fs::File, mem::MaybeUninit, os::windows::io::AsRawHandle, path::Path};
386    use windows_sys::Win32::{
387        Foundation::HANDLE,
388        Storage::FileSystem::{FILE_ID_INFO, FileIdInfo, GetFileInformationByHandleEx},
389    };
390
391    /// Use `GetFileInformationByHandleEx` to return a FILE_ID_INFO data for `f`.
392    ///
393    /// `GetFileInformationByHandleEx` is supported in Vista and later, so it
394    /// should be fine here.  Unlike GetFileInformationByHandle, it gives
395    /// 128-bit identifiers which are supposedly even more unique.
396    fn get_id_info(f: &File) -> std::io::Result<FILE_ID_INFO> {
397        let handle = f.as_raw_handle() as HANDLE;
398        let mut info: MaybeUninit<FILE_ID_INFO> = MaybeUninit::uninit();
399        let buffersize: u32 = std::mem::size_of::<FILE_ID_INFO>()
400            .try_into()
401            .expect("sizeof(FILE_ID_INFO) is ridiculously large");
402
403        let info = unsafe {
404            // SAFETY: Since `size` is the size of info, this will not write to
405            // uninitialized memory.
406            let rv = GetFileInformationByHandleEx(
407                handle,
408                FileIdInfo,
409                info.as_mut_ptr() as _,
410                buffersize,
411            );
412
413            if rv == 0 {
414                return Err(std::io::Error::last_os_error());
415            }
416
417            // SAFETY: since rv was nonzero, this value is initialized.
418            info.assume_init()
419        };
420        Ok(info)
421    }
422
423    /// Return true if `lf` currently exists with the given `path`, and false otherwise.
424    pub(crate) fn lockfile_has_path(lf: &File, path: &Path) -> std::io::Result<bool> {
425        let f2 = File::open(path)?;
426
427        // Note: we would like to just use the MetadataExt methods for index and
428        // volume serial number, but they are currently available only on
429        // nightly: https://github.com/rust-lang/rust/issues/63010
430        //
431        // If they stabilize at our MSRV, _and_ the file ID is expanded to the
432        // 128-bit version, we can use them here instead.
433
434        let i1 = get_id_info(lf)?;
435        let i2 = get_id_info(&f2)?;
436
437        // This comparison is about the best we can do on Windows,
438        // though there are caveats.
439        //
440        // See Raymond Chen's writeup at
441        //   https://devblogs.microsoft.com/oldnewthing/20220128-00/?p=106201
442        // and also see BurntSushi's caveats at
443        //   https://github.com/BurntSushi/same-file/blob/master/src/win.rs
444        Ok(i1.VolumeSerialNumber == i2.VolumeSerialNumber
445            && i1.FileId.Identifier == i2.FileId.Identifier)
446    }
447}
448
449/// Non-windows, non-unix implementation for lockfile_has_path.
450///
451/// For now, this implementation always reports an error.
452/// It exists so that we can build (but not run) on wasm.
453#[cfg(all(not(windows), not(unix)))]
454mod os {
455    use std::path::Path;
456
457    /// Return true if `lf` currently exists with the given `path`, and false otherwise.
458    pub(crate) fn lockfile_has_path(_lf: &std::fs::File, _path: &Path) -> std::io::Result<bool> {
459        Err(std::io::Error::other(
460            "fslock-guard does not support this operating system".to_string(),
461        ))
462    }
463}
464
465#[cfg(test)]
466mod tests {
467    // @@ begin test lint list maintained by maint/add_warning @@
468    #![allow(clippy::bool_assert_comparison)]
469    #![allow(clippy::clone_on_copy)]
470    #![allow(clippy::dbg_macro)]
471    #![allow(clippy::mixed_attributes_style)]
472    #![allow(clippy::print_stderr)]
473    #![allow(clippy::print_stdout)]
474    #![allow(clippy::single_char_pattern)]
475    #![allow(clippy::unwrap_used)]
476    #![allow(clippy::unchecked_time_subtraction)]
477    #![allow(clippy::useless_vec)]
478    #![allow(clippy::needless_pass_by_value)]
479    #![allow(clippy::string_slice)] // See arti#2571
480    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
481
482    use crate::LockFileGuard;
483    use std::sync::Arc;
484    use std::thread;
485    use test_temp_dir::test_temp_dir;
486
487    #[test]
488    fn keep_lock_file_after_drop() {
489        test_temp_dir!().used_by(|dir| {
490            let file = dir.join("file");
491            let flock_guard = LockFileGuard::lock(&file).unwrap();
492            assert!(file.try_exists().unwrap());
493            drop(flock_guard);
494            assert!(file.try_exists().unwrap());
495        });
496    }
497
498    #[test]
499    fn delete_lock_file_if_requested() {
500        test_temp_dir!().used_by(|dir| {
501            let file = dir.join("file");
502            let flock_guard = LockFileGuard::lock(&file).unwrap();
503            assert!(file.try_exists().unwrap());
504            assert!(flock_guard.delete_lock_file(&file).is_ok());
505            assert!(!file.try_exists().unwrap());
506        });
507    }
508
509    #[test]
510    fn tight_loop() {
511        let tmp = Arc::new(test_temp_dir!());
512
513        // We make several threads in case there are any cross-thread interactions
514        // that we're not aware of.  There shouldn't be.
515        let threads = (0..10)
516            .map(|i| {
517                let tmp = tmp.clone();
518                thread::spawn(move || {
519                    tmp.used_by(|dir| {
520                        let file = dir.join(format!("{i}"));
521                        for _ in 0..1000 {
522                            // Test that the lock is immediately re-requirable after drop.
523                            let lock: LockFileGuard =
524                                LockFileGuard::try_lock(&file).unwrap().unwrap();
525                            drop(lock);
526                        }
527                    });
528                })
529            })
530            .collect::<Vec<_>>();
531
532        for t in threads {
533            t.join().unwrap_or_else(|e| std::panic::resume_unwind(e));
534        }
535    }
536
537    #[test]
538    #[cfg(unix)]
539    fn fork_leak_fds() {
540        use std::ffi::c_int;
541
542        let tmp = test_temp_dir!();
543
544        tmp.used_by(|tmp| {
545            let file = tmp.join("lock");
546            let lock = LockFileGuard::lock(&file).unwrap();
547
548            let child = unsafe {
549                // It would be nicer to do this with std's Command, but
550                // we'd have to use the unsafe pre-exec hook for synchronisation
551                // and anyway that runs after Command's impl has closed "unwanted" fds.
552                match libc::fork() {
553                    -1 => panic!("fork failed"),
554                    0 => {
555                        libc::usleep(10_000);
556                        libc::_exit(0);
557                    }
558                    child => child,
559                }
560            };
561
562            drop(lock);
563            let _lock: LockFileGuard = LockFileGuard::try_lock(&file).unwrap().unwrap();
564
565            unsafe {
566                let mut status: c_int = 0;
567                let got = libc::waitpid(child, (&mut status) as *mut _, 0);
568                assert_eq!(got, child);
569                assert_eq!(status, 0, "{status}");
570            }
571        });
572    }
573}