Struct Cache 

pub struct Cache { /* private fields */ }

A configured GSYM filesystem cache.

Directory descriptors are pinned once opened. Create a new Cache after replacing a cache namespace directory; ordinary entry creation and removal do not require reopening it.

See docs::deployment for root selection, epochs, filesystem requirements, and the trust model.

Implementations

impl Cache

pub fn record_access(&self, build_id: &BuildId) -> Result<AccessUpdate>

Records a cache hit without changing the immutable GSYM file’s mtime.

Marker updates are limited to once per hour to avoid write traffic on repeated hits. Callers should invoke this only after a successful Cache::lookup; recording a missing build ID creates an orphan marker that a later scrub pass will remove.

Errors

Returns an error when the marker cannot be inspected or updated.

impl Cache

pub fn open(root: impl AsRef<Path>, epoch: CacheEpoch) -> Result<Self>

Opens a cache namespace without creating it.

A missing root is valid and produces cache misses. An existing root must be a private non-symlink directory owned by the effective user.

Errors

Returns an error if the existing root is insecure or cannot be inspected.

pub fn open_xdg( application: impl AsRef<OsStr>, epoch: CacheEpoch, ) -> Result<Self>

Opens an application cache below $XDG_CACHE_HOME.

An unset, empty, or relative XDG_CACHE_HOME falls back to $HOME/.cache as required by the XDG Base Directory Specification. application must be one normal path component. The resulting root is <cache-home>/<application>/gsym.

Privileged applications should use Cache::open with an explicitly configured root instead of trusting process environment variables.

Errors

Returns an error when no absolute cache home is available, the application identifier is invalid, or the resulting root is insecure.

pub fn root(&self) -> &Path

Returns the user-configured cache root.

pub const fn epoch(&self) -> CacheEpoch

Returns this cache’s converter epoch.

pub fn lookup(&self, build_id: &BuildId) -> Result<Option<CacheEntry>>

Opens a cached GSYM file without taking a lock.

The returned entry owns its read-only file descriptor, preventing a lookup-to-open race with pruning. Lookup validates filesystem ownership and file type but deliberately does not decode or fully verify GSYM on this hot path. Managed population and scrubbing perform full verification.

Errors

Returns an error for filesystem failures or an untrusted entry. A file that does not exist returns Ok(None).

impl Cache

pub fn stats(&self) -> Result<CacheStats>

Counts recognized GSYM objects in this converter epoch without writing to the cache.

Errors

Returns an error when the object tree cannot be scanned.

pub fn prune(&self, policy: PrunePolicy) -> Result<PruneOutcome>

Prunes this converter epoch’s least-recently-used objects under a nonblocking maintenance lock.

Capacity pruning starts only above a high watermark and continues to 80% of it. This hysteresis prevents a deletion on every subsequent publication. Objects whose population lock is held are skipped.

See docs::operations for scheduling and recovery guidance.

Errors

Returns an error when the cache cannot be scanned, locked, or modified.

pub fn scrub(&self) -> Result<ScrubOutcome>

Verifies every recognized object and removes corrupt entries, expired negative records, and stale crash-leftover staging files.

Temporary files younger than one day are retained. Older files are removed only after acquiring their build identifier’s population lock, so a long-running conversion cannot lose its staging path.

See docs::operations for the full repair contract and crash behavior.

Errors

Returns an error when the cache cannot be scanned, locked, mapped, or modified. Transient mapping failures do not cause object deletion.

impl Cache

pub fn try_begin_population<'cache>( &'cache self, build_id: &'cache BuildId, ) -> Result<PopulationOutcome<'cache>>

Tries to become the sole population owner for a build identifier.

This never waits for another process. After acquiring the advisory lock it rechecks the cache, closing the race between lookup and lock. An existing entry is fully verified before it is returned as PopulationOutcome::Present. Confirmed corruption is removed only while holding the population lock; transient I/O failures never cause deletion.

See docs::operations for the complete state machine and docs::cookbook for recipes.

Errors

Returns an error when the cache directories or lock file cannot be created, inspected, or locked.

Example

use std::fs::File;
use std::io;
use gsym_cache::{BuildId, Cache, CacheEpoch, PopulationOutcome};

let cache = Cache::open("/var/cache/my-profiler/gsym", CacheEpoch::new(1))?;
let build_id = BuildId::new([0x12; 20])?;

match cache.try_begin_population(&build_id)? {
    PopulationOutcome::Present(entry) => drop(entry),
    PopulationOutcome::Acquired(population) => {
        let mut source = File::open("artifact.gsym")?;
        let mut writer = population.into_writer()?;
        io::copy(&mut source, &mut writer)?;
        let entry = writer.publish()?.into_entry();
        drop(entry);
    }
    PopulationOutcome::Suppressed(failure) => {
        eprintln!("retry after {:?}", failure.expires_at());
    }
    PopulationOutcome::Busy => eprintln!("another population is active"),
}

pub fn cached_failure( &self, build_id: &BuildId, ) -> Result<Option<CachedFailure>>

Returns an unexpired cached failure.

Expired or malformed records are ignored. Population or a scrub pass removes them while holding the entry lock.

Errors

Returns an error for filesystem failures or an untrusted cache entry.

Trait Implementations

impl Debug for Cache

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.