Merge branch 'gix-lock-improvements'

Author: Byron

Diff for: gix-lock/src/acquire.rs

@@ -30,6 +30,16 @@ impl fmt::Display for Fail {
     }
 }
 
+impl From<Duration> for Fail {
+    fn from(value: Duration) -> Self {
+        if value.is_zero() {
+            Fail::Immediately
+        } else {
+            Fail::AfterDurationWithBackoff(value)
+        }
+    }
+}
+
 /// The error returned when acquiring a [`File`] or [`Marker`].
 #[derive(Debug, thiserror::Error)]
 #[allow(missing_docs)]
@@ -49,6 +59,12 @@ impl File {
     ///
     /// If `boundary_directory` is given, non-existing directories will be created automatically and removed in the case of
     /// a rollback. Otherwise the containing directory is expected to exist, even though the resource doesn't have to.
+    ///
+    /// ### Warning of potential resource leak
+    ///
+    /// Please note that the underlying file will remain if destructors don't run, as is the case when interrupting the application.
+    /// This results in the resource being locked permanently unless the lock file is removed by other means.
+    /// See [the crate documentation](crate) for more information.
     pub fn acquire_to_update_resource(
         at_path: impl AsRef<Path>,
         mode: Fail,
@@ -70,6 +86,12 @@ impl Marker {
     ///
     /// If `boundary_directory` is given, non-existing directories will be created automatically and removed in the case of
     /// a rollback.
+    ///
+    /// ### Warning of potential resource leak
+    ///
+    /// Please note that the underlying file will remain if destructors don't run, as is the case when interrupting the application.
+    /// This results in the resource being locked permanently unless the lock file is removed by other means.
+    /// See [the crate documentation](crate) for more information.
     pub fn acquire_to_hold_resource(
         at_path: impl AsRef<Path>,
         mode: Fail,

Diff for: gix-lock/src/lib.rs

@@ -1,24 +1,25 @@
 //! git-style registered lock files to make altering resources atomic.
 //!
-//! In this model, reads are always atomic and can be performed directly while writes are facilitated by a locking mechanism
-//! implemented here.
+//! In this model, reads are always atomic and can be performed directly while writes are facilitated by the locking mechanism
+//! implemented here. Locks are acquired atomically, then written to, to finally atomically overwrite the actual resource.
 //!
-//! Lock files mostly `gix-tempfile` with its auto-cleanup and the following:
+//! Lock files are wrapped [`gix-tempfile`](gix_tempfile)-handles and add the following:
 //!
 //! * consistent naming of lock files
 //! * block the thread (with timeout) or fail immediately if a lock cannot be obtained right away
 //! * commit lock files to atomically put them into the location of the originally locked file
 //!
 //! # Limitations
 //!
+//! * [All limitations of `gix-tempfile`](gix_tempfile) apply. **A highlight of such a limitation is resource leakage
+//!   which results in them being permanently locked unless there is user-intervention.**
 //! * As the lock file is separate from the actual resource, locking is merely a convention rather than being enforced.
-//! * The limitations of `gix-tempfile` apply.
 #![deny(missing_docs, rust_2018_idioms, unsafe_code)]
 
+use gix_tempfile::handle::{Closed, Writable};
 use std::path::PathBuf;
 
 pub use gix_tempfile as tempfile;
-use gix_tempfile::handle::{Closed, Writable};
 
 const DOT_LOCK_SUFFIX: &str = ".lock";
 

Diff for: gix-tempfile/src/handle.rs

@@ -69,6 +69,11 @@ impl Handle<Closed> {
     ///
     /// Depending on the `directory` configuration, intermediate directories will be created, and depending on `cleanup` empty
     /// intermediate directories will be removed.
+    ///
+    /// ### Warning of potential leaks
+    ///
+    /// Without [signal handlers](crate::signal) installed, tempfiles will remain once a termination
+    /// signal is encountered as destructors won't run. See [the top-level documentation](crate) for more.
     pub fn at(path: impl AsRef<Path>, directory: ContainingDirectory, cleanup: AutoRemove) -> io::Result<Self> {
         Ok(Handle {
             id: Handle::<()>::at_path(path.as_ref(), directory, cleanup, Mode::Closed)?,
@@ -92,6 +97,11 @@ impl Handle<Writable> {
     ///
     /// Depending on the `directory` configuration, intermediate directories will be created, and depending on `cleanup` empty
     /// intermediate directories will be removed.
+    ///
+    /// ### Warning of potential leaks
+    ///
+    /// Without [signal handlers](crate::signal) installed, tempfiles will remain once a termination
+    /// signal is encountered as destructors won't run. See [the top-level documentation](crate) for more.
     pub fn at(path: impl AsRef<Path>, directory: ContainingDirectory, cleanup: AutoRemove) -> io::Result<Self> {
         Ok(Handle {
             id: Handle::<()>::at_path(path.as_ref(), directory, cleanup, Mode::Writable)?,
@@ -102,6 +112,11 @@ impl Handle<Writable> {
     /// Create a registered tempfile within `containing_directory` with a name that won't clash, and clean it up as specified with `cleanup`.
     /// Control how to deal with intermediate directories with `directory`.
     /// The temporary file is opened and can be written to using the [`with_mut()`][Handle::with_mut()] method.
+    ///
+    /// ### Warning of potential leaks
+    ///
+    /// Without [signal handlers](crate::signal) installed, tempfiles will remain once a termination
+    /// signal is encountered as destructors won't run. See [the top-level documentation](crate) for more.
     pub fn new(
         containing_directory: impl AsRef<Path>,
         directory: ContainingDirectory,

Diff for: gix-tempfile/src/lib.rs

@@ -9,8 +9,9 @@
 //!
 //! ### Initial Setup
 //!
-//! As no handlers for `TERMination` are installed, it is required to call [`signal::setup()`] before creating the first tempfile.
-//! This also allows to control how `git-tempfiles` integrates with other handlers under application control.
+//! As no handlers for `TERMination` are installed, it is required to call [`signal::setup()`] before creating
+//! the first tempfile. This also allows to control how this crate integrates with
+//! other handlers under application control.
 //!
 //! As a general rule of thumb, use `Default::default()` as argument to emulate the default behaviour and
 //! abort the process after cleaning temporary files. Read more about options in [`signal::handler::Mode`].
@@ -23,7 +24,7 @@
 //! * The application is performing a write operation on the tempfile when a signal arrives, preventing this tempfile to be removed,
 //!   but not others. Any other operation dealing with the tempfile suffers from the same issue.
 //!
-//! [signal-hook]: https://docs.rs/signal-hook
+//! [`signal-hook`]: https://docs.rs/signal-hook
 //!
 //! ## Feature Flags
 #![cfg_attr(