Struct PackageCache

pub struct PackageCache { /* private fields */ }

A PackageCache manages a cache of extracted Conda packages on disk.

The store does not provide an implementation to get the data into the store. Instead, this is left up to the user when the package is requested. If the package is found in the cache it is returned immediately. However, if the cache is stale a user defined function is called to populate the cache. This separates the concerns between caching and fetching of the content.

Implementations

impl PackageCache

pub fn new(path: impl Into<PathBuf>) -> PackageCache

Constructs a new PackageCache with only one layer.

pub fn with_cached_origin(self) -> PackageCache

Adds the origin (url or path) to the cache key to avoid unwanted cache hits of packages with packages with similar properties.

pub async fn acquire_global_lock( &self, ) -> Result<CacheGlobalLock, PackageCacheError>

Acquires a global lock on the package cache.

This lock can be used to coordinate multiple package operations, reducing the overhead of acquiring individual locks for each package. The lock is held until the returned CacheGlobalLock is dropped.

This is particularly useful when installing many packages at once, as it significantly reduces the number of file locking syscalls.

pub fn new_layered<I>( paths: I, cache_origin: bool, validation_mode: ValidationMode, ) -> PackageCache

where I: IntoIterator, <I as IntoIterator>::Item: Into<PathBuf>,

Constructs a new PackageCache located at the specified paths. Layers are queried in the order they are provided. The first writable layer is written to.

pub fn split_layers(&self) -> (Vec<&PackageCacheLayer>, Vec<&PackageCacheLayer>)

Returns a tuple containing two sets of layers:

• A collection of read-only layers.
• A collection of writable layers.

The permissions are checked at the time of the function call.

pub async fn get_or_fetch<F, Fut, E>( &self, pkg: impl Into<CacheKey>, fetch: F, reporter: Option<Arc<dyn CacheReporter>>, ) -> Result<CacheMetadata, PackageCacheError>

where F: Fn(PathBuf) -> Fut + Send + 'static, Fut: Future<Output = Result<(), E>> + Send + 'static, E: Error + Send + Sync + 'static,

Returns the directory that contains the specified package.

If the package was previously successfully fetched and stored in the cache the directory containing the data is returned immediately. If the package was not previously fetch the filesystem is checked to see if a directory with valid package content exists. Otherwise, the user provided fetch function is called to populate the cache.

Layer Priority

Layers are checked in the order they were provided to PackageCache::new_layered. If a valid package is found in any layer, it is returned immediately. If no valid package is found in any layer, the package is fetched and written to the first writable layer.

If the package is already being fetched by another task/thread the request is coalesced. No duplicate fetch is performed.

pub async fn get_or_fetch_from_url( &self, pkg: impl Into<CacheKey>, url: Url, client: LazyClient, reporter: Option<Arc<dyn CacheReporter>>, ) -> Result<CacheMetadata, PackageCacheError>

Returns the directory that contains the specified package.

This is a convenience wrapper around get_or_fetch which fetches the package from the given URL if the package could not be found in the cache.

pub async fn get_or_fetch_from_path( &self, path: &Path, reporter: Option<Arc<dyn CacheReporter>>, ) -> Result<CacheMetadata, PackageCacheError>

Returns the directory that contains the specified package.

This is a convenience wrapper around get_or_fetch which fetches the package from the given path if the package could not be found in the cache.

pub async fn get_or_fetch_from_url_with_retry( &self, pkg: impl Into<CacheKey>, url: Url, client: LazyClient, retry_policy: impl RetryPolicy + Send + Clone + 'static, reporter: Option<Arc<dyn CacheReporter>>, ) -> Result<CacheMetadata, PackageCacheError>

Returns the directory that contains the specified package.

This is a convenience wrapper around get_or_fetch which fetches the package from the given URL if the package could not be found in the cache.

This function assumes that the client is already configured with a retry middleware that will retry any request that fails. This function uses the passed in retry_policy if, after the request has been sent and the response is successful, streaming of the package data fails and the whole request must be retried.

Trait Implementations

impl Clone for PackageCache

fn clone(&self) -> PackageCache

Returns a copy of the value.

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

Performs copy-assignment from source.