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>) -> Self

Constructs a new PackageCache with only one layer.

pub fn with_cached_origin(self) -> Self

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, ) -> Self

where I: IntoIterator, I::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>>, concurrent_requests_semaphore: Option<Arc<Semaphore>>, ) -> 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, record: Option<&PackageRecord>, 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.

If a PackageRecord is provided, the cache key is derived from the record, which includes its hashes. This ensures that packages that share the same name, version and build string but have different content do not collide in the cache. Otherwise, the cache key is derived from the package filename only.

pub async fn get_or_fetch_from_url_with_retry( &self, pkg: impl Into<CacheKey>, url: Url, client: LazyClient, retry_policy: impl RetryPolicy + Send + 'static + Clone, reporter: Option<Arc<dyn CacheReporter>>, concurrent_requests_semaphore: Option<Arc<Semaphore>>, ) -> 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.

The optional concurrent_requests_semaphore limits the number of simultaneous downloads. A permit is acquired only when a download is actually started (i.e. the package is not already cached), and is held for the duration of the download and extraction.

Trait Implementations

impl Clone for PackageCache

fn clone(&self) -> PackageCache

Returns a duplicate of the value.

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

Performs copy-assignment from source.