feat: add FileSnapshot::into_owned_or_cloned().

That way it's possible to efficiently take ownership if there happens to
be only one instance of a snapshot.

Author: Byron

gix-fs/src/snapshot.rs

@@ -1,7 +1,6 @@
 // TODO: tests
-use std::ops::Deref;
-
 use gix_features::threading::{get_mut, get_ref, MutableOnDemand, OwnShared};
+use std::ops::Deref;
 
 /// A structure holding enough information to reload a value if its on-disk representation changes as determined by its modified time.
 #[derive(Debug)]
@@ -39,6 +38,16 @@ impl<T: Clone + std::fmt::Debug> Clone for FileSnapshot<T> {
     }
 }
 
+impl<T: Clone + std::fmt::Debug> FileSnapshot<T> {
+    /// Return the contained instance if nobody else is holding it, or clone it otherwise.
+    pub fn into_owned_or_cloned(self: OwnShared<Self>) -> T {
+        match OwnShared::try_unwrap(self) {
+            Ok(this) => this.value,
+            Err(this) => this.value.clone(),
+        }
+    }
+}
+
 /// A snapshot of a resource which is up-to-date in the moment it is retrieved.
 pub type SharedFileSnapshot<T> = OwnShared<FileSnapshot<T>>;
 

gix-fs/tests/capabilities/mod.rs renamed to gix-fs/tests/fs/capabilities.rs

@@ -3,4 +3,5 @@ type Result<T = ()> = std::result::Result<T, Box<dyn std::error::Error + Send +
 mod capabilities;
 mod dir;
 mod read_dir;
+mod snapshot;
 mod stack;

gix-fs/tests/dir/create.rs renamed to gix-fs/tests/fs/dir/create.rs

@@ -0,0 +1,54 @@
+use gix_fs::SharedFileSnapshotMut;
+use std::path::Path;
+
+#[test]
+fn journey() -> Result<(), Box<dyn std::error::Error>> {
+    let tmp = tempfile::tempdir().unwrap();
+    if !has_nanosecond_times(tmp.path())? {
+        return Ok(());
+    }
+
+    let file_path = tmp.path().join("content");
+    let smut = SharedFileSnapshotMut::<String>::new();
+
+    let check = || file_path.metadata().ok()?.modified().ok();
+    let open = || {
+        Ok(match std::fs::read_to_string(&file_path) {
+            Ok(s) => Some(s),
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => None,
+            Err(err) => return Err(err),
+        })
+    };
+    let snap = smut.recent_snapshot(check, open)?;
+    assert!(snap.is_none());
+
+    std::fs::write(&file_path, "content")?;
+    let snap = smut.recent_snapshot(check, open)?.expect("content read");
+    assert_eq!(&**snap, "content", "it read the file for the first time");
+
+    std::fs::write(&file_path, "change")?;
+    let snap = smut.recent_snapshot(check, open)?.expect("content read");
+    assert_eq!(&**snap, "change", "it picks up the change");
+
+    std::fs::remove_file(&file_path)?;
+    let snap = smut.recent_snapshot(check, open)?;
+    assert!(snap.is_none(), "file deleted, nothing to see here");
+
+    std::fs::write(&file_path, "new")?;
+    let snap = smut.recent_snapshot(check, open)?.expect("content read again");
+    let owned: String = snap.into_owned_or_cloned();
+    assert_eq!(owned, "new", "owned versions are possible easily and efficiently");
+    Ok(())
+}
+
+fn has_nanosecond_times(root: &Path) -> std::io::Result<bool> {
+    let test_file = root.join("nanosecond-test");
+
+    std::fs::write(&test_file, "a")?;
+    let first_time = test_file.metadata()?.modified()?;
+
+    std::fs::write(&test_file, "b")?;
+    let second_time = test_file.metadata()?.modified()?;
+
+    Ok(first_time != second_time)
+}