Struct git_odb::store::Handle

pub struct Handle<S>where
    S: Deref<Target = Store> + Clone,{
    pub refresh: RefreshMode,
    pub max_recursion_depth: usize,
    pub ignore_replacements: bool,
    /* private fields */
}

This effectively acts like a handle but exists to be usable from the actual crate::Handle implementation which adds caches on top. Each store is quickly cloned and contains thread-local state for shared packs.

Fields

refresh: RefreshMode

Defines what happens when there is no more indices to load.

max_recursion_depth: usize

The maximum recursion depth for resolving ref-delta base objects, that is objects referring to other objects within a pack. Recursive loops are possible only in purposefully crafted packs. This value doesn’t have to be huge as in typical scenarios, these kind of objects are rare and chains supposedly are even more rare.

ignore_replacements: bool

If true, replacements will not be performed even if these are available.

Implementations

impl<S> Handle<S>where
    S: Deref<Target = Store> + Clone,

pub fn packed_object_count(&self) -> Result<u64, Error>

Return the exact number of packed objects after loading all currently available indices as last seen on disk.

pub fn disambiguate_prefix(
    &self,
    candidate: Candidate
) -> Result<Option<Prefix>, Error>

Given a prefix candidate with an object id and an initial hex_len, check if it only matches a single object within the entire object database and increment its hex_len by one until it is unambiguous. Return Ok(None) if no object with that prefix exists.

pub fn lookup_prefix(
    &self,
    prefix: Prefix,
    candidates: Option<&mut HashSet<ObjectId>>
) -> Result<Option<Outcome>, Error>

Find the only object matching prefix and return it as Ok(Some(Ok(<ObjectId>))), or return Ok(Some(Err(())) if multiple different objects with the same prefix were found.

Return Ok(None) if no object matched the prefix.

Pass candidates to obtain the set of all object ids matching prefix, with the same return value as one would have received if it remained None.

Performance Note

• Unless the handles refresh mode is set to Never, each lookup will trigger a refresh of the object databases files on disk if the prefix doesn’t lead to ambiguous results.
• Since all objects need to be examined to assure non-ambiguous return values, after calling this method all indices will be loaded.
• If candidates is Some(…), the traversal will continue to obtain all candidates, which takes more time as there is no early abort.

Examples found in repository

src/store_impls/dynamic/prefix.rs (line 111)

    pub fn disambiguate_prefix(
        &self,
        mut candidate: disambiguate::Candidate,
    ) -> Result<Option<git_hash::Prefix>, disambiguate::Error> {
        let max_hex_len = candidate.id().kind().len_in_hex();
        if candidate.hex_len() == max_hex_len {
            return Ok(self.contains(candidate.id()).then(|| candidate.to_prefix()));
        }

        while candidate.hex_len() != max_hex_len {
            let res = self.lookup_prefix(candidate.to_prefix(), None)?;
            match res {
                Some(Ok(_id)) => return Ok(Some(candidate.to_prefix())),
                Some(Err(())) => {
                    candidate.inc_hex_len();
                    continue;
                }
                None => return Ok(None),
            }
        }
        Ok(Some(candidate.to_prefix()))
    }

impl<S> Handle<S>where
    S: Deref<Target = Store> + Clone,

pub fn iter(&self) -> Result<AllObjects, Error>

Return an iterator over all, possibly duplicate, objects, first the ones in all packs of all linked databases (via alternates), followed by all loose objects.

impl<S> Handle<S>where
    S: Deref<Target = Store> + Clone,

pub fn prevent_pack_unload(&mut self)

Call once if pack ids are stored and later used for lookup, meaning they should always remain mapped and not be unloaded even if they disappear from disk. This must be called if there is a chance that git maintenance is happening while a pack is created.

pub fn store_ref(&self) -> &S::Target

Return a shared reference to the contained store.

Examples found in repository

src/store_impls/dynamic/iter.rs (line 225)

    pub fn iter(&self) -> Result<AllObjects, dynamic::load_index::Error> {
        AllObjects::new(self.store_ref())
    }

src/store_impls/dynamic/handle.rs (line 362)

    pub fn into_arc(self) -> std::io::Result<super::Handle<Arc<super::Store>>> {
        let store = Arc::new(super::Store::try_from(self.store_ref())?);
        let mut cache = store.to_handle_arc();
        cache.refresh = self.refresh;
        cache.max_recursion_depth = self.max_recursion_depth;
        Ok(cache)
    }

src/store_impls/dynamic/find.rs (line 363)

    fn location_by_oid(
        &self,
        id: impl AsRef<git_hash::oid>,
        buf: &mut Vec<u8>,
    ) -> Option<git_pack::data::entry::Location> {
        assert!(
            matches!(self.token.as_ref(), Some(handle::Mode::KeepDeletedPacksAvailable)),
            "BUG: handle must be configured to `prevent_pack_unload()` before using this method"
        );

        assert!(self.store_ref().replacements.is_empty() || self.ignore_replacements, "Everything related to packing must not use replacements. These are not used here, but it should be turned off for good measure.");

        let id = id.as_ref();
        let mut snapshot = self.snapshot.borrow_mut();
        'outer: loop {
            {
                let marker = snapshot.marker;
                for (idx, index) in snapshot.indices.iter_mut().enumerate() {
                    if let Some(handle::index_lookup::Outcome {
                        object_index: handle::IndexForObjectInPack { pack_id, pack_offset },
                        index_file: _,
                        pack: possibly_pack,
                    }) = index.lookup(id)
                    {
                        let pack = match possibly_pack {
                            Some(pack) => pack,
                            None => match self.store.load_pack(pack_id, marker).ok()? {
                                Some(pack) => {
                                    *possibly_pack = Some(pack);
                                    possibly_pack.as_deref().expect("just put it in")
                                }
                                None => {
                                    // The pack wasn't available anymore so we are supposed to try another round with a fresh index
                                    match self.store.load_one_index(self.refresh, snapshot.marker).ok()? {
                                        Some(new_snapshot) => {
                                            *snapshot = new_snapshot;
                                            self.clear_cache();
                                            continue 'outer;
                                        }
                                        None => {
                                            // nothing new in the index, kind of unexpected to not have a pack but to also
                                            // to have no new index yet. We set the new index before removing any slots, so
                                            // this should be observable.
                                            return None;
                                        }
                                    }
                                }
                            },
                        };
                        let entry = pack.entry(pack_offset);

                        buf.resize(entry.decompressed_size.try_into().expect("representable size"), 0);
                        assert_eq!(pack.id, pack_id.to_intrinsic_pack_id(), "both ids must always match");

                        let res = pack.decompress_entry(&entry, buf).ok().map(|entry_size_past_header| {
                            git_pack::data::entry::Location {
                                pack_id: pack.id,
                                pack_offset,
                                entry_size: entry.header_size() + entry_size_past_header,
                            }
                        });

                        if idx != 0 {
                            snapshot.indices.swap(0, idx);
                        }
                        return res;
                    }
                }
            }

            match self.store.load_one_index(self.refresh, snapshot.marker).ok()? {
                Some(new_snapshot) => {
                    *snapshot = new_snapshot;
                    self.clear_cache();
                }
                None => return None,
            }
        }
    }

pub fn store(&self) -> S

Return an owned store with shared ownership.

pub fn refresh_never(&mut self)

Set the handle to never cause ODB refreshes if an object could not be found.

The latter is the default, as typically all objects referenced in a git repository are contained in the local clone. More recently, however, this doesn’t always have to be the case due to sparse checkouts and other ways to only have a limited amount of objects available locally.

pub fn refresh_mode(&mut self) -> RefreshMode

Return the current refresh mode.

impl Handle<Rc<Store>>

pub fn into_arc(self) -> Result<Handle<Arc<Store>>>

Convert a ref counted store into one that is ref-counted and thread-safe, by creating a new Store.

Examples found in repository

src/cache.rs (line 24)

    pub fn into_arc(self) -> std::io::Result<Cache<crate::store::Handle<Arc<crate::Store>>>> {
        let inner = self.inner.into_arc()?;
        Ok(Cache {
            inner,
            new_pack_cache: self.new_pack_cache,
            new_object_cache: self.new_object_cache,
            pack_cache: self.pack_cache,
            object_cache: self.object_cache,
        })
    }

impl Handle<Arc<Store>>

pub fn into_arc(self) -> Result<Handle<Arc<Store>>>

Convert a ref counted store into one that is ref-counted and thread-safe, by creating a new Store

Trait Implementations

impl<S> Clone for Handle<S>where
    S: Deref<Target = Store> + Clone,

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S> Drop for Handle<S>where
    S: Deref<Target = Store> + Clone,

fn drop(&mut self)

Executes the destructor for this type.

impl<S> Find for Handle<S>where
    S: Deref<Target = Store> + Clone,

type Error = Error

The error returned by try_find()

fn contains(&self, id: impl AsRef<oid>) -> bool

Returns true if the object exists in the database.

fn try_find_cached<'a>(
    &self,
    id: impl AsRef<oid>,
    buffer: &'a mut Vec<u8>,
    pack_cache: &mut impl DecodeEntry
) -> Result<Option<(Data<'a>, Option<Location>)>, Self::Error>

Like Find::try_find(), but with support for controlling the pack cache. A pack_cache can be used to speed up subsequent lookups, set it to crate::cache::Never if the workload isn’t suitable for caching.

fn location_by_oid(
    &self,
    id: impl AsRef<oid>,
    buf: &mut Vec<u8>
) -> Option<Location>

Find the packs location where an object with id can be found in the database, or None if there is no pack holding the object.

fn pack_offsets_and_oid(&self, pack_id: u32) -> Option<Vec<(u64, ObjectId)>>

Obtain a vector of all offsets, in index order, along with their object id.

fn entry_by_location(&self, location: &Location) -> Option<Entry>

Return the find::Entry for location if it is backed by a pack.

fn try_find<'a>(
    &self,
    id: impl AsRef<oid>,
    buffer: &'a mut Vec<u8, Global>
) -> Result<Option<(Data<'a>, Option<Location>)>, Self::Error>

Find an object matching id in the database while placing its raw, decoded data into buffer. A pack_cache can be used to speed up subsequent lookups, set it to crate::cache::Never if the workload isn’t suitable for caching.

impl<S> Find for Handle<S>where
    S: Deref<Target = Store> + Clone,
    Self: Find,

type Error = <Handle<S> as Find>::Error

The error returned by try_find()

fn contains(&self, id: impl AsRef<oid>) -> bool

Returns true if the object exists in the database.

fn try_find<'a>(
    &self,
    id: impl AsRef<oid>,
    buffer: &'a mut Vec<u8>
) -> Result<Option<Data<'a>>, Self::Error>

Find an object matching id in the database while placing its raw, undecoded data into buffer.

impl<S> Header for Handle<S>where
    S: Deref<Target = Store> + Clone,

type Error = Error

The error returned by try_header().

fn try_header(&self, id: impl AsRef<oid>) -> Result<Option<Header>, Self::Error>

Try to read the header of the object associated with id or return None if it could not be found.

impl<S> Write for Handle<S>where
    S: Deref<Target = Store> + Clone,

type Error = Error

The error type used for all trait methods.

fn write_stream(
    &self,
    kind: Kind,
    size: u64,
    from: impl Read
) -> Result<ObjectId, Self::Error>

As write, but takes an input stream. This is commonly used for writing blobs directly without reading them to memory first.

fn write(&self, object: impl WriteTo) -> Result<ObjectId, Self::Error>

Write objects using the intrinsic kind of hash into the database, returning id to reference it in subsequent reads.

fn write_buf(&self, object: Kind, from: &[u8]) -> Result<ObjectId, Self::Error>

As write, but takes an object kind along with its encoded bytes.