Struct ArtifactCache 

pub struct ArtifactCache { /* private fields */ }

Global artifact cache

Provides persistent caching of compiled dynamic libraries using SHA256 content-addressed storage. The cache is shared across all REPL sessions and persists across restarts.

Cache Key Algorithm (ODD-0026)

SHA256(
    source_code +
    dependencies +
    optimization_level +
    source_map_config
)

Directory Structure

~/.cache/oxur/artifacts/
├── index.json                 # Cache index
├── <sha256-1>/
│   ├── lib.so                 # Compiled artifact (Linux)
│   └── metadata.json          # Entry metadata
├── <sha256-2>/
│   ├── lib.dylib              # Compiled artifact (macOS)
│   └── metadata.json
└── ...

Examples

use oxur_repl::cache::ArtifactCache;

let mut cache = ArtifactCache::new()?;

// Generate cache key from source
let key = cache.generate_key("(+ 1 2)", &[], 0, "default");

// Check if artifact exists
if let Some(path) = cache.get(&key)? {
    println!("Cache hit: {:?}", path);
} else {
    println!("Cache miss, need to compile");
}

Implementations

impl ArtifactCache

pub fn new() -> Result<Self, CacheError>

Create or open the global artifact cache

Uses platform-specific cache directory:

• Linux: ~/.cache/oxur/artifacts/
• macOS: ~/Library/Caches/oxur/artifacts/
• Windows: %LOCALAPPDATA%\oxur\artifacts\

Can be overridden with OXUR_CACHE_DIR environment variable.

Errors

Returns error if cache directory cannot be created or index cannot be loaded

pub fn with_directory(cache_dir: impl AsRef<Path>) -> Result<Self, CacheError>

Create a new artifact cache with a specific directory

This is primarily useful for testing with isolated cache directories.

Arguments

• cache_dir - Path to use as the cache directory

Errors

Returns error if cache directory cannot be created or index cannot be loaded

pub fn generate_key( &self, source: impl AsRef<str>, dependencies: &[(&str, &str)], opt_level: u8, source_map_config: impl AsRef<str>, ) -> String

Generate cache key from compilation inputs

Arguments

• source - Source code
• dependencies - List of dependency names and versions
• opt_level - Optimization level (0-3)
• source_map_config - Source map configuration identifier

Returns

SHA256 hash as hex string

pub fn get(&self, key: impl AsRef<str>) -> Result<Option<PathBuf>, CacheError>

Get cached artifact by key

Returns the path to the cached dynamic library if it exists.

Arguments

• key - SHA256 cache key

Returns

Some(path) if artifact exists, None otherwise

pub fn insert( &mut self, key: impl AsRef<str>, artifact_path: &Path, ) -> Result<PathBuf, CacheError>

Insert artifact into cache

Copies the artifact to cache directory and updates the index.

Arguments

• key - SHA256 cache key
• artifact_path - Path to compiled artifact

Errors

Returns error if artifact cannot be copied or index cannot be saved

pub fn clear(&mut self) -> Result<(), CacheError>

Clear all cached artifacts

Removes all artifacts from cache directory and resets index.

pub fn stats(&self) -> (usize, u64)

Get cache statistics

Returns (entry_count, total_size_bytes)

pub fn detailed_stats(&self) -> CacheStats

Get detailed cache statistics

Returns comprehensive statistics including oldest/newest entries

pub fn keys(&self) -> Vec<String>

List all cache keys

pub fn evict_lru( &mut self, max_size_bytes: Option<u64>, ) -> Result<usize, CacheError>

Evict least recently used cache entries

Removes oldest entries until total cache size is below the limit. Default limit is 1GB. Can be configured via OXUR_CACHE_MAX_SIZE_MB environment variable.

Arguments

• max_size_bytes - Maximum allowed cache size in bytes. If None, uses default (1GB)

Returns

Number of entries evicted

Examples

use oxur_repl::cache::ArtifactCache;

let mut cache = ArtifactCache::new()?;
let evicted = cache.evict_lru(Some(100 * 1024 * 1024))?; // Limit to 100MB
println!("Evicted {} cache entries", evicted);

pub fn total_size_bytes(&self) -> u64

Get total cache size in bytes

pub fn check_and_evict(&mut self) -> Result<usize, CacheError>

Check if cache is over size limit and evict if needed

This is automatically called after insert() operations. Can also be called manually for periodic cleanup.

Returns

Number of entries evicted

Trait Implementations

impl Clone for ArtifactCache

fn clone(&self) -> ArtifactCache

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ArtifactCache

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

Formats the value using the given formatter.