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

source ·

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

Expand description

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§

§`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.

§`config: &'cfg Config`§`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 repeatly 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 informations.

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

§`quiet: bool`

Disables status messages.

## Implementations§

source§

### impl<'cfg> RemoteRegistry<'cfg>

source

#### pub fn new( source_id: SourceId, config: &'cfg Config, name: &str ) -> RemoteRegistry<'cfg>

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.

source

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

Creates intermediate dirs and initialize the repository.

source

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

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

source

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

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

source

#### 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.

source

#### fn is_updated(&self) -> bool

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

source

#### 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§

source§

### impl<'cfg> Drop for RemoteRegistry<'cfg>

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

source§

#### fn drop(&mut self)

Executes the destructor for this type. Read more
source§

### impl<'cfg> RegistryData for RemoteRegistry<'cfg>

source§

#### 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.

source§

#### 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.

source§

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

Performs initialization for the registry. Read more
source§

#### fn index_path(&self) -> &Filesystem

Returns the path to the index. Read more
source§

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

Validates that the global package cache lock is held. Read more
source§

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

Loads the `config.json` file and returns it. Read more
source§

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

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

#### fn set_quiet(&mut self, quiet: bool)

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

#### fn is_updated(&self) -> bool

Is the local cached data up-to-date?
source§

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

Prepare to start downloading a `.crate` file. Read more
source§

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

Finish a download by saving a `.crate` file to disk. Read more
source§

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

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

## Auto Trait Implementations§

§

### impl<'cfg> !RefUnwindSafe for RemoteRegistry<'cfg>

§

### impl<'cfg> !Send for RemoteRegistry<'cfg>

§

### impl<'cfg> !Sync for RemoteRegistry<'cfg>

§

### impl<'cfg> Unpin for RemoteRegistry<'cfg>

§

### impl<'cfg> !UnwindSafe for RemoteRegistry<'cfg>

## Blanket Implementations§

source§

### impl<T> Any for Twhere T: 'static + ?Sized,

source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
source§

### impl<T> Borrow<T> for Twhere T: ?Sized,

source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

### impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

### impl<T> From<T> for T

source§

#### fn from(t: T) -> T

Returns the argument unchanged.

source§

### impl<T, U> Into<U> for Twhere U: From<T>,

source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

source§

### impl<T> Same<T> for T

§

#### type Output = T

Should always be `Self`
source§

### impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

#### type Error = Infallible

The type returned in the event of a conversion error.
source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

### impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

### impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

#### fn vzip(self) -> V

## 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:176 bytes