Struct SummariesCache

pub struct SummariesCache<'a> {
    pub versions: Vec<(Version, &'a [u8])>,
    pub index_version: &'a str,
}

A representation of the cache on disk that Cargo maintains of summaries.

Cargo will initially parse all summaries in the registry and will then serialize that into this form and place it in a new location on disk, ensuring that access in the future is much speedier.

For serialization and deserialization of this on-disk index cache of summaries, see SummariesCache::serialize and SummariesCache::parse.

The format of the index cache

The idea of this format is that it’s a very easy file for Cargo to parse in future invocations. The read from disk should be fast and then afterwards all we need to know is what versions correspond to which JSON blob.

Currently the format looks like:

+---------------+----------------------+--------------------+---+
| cache version | index schema version | index file version | 0 |
+---------------+----------------------+--------------------+---+

followed by one or more (version + JSON blob) pairs…

+----------------+---+-----------+---+
| semver version | 0 | JSON blob | 0 | ...
+----------------+---+-----------+---+

Each field represents:

• cache version — Intended to ensure that there’s some level of future compatibility against changes to this cache format so if different versions of Cargo share the same cache they don’t get too confused.
• index schema version — The schema version of the raw index file. See IndexPackage::v for the detail.
• index file version — Tracks when a cache needs to be regenerated. A cache regeneration is required whenever the index file itself updates.
• semver version — The version for each JSON blob. Extracted from the blob for fast queries without parsing the entire blob.
• JSON blob — The actual metadata for each version of the package. It has the same representation as IndexPackage.

Changes between each cache version

• 1: The original version.
• 2: Added the “index schema version” field so that if the index schema changes, different versions of cargo won’t get confused reading each other’s caches.
• 3: Bumped the version to work around an issue where multiple versions of a package were published that differ only by semver metadata. For example, openssl-src 110.0.0 and 110.0.0+1.1.0f. Previously, the cache would be incorrectly populated with two entries, both 110.0.0. After this, the metadata will be correctly included. This isn’t really a format change, just a version bump to clear the incorrect cache entries. Note: the index shouldn’t allow these, but unfortunately crates.io doesn’t check it.

See CURRENT_CACHE_VERSION for the current cache version.

Fields

versions: Vec<(Version, &'a [u8])>

JSON blobs of the summaries. Each JSON blob has a Version beside, so that Cargo can query a version without full JSON parsing.

index_version: &'a str

For cache invalidation, we tracks the index file version to determine when to regenerate the cache itself.

Implementations

impl<'a> SummariesCache<'a>

pub fn parse(data: &'a [u8]) -> CargoResult<SummariesCache<'a>>

Deserializes an on-disk cache.

pub fn serialize(&self, index_version: &str) -> Vec<u8>

Serializes itself with a given index_version.

Trait Implementations

impl<'a> Default for SummariesCache<'a>

fn default() -> SummariesCache<'a>

Returns the “default value” for a type.

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: 40 bytes