Struct Graph

pub struct Graph<'find, 'cache, 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 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<'cache, T> Graph<'_, 'cache, T>

where T: Default,

pub fn try_lookup_or_insert( &mut self, id: ObjectId, update_data: impl FnOnce(&mut T), ) -> Result<Option<LazyCommit<'_, 'cache>>, 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<'cache, T> Graph<'_, 'cache, T>

Access and mutation

pub fn len(&self) -> usize

Returns the amount of entries in the graph.

pub fn is_empty(&self) -> bool

Returns true if there is no entry in the graph.

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 id if it existed.

pub fn insert_data<E>( &mut self, id: ObjectId, make_data: impl FnMut(LazyCommit<'_, 'cache>) -> Result<T, E>, ) -> Result<Option<T>, E>

where E: From<Error>,

Insert id into the graph and associate it with the value returned by make_data, and returning the previous value associated with id if it existed. Fail if id doesn’t exist in the object database.

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 insert_parents_with_lookup<E>( &mut self, id: &oid, parent_data: &mut dyn FnMut(ObjectId, LazyCommit<'_, 'cache>, Option<&mut T>) -> Result<T, E>, ) -> Result<(), E>

where E: From<Error> + From<Error> + From<Error>,

Insert the parents of commit named id to the graph and associate new parents with data as produced by parent_data(parent_id, parent_info, maybe-existing-data &mut T) -> T, which is always provided the full parent commit information. It will be provided either existing data, along with complete information about the parent, and produces new data even though it’s only used in case the parent isn’t stored in the graph yet.

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, 'cache, T> Graph<'find, 'cache, T>

Initialization

pub fn new( objects: impl Find + 'find, cache: Option<&'cache Graph>, ) -> Graph<'find, 'cache, 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<T> Graph<'_, '_, Commit<T>>

Commit based methods

pub fn get_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 in the graph, but insert it if it’s not yet present by looking it up without failing if the commit doesn’t exist. Call new_data() to obtain data for a newly inserted commit. 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.

pub fn clear_commit_data(&mut self, clear: impl FnMut(&mut T))

For each stored commit, call clear on its data.

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

where T: Default,

Commit based methods

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

Lookup id in the graph, but insert it if it’s not yet present by looking it up without failing if the commit doesn’t exist. Newly inserted commits are populated with default data. 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.

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

Lookup id in the graph, but insert it if it’s not yet present by looking it up without failing if the commit doesn’t exist. update_commit(commit) gets run either on existing or on new data.

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

impl<'cache, T> Graph<'_, 'cache, 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<'_, 'cache>>, 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<'_, 'cache>>, 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<'_, 'cache>, Error>

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

Trait Implementations

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

where T: Debug,

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

Formats the value using the given formatter.

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

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.