feat: A Graph for quick access to commits and for associating state with them.

This data structure should be used whenever stateful traversal is required, usually
by associating information with each commit to remember what was seen and what wasn't.

Author: Byron

Cargo.lock

@@ -22,6 +22,7 @@ gix-hash = { version = "^0.11.1", path = "../gix-hash" }
 gix-object = { version = "^0.29.2", path = "../gix-object" }
 gix-date = { version = "^0.5.0", path = "../gix-date" }
 gix-hashtable = { version = "^0.2.0", path = "../gix-hashtable" }
+gix-commitgraph = { version = "0.14.0", path = "../gix-commitgraph" }
 
 bstr = { version = "1.3.0", default-features = false, features = ["std"]}
 thiserror = "1.0.26"

gix-revision/Cargo.toml

@@ -0,0 +1,136 @@
+use crate::Graph;
+use gix_hash::oid;
+use std::ops::Index;
+
+impl<'find, T> Graph<'find, T> {
+    /// Create a new instance with `find` to retrieve commits and optionally `cache` to accelerate commit access.
+    pub fn new<Find, E>(mut find: Find, cache: impl Into<Option<gix_commitgraph::Graph>>) -> Self
+    where
+        Find:
+            for<'a> FnMut(&gix_hash::oid, &'a mut Vec<u8>) -> Result<Option<gix_object::CommitRefIter<'a>>, E> + 'find,
+        E: std::error::Error + Send + Sync + 'static,
+    {
+        Graph {
+            find: Box::new(move |id, buf| {
+                find(id, buf).map_err(|err| Box::new(err) as Box<dyn std::error::Error + Send + Sync + 'static>)
+            }),
+            cache: cache.into(),
+            set: gix_hashtable::HashMap::default(),
+            buf: Vec::new(),
+            parent_buf: Vec::new(),
+        }
+    }
+
+    /// Returns true if `id` has data associated with it, meaning that we processed it already.
+    pub fn contains(&self, id: &gix_hash::oid) -> bool {
+        self.set.contains_key(id.as_ref())
+    }
+
+    /// Returns the data associated with `id` if available.
+    pub fn get(&self, id: &gix_hash::oid) -> Option<&T> {
+        self.set.get(id)
+    }
+
+    /// Returns the data associated with `id` if available as mutable reference.
+    pub fn get_mut(&mut self, id: &gix_hash::oid) -> Option<&mut T> {
+        self.set.get_mut(id)
+    }
+
+    /// Insert `id` into the graph and associate it with `value`, returning the previous value associated with it if it existed.
+    pub fn insert(&mut self, id: gix_hash::ObjectId, value: T) -> Option<T> {
+        self.set.insert(id, value)
+    }
+
+    /// Remove all data from the graph to start over.
+    pub fn clear(&mut self) {
+        self.set.clear();
+    }
+
+    #[allow(missing_docs)]
+    pub fn try_lookup_mut(&mut self, id: &gix_hash::oid) -> Result<Option<CommitMut<'_, 'find, T>>, lookup::Error> {
+        match (self.find)(id, &mut self.buf)? {
+            Some(_) => Ok(Some(CommitMut { graph: self })),
+            None => Ok(None),
+        }
+    }
+}
+
+impl<'a, 'find, T> Index<&'a gix_hash::oid> for Graph<'find, T> {
+    type Output = T;
+
+    fn index(&self, index: &'a oid) -> &Self::Output {
+        &self.set[index]
+    }
+}
+
+///
+pub mod lookup {
+    /// The error returned by [`try_lookup()`][super::Graph::try_lookup()].
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error("Could not find commit")]
+        Find(#[from] Box<dyn std::error::Error + Send + Sync + 'static>),
+    }
+}
+
+///
+pub mod insert_parents {
+    /// The error returned by [`CommitMut::insert_parents()`][super::CommitMut::insert_parents()].
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error("Could not find commit")]
+        Find(#[from] Box<dyn std::error::Error + Send + Sync + 'static>),
+        #[error("A commit could not be decoded during traversal")]
+        Decode(#[from] gix_object::decode::Error),
+    }
+}
+
+/// A commit that provides access to graph-related information.
+pub struct CommitMut<'graph, 'find, T> {
+    graph: &'graph mut Graph<'find, T>,
+}
+
+mod commit {
+    use super::insert_parents;
+    use super::CommitMut;
+    use gix_hashtable::hash_map;
+
+    impl<'graph, 'find, T> CommitMut<'graph, 'find, T> {
+        #[allow(missing_docs)]
+        pub fn insert_parents(&mut self) -> Result<(), insert_parents::Error> {
+            let mut commit_iter = gix_object::CommitRefIter::from_bytes(&self.graph.buf);
+            for token in commit_iter {
+                match token {
+                    Ok(gix_object::commit::ref_iter::Token::Tree { .. }) => continue,
+                    Ok(gix_object::commit::ref_iter::Token::Parent { id: parent_id }) => {
+                        match self.graph.set.entry(parent_id) {
+                            hash_map::Entry::Vacant(entry) => {
+                                let parent = match (self.graph.find)(&parent_id, &mut self.graph.parent_buf)? {
+                                    Some(p) => p,
+                                    None => continue, // skip missing objects, they don't exist.
+                                };
+
+                                let parent_commit_date = parent
+                                    .committer()
+                                    .map(|committer| committer.time.seconds_since_unix_epoch)
+                                    .unwrap_or_default();
+
+                                // TODO: call user function
+                                // entry.insert(commit_flags);
+                            }
+                            hash_map::Entry::Occupied(mut entry) => {
+                                todo!()
+                            }
+                        }
+                    }
+                    Ok(_unused_token) => break,
+                    Err(err) => return Err(err.into()),
+                }
+                // TODO: check if we should abort
+            }
+            Ok(())
+        }
+    }
+}

gix-revision/src/graph.rs

@@ -19,6 +19,33 @@ pub mod spec;
 mod types;
 pub use types::Spec;
 
+/// A graph of commits which additionally allows to associate data with commits.
+///
+/// It starts empty, but each access may fill it with commit information.
+/// Note that the traversal can be accelerated if a [commit-graph][gix_commitgraph::Graph] is also made available.
+pub struct Graph<'find, T> {
+    /// A way to resolve a commit from the object database.
+    find: Box<
+        dyn for<'a> FnMut(
+                &gix_hash::oid,
+                &'a mut Vec<u8>,
+            ) -> Result<
+                Option<gix_object::CommitRefIter<'a>>,
+                Box<dyn std::error::Error + Send + Sync + 'static>,
+            > + 'find,
+    >,
+    /// A way to speedup commit access, essentially a multi-file commit database.
+    cache: Option<gix_commitgraph::Graph>,
+    /// The set of cached commits that we have seen once, along with data associated with them.
+    set: gix_hashtable::HashMap<gix_hash::ObjectId, T>,
+    /// A buffer for writing commit data into.
+    buf: Vec<u8>,
+    /// Another buffer we typically use to store parents.
+    parent_buf: Vec<u8>,
+}
+///
+pub mod graph;
+
 /// A utility type implementing a queue which can be used to automatically sort data by its time in ascending order.
 #[derive(Default)]
 pub struct PriorityQueue<K: Ord, T>(VecDeque<(K, T)>);

gix-revision/src/lib.rs

@@ -241,7 +241,7 @@ fn shallow_yields_result_if_refs_are_available() {
     assert_eq!(res.into_format(7).to_string(), "at-c5-1-g01ec18a");
 }
 
-fn repo() -> Repository {
+pub(crate) fn repo() -> Repository {
     let dir = gix_testtools::scripted_fixture_read_only_standalone("make_repo_with_branches.sh").unwrap();
     gix::open(dir).unwrap()
 }

gix-revision/tests/describe/mod.rs

@@ -1,5 +1,27 @@
 mod describe;
 mod spec;
+mod graph {
+    use crate::hex_to_id;
+    use gix::odb::Find;
+    use gix_revision::Graph;
+
+    #[test]
+    fn parent_insertion_theory() -> crate::Result {
+        let repo = crate::describe::repo();
+        let head_id = repo.head_id()?;
+        let mut g = Graph::<'_, ()>::new(
+            |id, buf| {
+                repo.objects
+                    .try_find(id, buf)
+                    .map(|d| d.and_then(|d| d.try_into_commit_iter()))
+            },
+            None,
+        );
+        let mut c = g.try_lookup_mut(&head_id)?.expect("available");
+        c.insert_parents();
+        Ok(())
+    }
+}
 
 pub type Result<T = ()> = std::result::Result<T, Box<dyn std::error::Error + 'static>>;