Struct gix_revision::Graph

pub struct Graph<'find, T> { /* private fields */ }

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.

About replacements

Object replacements is an object database feature to substitute one object with another. We assume that this is transparently implemented by the find function that returns objects. Also we assume that the commitgraph as been written with replacements active to provide a consistent view.

Odb or find configuration

The find handle should be setup to quickly determine if an object exists or not to assure quick operation on shallow repositories. This typically means that it should not re-read the odb if there is an object miss.

Most usage of the Graph will benefit from fast ODB lookups, so setting up an object cache will be beneficial. If that’s not the case, the method docs will inform about that.

Additionally, and only if T is Commit<T>, there is no need for an object cache as we keep track of everything related to commit traversal in our own hashmap.

Implementations

impl<'find, T> Graph<'find, T>

where T: Default,

pub fn try_lookup_or_insert( &mut self, id: ObjectId, update_data: impl FnOnce(&mut T) ) -> Result<Option<LazyCommit<'_>>, Error>

Lookup id without failing if the commit doesn’t exist, and assure that id is inserted into our set. If it wasn’t, associate it with the default value. Assure update_data(data) gets run. Return the commit when done. Note that none of the data updates happen if there was no commit named id.

impl<'find, T> Graph<'find, T>

Access and mutation

pub fn contains(&self, id: &oid) -> bool

Returns true if id has data associated with it, meaning that we processed it already.

pub fn get(&self, id: &oid) -> Option<&T>

Returns the data associated with id if available.

pub fn get_mut(&mut self, id: &oid) -> Option<&mut T>

Returns the data associated with id if available as mutable reference.

pub fn insert(&mut self, id: ObjectId, value: T) -> Option<T>

Insert id into the graph and associate it with value, returning the previous value associated with it if it existed.

pub fn clear(&mut self)

Remove all data from the graph to start over.

pub fn insert_parents( &mut self, id: &oid, new_parent_data: &mut dyn FnMut(ObjectId, i64) -> T, update_existing: &mut dyn FnMut(ObjectId, &mut T), first_parent: bool ) -> Result<(), Error>

Insert the parents of commit named id to the graph and associate new parents with data by calling new_parent_data(parent_id, committer_timestamp), or update existing parents data with update_existing(parent_id, &mut existing_data). If first_parent is true, only the first parent of commits will be looked at.

pub fn detach(self) -> HashMap<ObjectId, T, Builder>

Turn ourselves into the underlying graph structure, which is a mere mapping between object ids and their data.

impl<'find, T> Graph<'find, T>

Initialization

pub fn new( objects: impl Find + 'find, cache: impl Into<Option<Graph>> ) -> Graph<'find, T>

Create a new instance with objects to retrieve commits and optionally cache to accelerate commit access.

Performance

find should be optimized to access the same object repeatedly, ideally with an object cache to keep the last couple of most recently used commits. Furthermore, none-existing commits should not trigger the pack-db to be refreshed. Otherwise, performance may be sub-optimal in shallow repositories as running into non-existing commits will trigger a refresh of the packs directory.

impl<'find, T> Graph<'find, Commit<T>>

commit access

pub fn try_lookup_or_insert_commit_default( &mut self, id: ObjectId, new_data: impl FnOnce() -> T, update_data: impl FnOnce(&mut T) ) -> Result<Option<&mut Commit<T>>, Error>

Lookup id without failing if the commit doesn’t exist, and assure that id is inserted into our set with a commit with new_data() assigned. update_data(data) gets run either on existing or on new data.

Note that none of the data updates happen if id didn’t exist.

impl<'find, T> Graph<'find, Commit<T>>

where T: Default,

commit access

pub fn try_lookup_or_insert_commit( &mut self, id: ObjectId, update_data: impl FnOnce(&mut T) ) -> Result<Option<&mut Commit<T>>, Error>

Lookup id without failing if the commit doesn’t exist or id isn’t a commit, and assure that id is inserted into our set with a commit and default data assigned. update_data(data) gets run either on existing or on new data.

Note that none of the data updates happen if id didn’t exist.

If only commit data is desired without the need for attaching custom data, use try_lookup(id).to_owned() instead.

impl<'find, T> Graph<'find, T>

Lazy commit access

pub fn try_lookup_or_insert_default( &mut self, id: ObjectId, default: impl FnOnce() -> T, update_data: impl FnOnce(&mut T) ) -> Result<Option<LazyCommit<'_>>, Error>

Lookup id without failing if the commit doesn’t exist or id isn’t a commit, and assure that id is inserted into our set with a default value assigned to it. update_data(data) gets run either on existing or no new data. Return the commit when done.

Note that none of the data updates happen if id didn’t exist.

If only commit data is desired without the need for attaching custom data, use try_lookup(id) instead.

pub fn try_lookup(&mut self, id: &oid) -> Result<Option<LazyCommit<'_>>, Error>

Try to lookup id and return a handle to it for accessing its data, but don’t fail if the commit doesn’t exist or isn’t a commit.

It’s possible that commits don’t exist if the repository is shallow.

pub fn lookup(&mut self, id: &oid) -> Result<LazyCommit<'_>, Error>

Lookup id and return a handle to it, or fail if it doesn’t exist or is no commit.

Trait Implementations

impl<'find, T> Debug for Graph<'find, T>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a, 'find, T> Index<&'a oid> for Graph<'find, T>

type Output = T

The returned type after indexing.

fn index(&self, index: &'a oid) -> &<Graph<'find, T> as Index<&'a oid>>::Output

Performs the indexing (container[index]) operation.