Line data Source code
1 : //! A module to create and read lock files.
2 : //!
3 : //! File locking is done using [`fcntl::flock`] exclusive locks.
4 : //! The only consumer of this module is currently
5 : //! [`pid_file`](crate::pid_file). See the module-level comment
6 : //! there for potential pitfalls with lock files that are used
7 : //! to store PIDs (pidfiles).
8 :
9 : use std::fs;
10 : use std::io::{Read, Write};
11 : use std::ops::Deref;
12 : use std::os::unix::prelude::AsRawFd;
13 :
14 : use anyhow::Context;
15 : use camino::{Utf8Path, Utf8PathBuf};
16 : use nix::errno::Errno::EAGAIN;
17 : use nix::fcntl;
18 :
19 : use crate::crashsafe;
20 :
21 : /// A handle to an open and unlocked, but not-yet-written lock file.
22 : /// Returned by [`create_exclusive`].
23 : #[must_use]
24 : pub struct UnwrittenLockFile {
25 : path: Utf8PathBuf,
26 : file: fs::File,
27 : }
28 :
29 : /// Returned by [`UnwrittenLockFile::write_content`].
30 : #[must_use]
31 : pub struct LockFileGuard(fs::File);
32 :
33 : impl Deref for LockFileGuard {
34 : type Target = fs::File;
35 :
36 0 : fn deref(&self) -> &Self::Target {
37 0 : &self.0
38 0 : }
39 : }
40 :
41 : impl UnwrittenLockFile {
42 : /// Replace the content of this lock file with the byte representation of `contents`.
43 0 : pub fn write_content(mut self, contents: String) -> anyhow::Result<LockFileGuard> {
44 0 : self.file
45 0 : .set_len(0)
46 0 : .context("Failed to truncate lockfile")?;
47 0 : self.file
48 0 : .write_all(contents.as_bytes())
49 0 : .with_context(|| format!("Failed to write '{contents}' contents into lockfile"))?;
50 0 : crashsafe::fsync_file_and_parent(&self.path).context("fsync lockfile")?;
51 0 : Ok(LockFileGuard(self.file))
52 0 : }
53 : }
54 :
55 : /// Creates and opens a lock file in the path, grabs an exclusive flock on it, and returns
56 : /// a handle that allows overwriting the locked file's content.
57 : ///
58 : /// The exclusive lock is released when dropping the returned handle.
59 : ///
60 : /// It is not an error if the file already exists.
61 : /// It is an error if the file is already locked.
62 0 : pub fn create_exclusive(lock_file_path: &Utf8Path) -> anyhow::Result<UnwrittenLockFile> {
63 0 : let lock_file = fs::OpenOptions::new()
64 0 : .create(true) // O_CREAT
65 0 : .truncate(true)
66 0 : .write(true)
67 0 : .open(lock_file_path)
68 0 : .context("open lock file")?;
69 :
70 0 : let res = fcntl::flock(
71 0 : lock_file.as_raw_fd(),
72 0 : fcntl::FlockArg::LockExclusiveNonblock,
73 0 : );
74 0 : match res {
75 0 : Ok(()) => Ok(UnwrittenLockFile {
76 0 : path: lock_file_path.to_owned(),
77 0 : file: lock_file,
78 0 : }),
79 0 : Err(EAGAIN) => anyhow::bail!("file is already locked"),
80 0 : Err(e) => Err(e).context("flock error"),
81 : }
82 0 : }
83 :
84 : /// Returned by [`read_and_hold_lock_file`].
85 : /// Check out the [`pid_file`](crate::pid_file) module for what the variants mean
86 : /// and potential caveats if the lock files that are used to store PIDs.
87 : pub enum LockFileRead {
88 : /// No file exists at the given path.
89 : NotExist,
90 : /// No other process held the lock file, so we grabbed an flock
91 : /// on it and read its contents.
92 : /// Release the flock by dropping the [`LockFileGuard`].
93 : NotHeldByAnyProcess(LockFileGuard, String),
94 : /// The file exists but another process was holding an flock on it.
95 : LockedByOtherProcess {
96 : not_locked_file: fs::File,
97 : content: String,
98 : },
99 : }
100 :
101 : /// Open & try to lock the lock file at the given `path`, returning a [handle][`LockFileRead`] to
102 : /// inspect its content.
103 : ///
104 : /// It is not an `Err(...)` if the file does not exist or is already locked.
105 : /// Check the [`LockFileRead`] variants for details.
106 0 : pub fn read_and_hold_lock_file(path: &Utf8Path) -> anyhow::Result<LockFileRead> {
107 0 : let res = fs::OpenOptions::new().read(true).open(path);
108 0 : let mut lock_file = match res {
109 0 : Ok(f) => f,
110 0 : Err(e) => match e.kind() {
111 0 : std::io::ErrorKind::NotFound => return Ok(LockFileRead::NotExist),
112 0 : _ => return Err(e).context("open lock file"),
113 : },
114 : };
115 0 : let res = fcntl::flock(
116 0 : lock_file.as_raw_fd(),
117 0 : fcntl::FlockArg::LockExclusiveNonblock,
118 0 : );
119 0 : // We need the content regardless of lock success / failure.
120 0 : // But, read it after flock so that, if it succeeded, the content is consistent.
121 0 : let mut content = String::new();
122 0 : lock_file
123 0 : .read_to_string(&mut content)
124 0 : .context("read lock file")?;
125 0 : match res {
126 0 : Ok(()) => Ok(LockFileRead::NotHeldByAnyProcess(
127 0 : LockFileGuard(lock_file),
128 0 : content,
129 0 : )),
130 0 : Err(EAGAIN) => Ok(LockFileRead::LockedByOtherProcess {
131 0 : not_locked_file: lock_file,
132 0 : content,
133 0 : }),
134 0 : Err(e) => Err(e).context("flock error"),
135 : }
136 0 : }
|
