Struct cargo::sources::registry::remote::RemoteRegistry

pub struct RemoteRegistry<'gctx> {
    name: InternedString,
    index_path: Filesystem,
    cache_path: Filesystem,
    source_id: SourceId,
    index_git_ref: GitReference,
    gctx: &'gctx GlobalContext,
    tree: RefCell<Option<Tree<'static>>>,
    repo: LazyCell<Repository>,
    head: Cell<Option<Oid>>,
    current_sha: Cell<Option<InternedString>>,
    needs_update: bool,
    quiet: bool,
}

A remote registry is a registry that lives at a remote URL (such as crates.io). The git index is cloned locally, and .crate files are downloaded as needed and cached locally.

This type is primarily accessed through the RegistryData trait.

See the module-level documentation for the index format and layout.

History of Git-based index registry

Using Git to host this index used to be quite efficient. The full index can be stored efficiently locally on disk, and once it is downloaded, all queries of a registry can happen locally and needn’t touch the network. Git-based index was a reasonable design choice at the time when HTTP/2 was just introduced.

However, the full index keeps growing as crates.io grows. It becomes relatively big and slows down the first use of Cargo. Git (specifically libgit2) is not efficient at handling huge amounts of small files either. On the other hand, newer protocols like HTTP/2 are prevalent and capable to serve a bunch of tiny files. Today, it is encouraged to use HttpRegistry, which is the default from 1.70.0. That being said, Cargo will continue supporting Git-based index for a pretty long while.

Fields

name: InternedString

The name of this source, a unique string (across all sources) used as the directory name where its cached content is stored.

index_path: Filesystem

Path to the registry index ($CARGO_HOME/registry/index/$REG-HASH).

cache_path: Filesystem

Path to the cache of .crate files ($CARGO_HOME/registry/cache/$REG-HASH).

source_id: SourceId

The unique identifier of this registry source.

index_git_ref: GitReference

This reference is stored so that when a registry needs update, it knows where to fetch from.

gctx: &'gctx GlobalContext

tree: RefCell<Option<Tree<'static>>>

A Git tree object to help this registry find crate metadata from the underlying Git repository.

This is stored here to prevent Git from repeatedly creating a tree object during each call into load().

repo: LazyCell<Repository>

A Git repository that contains the actual index we want.

head: Cell<Option<Oid>>

The current HEAD commit of the underlying Git repository.

current_sha: Cell<Option<InternedString>>

This stores sha value of the current HEAD commit for convenience.

needs_update: bool

Whether this registry needs to update package information.

See RemoteRegistry::mark_updated on how to make sure a registry index is updated only once per session.

quiet: bool

Disables status messages.

Implementations

impl<'gctx> RemoteRegistry<'gctx>

pub fn new( source_id: SourceId, gctx: &'gctx GlobalContext, name: &str, ) -> RemoteRegistry<'gctx>

Creates a Git-rebased remote registry for source_id.

• name — Name of a path segment where .crate tarballs and the registry index are stored. Expect to be unique.

fn repo(&self) -> CargoResult<&Repository>

Creates intermediate dirs and initialize the repository.

fn head(&self) -> CargoResult<Oid>

Get the object ID of the HEAD commit from the underlying Git repository.

fn tree(&self) -> CargoResult<Ref<'_, Tree<'_>>>

Returns a git2::Tree object of the current HEAD commit of the underlying Git repository.

fn current_version(&self) -> Option<InternedString>

Gets the current version of the registry index.

It is usually sha of the HEAD commit from the underlying Git repository.

fn is_updated(&self) -> bool

Whether the registry is up-to-date. See Self::mark_updated for more.

fn mark_updated(&self)

Marks this registry as up-to-date.

This makes sure the index is only updated once per session since it is an expensive operation. This generally only happens when the resolver is run multiple times, such as during cargo publish.

Trait Implementations

impl<'gctx> Drop for RemoteRegistry<'gctx>

Implemented to just be sure to drop tree field before our other fields. See SAFETY inside RemoteRegistry::tree() for more.

fn drop(&mut self)

Executes the destructor for this type.

impl<'gctx> RegistryData for RemoteRegistry<'gctx>

fn load( &mut self, _root: &Path, path: &Path, index_version: Option<&str>, ) -> Poll<CargoResult<LoadResponse>>

Read the general concept for load() on RegistryData::load.

index_version is a string representing the version of the file used to construct the cached copy.

Older versions of Cargo used the single value of the hash of the HEAD commit as a index_version. This is technically correct but a little too conservative. If a new commit is fetched all cached files need to be regenerated even if a particular file was not changed.

However if an old cargo has written such a file we still know how to read it, as long as we check for that hash value.

Cargo now uses a hash of the file’s contents as provided by git.

fn invalidate_cache(&mut self)

Read the general concept for invalidate_cache() on RegistryData::invalidate_cache.

To fully invalidate, undo RemoteRegistry::mark_updated’s work.

fn prepare(&self) -> CargoResult<()>

Performs initialization for the registry.

fn index_path(&self) -> &Filesystem

Returns the path to the index.

fn assert_index_locked<'a>(&self, path: &'a Filesystem) -> &'a Path

Validates that the global package cache lock is held.

fn config(&mut self) -> Poll<CargoResult<Option<RegistryConfig>>>

Loads the config.json file and returns it.

fn block_until_ready(&mut self) -> CargoResult<()>

Block until all outstanding Poll::Pending requests are Poll::Ready.

fn set_quiet(&mut self, quiet: bool)

If quiet, the source should not display any progress or status messages.

fn is_updated(&self) -> bool

Is the local cached data up-to-date?

fn download(&mut self, pkg: PackageId, checksum: &str) -> CargoResult<MaybeLock>

Prepare to start downloading a .crate file.

fn finish_download( &mut self, pkg: PackageId, checksum: &str, data: &[u8], ) -> CargoResult<File>

Finish a download by saving a .crate file to disk.

fn is_crate_downloaded(&self, pkg: PackageId) -> bool

Returns whether or not the .crate file is already downloaded.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 192 bytes