Struct PackageCache 

pub struct PackageCache { /* private fields */ }

High-performance package payload cache.

This struct manages a disk-based cache of package variant payloads, enabling fast environment resolution without fetching from shared storage.

Example

use rez_next_package::package_cache::PackageCache;

let cache = PackageCache::new("/path/to/cache").unwrap();

Implementations

impl PackageCache

pub fn new<P: AsRef<Path>>(path: P) -> Result<Self, PackageCacheError>

Create a new package cache at the given root path.

Errors

Returns PackageCacheError::NotADirectory if path is not an existing directory.

pub fn with_config<P: AsRef<Path>>( path: P, config: CacheConfig, ) -> Result<Self, PackageCacheError>

Create with custom configuration.

pub fn root(&self) -> &Path

Get the root path of the cache.

pub fn config(&self) -> &CacheConfig

Get the configuration.

pub fn get_cached_root( &self, handle: &VariantHandle, ) -> (CacheStatus, Option<PathBuf>)

Check if a variant is cached and return its root path.

Updates the last-accessed time on the cache entry.

Returns

(CacheStatus, Option<PathBuf>) - status and path if found.

pub fn add_variant( &self, handle: &VariantHandle, source_root: &Path, force: bool, ) -> Result<(CacheStatus, PathBuf), PackageCacheError>

Add a variant’s payload to the cache.

Copies the payload from source_root to the cache.

Arguments

• handle - The variant handle
• source_root - Path to the variant’s payload on disk
• force - Force caching even if checks fail

Returns

(CacheStatus, PathBuf) - final status and cache path.

pub fn remove_variant( &self, handle: &VariantHandle, ) -> (CacheStatus, Option<PathBuf>)

Remove a variant from the cache.

Moves the payload to the to_delete directory; actual deletion happens during clean().

pub fn list_cached(&self) -> Vec<(VariantHandle, PathBuf, CacheStatus)>

List all cached variants.

Returns a list of (handle, path, status) tuples.

pub fn clean(&self, time_limit_secs: Option<u64>) -> CleanStats

Clean the cache by removing:

• Old unused entries (based on max_age_secs)
• Stalled copies
• Entries in to_delete directory

Arguments

• time_limit_secs - Optional time limit for cleaning operation

pub fn cache_near_full(&self) -> bool

Check if the cache disk is near full.

Returns true if available space is below min_free_space_bytes. Aligns with rez.package_cache.PackageCache.cache_near_full().

pub fn variant_meets_space_requirements(&self, variant_root: &Path) -> bool

Check if adding a variant would leave enough free space.

Aligns with rez.package_cache.PackageCache.variant_meets_space_requirements().

Arguments

• variant_root - Path to the variant’s payload

Returns

true if there’s enough space to cache this variant.