Struct assets_manager::OnceInitCell

pub struct OnceInitCell<U, T> { /* private fields */ }

Available on crate feature utils only.

A thread-safe cell which can be written to only once.

This is just like a OnceCell, but it also has data when uninitialized.

This is useful if an asset needs a context to be fully initialized. The “raw” version of the asset can be stored as the Uninitialized part of the cell, and further loading can be done later when additional context is available.

The type also provides easy integration with hot-reloading: when the “uninitialized” value is reloaded, so is the cell, and the initialization is re-run.

Example

use assets_manager::{asset::Png, AnyCache, BoxedError, OnceInitCell};
struct GpuCtx(/* ... */);
struct Texture(/* ... */);

impl GpuCtx {
    /// Loads a texture to GPU from an image
    fn load_texture(&self, img: &image::DynamicImage) -> Texture {
        /* ... */
    }

    /// Does something with a GPU texture
    fn use_texture(&self, texture: &Texture) {
        /* ... */
    }

    /// Loads a texture from an image the cache and uses it.
    fn load_and_use_texture(&self, cache: AnyCache, id: &str) -> Result<(), BoxedError> {
        // Load the cached texture or the source PNG image.
        let img = cache.load::<OnceInitCell<Png, Texture>>(id)?.read();

        // If the image has not been uploaded to GPU yet or if it has been
        // reloaded, upload it.
        let texture = img.get_or_init(|img| self.load_texture(&img.0));

        self.use_texture(texture);

        Ok(())
    }
}

Implementations

impl<U, T> OnceInitCell<U, T>

pub const fn new(value: U) -> Self

Creates a new uninitialized cell.

pub const fn with_value(value: T) -> Self

Creates a new initialized cell.

pub fn get(&self) -> Option<&T>

Gets the reference to the underlying value.

Returns None if the cell is empty, or being initialized. This method never blocks.

pub fn get_or_init(&self, f: impl FnOnce(&mut U) -> T) -> &T

Gets the contents of the cell, initializing it with f if the cell was uninitialized.

See get_or_try_init for more details.

pub fn get_or_try_init<E>( &self, f: impl FnOnce(&mut U) -> Result<T, E>, ) -> Result<&T, E>

Gets the contents of the cell, initializing it with f if the cell was uninitialized. If the cell was uninitialized and f failed, an error is returned.

Panics

If f panics, the panic is propagated to the caller, and the cell remains uninitialized.

It is an error to reentrantly initialize the cell from f. The exact outcome is unspecified.

Trait Implementations

impl<U: Compound, T: Storable> Compound for OnceInitCell<Option<U>, T>

fn load(cache: AnyCache<'_>, id: &SharedString) -> Result<Self, BoxedError>

Loads an asset from the cache.

const HOT_RELOADED: bool = U::HOT_RELOADED

If false, disable hot-reloading for assets of this type (true by default). This avoids having to lock the asset to read it (ie it makes Handle::read a noop)

impl<U: Compound, T: Storable> Compound for OnceInitCell<U, T>

fn load(cache: AnyCache<'_>, id: &SharedString) -> Result<Self, BoxedError>

Loads an asset from the cache.

const HOT_RELOADED: bool = U::HOT_RELOADED

If false, disable hot-reloading for assets of this type (true by default). This avoids having to lock the asset to read it (ie it makes Handle::read a noop)

impl<U, T: Debug> Debug for OnceInitCell<U, T>

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

Formats the value using the given formatter.

impl<U, T> Default for OnceInitCell<U, T>

where U: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<U: DirLoadable, T: Storable> DirLoadable for OnceInitCell<Option<U>, T>

fn select_ids( cache: AnyCache<'_>, id: &SharedString, ) -> Result<Vec<SharedString>>

Returns the ids of the assets contained in the directory given by id.

fn sub_directories( cache: AnyCache<'_>, id: &SharedString, f: impl FnMut(&str), ) -> Result<()>

Executes the given closure for each id of a child directory of the given directory. The default implementation reads the cache’s source.

impl<U: DirLoadable, T: Storable> DirLoadable for OnceInitCell<U, T>

fn select_ids( cache: AnyCache<'_>, id: &SharedString, ) -> Result<Vec<SharedString>>

Returns the ids of the assets contained in the directory given by id.

fn sub_directories( cache: AnyCache<'_>, id: &SharedString, f: impl FnMut(&str), ) -> Result<()>

Executes the given closure for each id of a child directory of the given directory. The default implementation reads the cache’s source.

impl<U, T> Drop for OnceInitCell<U, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<U, T> RefUnwindSafe for OnceInitCell<U, T>

where T: UnwindSafe + RefUnwindSafe, U: UnwindSafe,

impl<U, T> Sync for OnceInitCell<U, T>

where T: Send + Sync, U: Send,

impl<U, T> UnwindSafe for OnceInitCell<U, T>

where T: UnwindSafe, U: UnwindSafe,