Module assets 

Background loading and a cache of decoded sounds. Requires assets.

AudioCache retains shared decoded sounds within a byte budget. Accessing a sound makes it most recently used. Admission evicts the least recently used sounds whose only reference is the cache’s; a caller, pending load result or mixer voice holding an Arc<Audio> pins that entry. Failed admission leaves existing entries intact. Sharing one Arc under multiple keys pins those entries conservatively until the other references disappear. Weak references also pin an entry, so a concurrent weak upgrade cannot race eviction.

The budget accounts for sample and channel vector capacities, the Audio and entry structs, and key/metadata string storage. It excludes allocator bookkeeping, collection spare capacity and metadata tree nodes. It is a retained-data budget, not a bound on process memory: encoded inputs, decoder scratch space and sounds held outside the cache have separate lifetimes.

On native targets, Loader owns one worker and one cache. File reads and decoding happen on that worker. Requests use a bounded queue; queue saturation returns ErrorCode::LimitExceeded. A successful decode is returned even when it cannot be cached. Keys identify immutable assets: a cache hit ignores newly supplied bytes or changes to a file. Use a new key or a new loader when content changes. Relative paths are made absolute at submission using std::path::absolute, without resolving symlinks. Paths that remain differently spelled after that conversion are distinct keys.

All cache and loader operations belong on a game’s control/loading thread, never in the audio callback. Pass the resulting Arc<Audio> to the mixer. The cache works on WebAssembly; the thread-based loader is only available on native targets.

use audiobox::assets::{Loader, LoaderConfig};
let loader = Loader::new(LoaderConfig::default())?;
let mut loading = loader.load_bytes("jump", bytes)?;
// Once per game frame, on the control thread:
if let Some(result) = loading.try_take() {
    let sound = result?; // Arc<Audio>, ready for MixerHandle::play.
}

Structs

AudioCache

A least-recently-used cache that skips entries with external references. See the module documentation for budget accounting and thread responsibilities.

LoadHandle

A one-shot result of a queued file read/decode. Dropping it does not cancel work. A completed result pins its cached sound until taken or dropped.

Loader

One background worker with a bounded request queue and a private AudioCache.

LoaderConfig

Bounds shared by every request to a Loader.

Enums

AssetKey

Names and file paths occupy separate namespaces. Paths are compared literally.