Struct assets_manager::Handle

pub struct Handle<T> { /* private fields */ }

A handle on an asset.

Such a handle can be used to get access to an asset of type T. It is generally obtained by call AssetCache::load and its variants.

If feature hot-reloading is used, this structure wraps a RwLock, so assets can be written to be reloaded. As such, any number of read guard can exist at the same time, but none can exist while reloading an asset (when calling AssetCache::hot_reload).

You can use thus structure to store a reference to an asset. However it is generally easier to work with 'static data. For more information, see top-level documentation.

Implementations

impl<T> Handle<T>

pub fn read(&self) -> AssetReadGuard<'_, T>

Locks the pointed asset for reading.

If T implements NotHotReloaded or if hot-reloading is disabled, no reloading can occur so there is no actual lock. In these cases, calling this function is cheap and does not involve synchronisation.

Returns a RAII guard which will release the lock once dropped.

pub fn id(&self) -> &SharedString

Returns the id of the asset.

pub fn as_untyped(&self) -> &UntypedHandle

where T: Storable,

Returns an untyped version of the handle.

pub fn reload_watcher(&self) -> ReloadWatcher<'_>

Returns a ReloadWatcher that can be used to check whether this asset was reloaded.

Example

use assets_manager::{Asset, AssetCache, ReloadWatcher};

let cache = AssetCache::new("assets")?;
let asset = cache.load::<String>("common.some_text")?;
let mut watcher = asset.reload_watcher();

// The handle has just been created, so `reloaded` returns false
assert!(!watcher.reloaded());

loop {
    cache.hot_reload();

    if watcher.reloaded() {
        println!("The asset was reloaded !")
    }

    // Calling `reloaded` once more returns false: the asset has not
    // been reloaded since last call to `reloaded`
    assert!(!watcher.reloaded());
}

pub fn last_reload_id(&self) -> ReloadId

Returns the last ReloadId associated with this asset.

It is only meaningful when compared to other ReloadIds returned by the same handle or to ReloadId::NEVER.

pub fn reloaded_global(&self) -> bool

Returns true if the asset has been reloaded since last call to this method with any handle on this asset.

Note that this method and reload_watcher are totally independant, and the result of the two functions do not depend on whether the other was called.

impl<T> Handle<T>

where T: NotHotReloaded,

pub fn get(&self) -> &T

Returns a reference to the underlying asset.

This method only works if hot-reloading is disabled for the given type.

impl<T> Handle<T>

where T: Copy,

pub fn copied(&self) -> T

Returns a copy of the inner asset.

This is functionnally equivalent to cloned, but it ensures that no expensive operation is used (eg if a type is refactored).

impl<T> Handle<T>

where T: Clone,

pub fn cloned(&self) -> T

Returns a clone of the inner asset.

Trait Implementations

impl<T> Debug for Handle<T>

where T: Debug,

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

Formats the value using the given formatter.

impl<T> Serialize for Handle<T>

where T: Serialize,

Available on crate feature serde only.

fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.