git_lock/
lib.rs

1//! git-style registered lock files to make altering resources atomic.
2//!
3//! In this model, reads are always atomic and can be performed directly while writes are facilitated by a locking mechanism
4//! implemented here.
5//!
6//! Lock files mostly `git-tempfile` with its auto-cleanup and the following:
7//!
8//! * consistent naming of lock files
9//! * block the thread (with timeout) or fail immediately if a lock cannot be obtained right away
10//! * commit lock files to atomically put them into the location of the originally locked file
11//!
12//! # Limitations
13//!
14//! * As the lock file is separate from the actual resource, locking is merely a convention rather than being enforced.
15//! * The limitations of `git-tempfile` apply.
16#![deny(missing_docs, rust_2018_idioms, unsafe_code)]
17
18use std::path::PathBuf;
19
20pub use git_tempfile as tempfile;
21use git_tempfile::handle::{Closed, Writable};
22
23const DOT_LOCK_SUFFIX: &str = ".lock";
24
25///
26pub mod acquire;
27///
28pub mod backoff;
29///
30pub mod commit;
31
32/// Locks a resource to eventually be overwritten with the content of this file.
33///
34/// Dropping the file without [committing][File::commit] will delete it, leaving the underlying resource unchanged.
35#[must_use = "A File that is immediately dropped doesn't allow resource updates"]
36#[derive(Debug)]
37pub struct File {
38    inner: git_tempfile::Handle<Writable>,
39    lock_path: PathBuf,
40}
41
42/// Locks a resource to allow related resources to be updated using [files][File].
43///
44/// As opposed to the [File] type this one won't keep the tempfile open for writing and thus consumes no
45/// system resources, nor can it be persisted.
46#[must_use = "A Marker that is immediately dropped doesn't lock a resource meaningfully"]
47#[derive(Debug)]
48pub struct Marker {
49    inner: git_tempfile::Handle<Closed>,
50    created_from_file: bool,
51    lock_path: PathBuf,
52}
53
54///
55pub mod file;