Skip to main content

Module cache

eryx

Module cache 

Source
Expand description

Component caching for faster sandbox creation.

This module provides a two-tier caching system to minimize sandbox creation overhead:

§Two-Tier Cache Architecture

§Tier 1: InstancePreCache (in-memory)

Caches SandboxPre<ExecutorState> - the fully linked, pre-instantiated component. This is the fastest tier, returning a cached instance in ~0ms (just a Clone).

  • Key: CacheKey (extension hash + version info)
  • Lifetime: Process duration
  • Use: Automatic for embedded runtime and native extensions

§Tier 2: ComponentCache (disk or memory)

Caches pre-compiled .cwasm bytes for persistence across process restarts.

§Cache Flow

On sandbox creation:

  1. Check Tier 1 (InstancePreCache) → if hit, return immediately (~0ms)
  2. Check Tier 2 (ComponentCache) → if hit, create SandboxPre, store in Tier 1 (~10ms)
  3. Cold path → compile, store in Tier 2, create SandboxPre, store in Tier 1 (~500ms)

This means the second sandbox with the same configuration is ~10-100x faster.

§Example

ⓘ
use eryx::{Sandbox, cache::FilesystemCache};

let cache = FilesystemCache::new("/tmp/eryx-cache")?;

// First call: ~1000ms (link + compile + cache)
let sandbox1 = Sandbox::builder()
    .with_native_extension("numpy/core/*.so", bytes)
    .with_cache(cache.clone())
    .build()?;

// Second call: ~10ms (cache hit)
let sandbox2 = Sandbox::builder()
    .with_native_extension("numpy/core/*.so", bytes)
    .with_cache(cache.clone())
    .build()?;

Structs§

CacheKey
Cache key for identifying pre-compiled components.
FilesystemCache
Filesystem-based component cache.
InMemoryCache
In-memory component cache.
InstancePreCache
Global in-memory cache for pre-instantiated WASM components.
NoCache
A cache implementation that never caches anything.

Enums§

CacheError
Error type for cache operations.

Traits§

ComponentCache
Trait for component caching implementations.