Struct assets_manager::AssetCache

pub struct AssetCache { /* fields omitted */ }

The main structure of this crate, used to cache assets.

It uses interior mutability, so assets can be added in the cache without requiring a mutable reference, but one is required to remove an asset.

Within the cache, assets are identified with their type and a string. This string is constructed from the asset path, remplacing / by . and removing the extension.

Example

use assets_manager::{Asset, AssetCache, loader};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Point {
    x: i32,
    y: i32,
}

impl Asset for Point {
    const EXT: &'static str = "ron";
    type Loader = loader::RonLoader;
}

// Create a cache
let cache = AssetCache::new("assets")?;

// Get an asset from the file `assets/common/position.ron`
let point_lock = cache.load::<Point>("common.position")?;

// Read it
let point = point_lock.read();
println!("Loaded position: {:?}", point);

// Release the lock
drop(point);

// Use hot-reloading
loop {
    println!("Position: {:?}", point_lock.read());
    cache.hot_reload();
}

Methods

impl AssetCache

pub fn new<P: AsRef<Path>>(path: P) -> Result<AssetCache, Error>

Creates a new cache.

Assets will be searched in the directory given by path. Symbolic links will be followed.

Errors

An error will be returned if path is not valid readable directory.

pub fn path(&self) -> &Path

Gets the path of the cache's root.

The path is currently given as absolute, but this may change in the future.

pub fn load<A: Asset>(&self, id: &str) -> Result<AssetRefLock<A>, AssetError>

Loads an asset.

If the asset is not found in the cache, it is loaded from the filesystem.

Errors

Errors can occur in several cases :

• The asset could not be loaded from the filesystem
• Loaded data could not not be converted properly

pub fn load_cached<A: Asset>(&self, id: &str) -> Option<AssetRefLock<A>>

Loads an asset from the cache.

This function does not attempt to load the asset from the filesystem if it is not found in the cache.

pub fn load_expect<A: Asset>(&self, id: &str) -> AssetRefLock<A>

Loads an asset given an id, from the filesystem or the cache.

Panics

Panics if an error happens while loading the asset (see load).

pub fn force_reload<A: Asset>(
    &self,
    id: &str
) -> Result<AssetRefLock<A>, AssetError>

Reloads an asset from the filesystem.

It does not matter whether the asset has been loaded yet.

Note: this function requires a write lock on the asset, and will block until one is aquired, ie no read lock can exist at the same time. This means that you must not call this method if you have an AssetRef on the same asset, or it may cause a deadlock.

Errors

Error cases are the same as load.

If an error occurs, the asset is left unmodified.

pub fn remove<A: Asset>(&mut self, id: &str)

Remove an asset from the cache.

The removed asset matches both the id and the type parameter.

pub fn take<A: Asset>(&mut self, id: &str) -> Option<A>

Take ownership on an asset.

The corresponding asset is removed from the cache.

pub fn clear(&mut self)

Clears the cache.

pub fn hot_reload(&self) -> Result<(), Error>

This is supported on feature="hot-reloading" only.

Reloads changed assets.

The first time this function is called, the hot-reloading is started. Next calls to this function update assets if the cache if their related file have changed since the last call to this function.

This function is typically called within a loop.

If an error occurs while reloading an asset, a warning will be logged and the asset will be left unchanged.

This function will block the current thread until all changed assets are reloaded, but it does not perform any I/O. However, it will need to lock some assets for writing, so you must not have any AssetRef from the given AssetCache, or you might experience deadlocks. You are free to keep AssetRefLocks, though.

Errors

This function will return an error it it failed to start hot-reloading.

pub fn stop_hot_reloading(&self)

This is supported on feature="hot-reloading" only.

Stops the hot-reloading.

If hot_reload has not been called on this AssetCache, this method has no effect. Hot-reloading will restart when hot_reload is called again.

Trait Implementations

impl Debug for AssetCache

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

Formats the value using the given formatter.