Struct git_odb::pack::tree::Tree

pub struct Tree<T> { /* fields omitted */ }

A tree that allows one-time iteration over all nodes and their children, consuming it in the process, while being shareable among threads without a lock. It does this by making the run-time guarantee that iteration only happens once.

Implementations

impl<T> Tree<T>

Iteration

pub fn iter_root_chunks(&mut self, size: usize) -> Chunks<'_, T>

Return an iterator over chunks of roots. Roots are not children themselves, they have no parents.

impl<T> Tree<T> where
    T: Default + Send, 

pub fn traverse<F, P, MBFN, S, E>(
    self,
    should_run_in_parallel: impl FnOnce() -> bool,
    resolve: F,
    object_progress: P,
    size_progress: P,
    thread_limit: Option<usize>,
    pack_entries_end: u64,
    new_thread_state: impl Fn() -> S + Send + Sync,
    inspect_object: MBFN
) -> Result<Vec<Item<T>>, Error> where
    F: for<'r> Fn(EntrySlice, &'r mut Vec<u8>) -> Option<()> + Send + Sync,
    P: Progress + Send,
    MBFN: Fn(&mut T, &mut <P as Progress>::SubProgress, Context<'_, S>) -> Result<(), E> + Send + Sync,
    E: Error + Send + Sync + 'static, 

Traverse this tree of delta objects with a function inspect_object to process each object at will.

• should_run_in_parallel() -> bool returns true if the underlying pack is big enough to warrant parallel traversal at all.
• resolve(EntrySlice, &mut Vec<u8>) -> Option<()> resolves the bytes in the pack for the given EntrySlice and stores them in the output vector. It returns Some(()) if the object existed in the pack, or None to indicate a resolution error, which would abort the operation as well.
• object_progress is a progress instance to track progress for each object in the traversal.
• size_progress is a progress instance to track the overall progress.
• tread_limit is limits the amount of threads used if Some or otherwise defaults to all available logical cores.
• pack_entries_end marks one-past-the-last byte of the last entry in the pack, as the last entries size would otherwise be unknown as it's not part of the index file.
• new_thread_state() -> State is a function to create state to be used in each thread, invoked once per thread.
• inspect_object(node_data: &mut T, progress: Progress, context: Context<ThreadLocal State>) -> Result<(), CustomError> is a function running for each thread receiving fully decoded objects along with contextual information, which either succceeds with Ok(()) or returns a CustomError. Note that node_data can be modified to allow storing maintaining computation results on a per-object basis.

This method returns a vector of all tree items, along with their potentially modified custom node data.

Note that this method consumed the Tree to assure safe parallel traversal with mutation support.

impl<T> Tree<T>

Generate tree from certain input

pub fn from_offsets_in_pack(
    data_sorted_by_offsets: impl Iterator<Item = T>,
    get_pack_offset: impl Fn(&T) -> u64,
    pack_path: impl AsRef<Path>,
    progress: impl Progress,
    resolve_in_pack_id: impl Fn(Id<'_>) -> Option<u64>
) -> Result<Self, Error>

Create a new Tree from any data sorted by offset, ascending as returned by the data_sorted_by_offsets iterator.

• get_pack_offset(item: &T) -> PackOffset` is a function returning the pack offset of the given item, which can be used for obtaining the objects entry within the pack.
• pack_path is the path to the pack file itself and from which to read the entry data, which is a pack file matching the offsets returned by get_pack_offset(…).
• progress is used to track progress when creating the tree.
• resolve_in_pack_id(borrowed::Id) -> Option<PackOffset> takes an object ID and tries to resolve it to an object within this pack if possible. Failing to do so aborts the operation, and this function is not expected to be called in usual packs. It's a theoretical possibility though.

Note that the sort order is ascending. The given pack file path must match the provided offsets.

impl<T> Tree<T>

pub fn with_capacity(num_objects: usize) -> Result<Self, Error>

Instantiate a empty tree capable of storing num_objects amounts of items.

pub fn add_root(&mut self, offset: u64, data: T) -> Result<(), Error>

Add a new root node, one that only has children but is not a child itself, at the given pack offset and associate custom data with it.

pub fn add_child(
    &mut self,
    base_offset: u64,
    offset: u64,
    data: T
) -> Result<(), Error>

Add a child of the item at base_offset which itself resides at pack offset and associate custom data with it.

pub fn into_items(self) -> Vec<Item<T>>

Transform this Tree into its items.

Trait Implementations

impl<T> Sync for Tree<T>

SAFETY: We solemnly swear…that this is sync because without the unsafe cell, it is also sync. But that's really the only reason why I would dare to know.