distill_loader/

storage.rs

use std::{
    error::Error,
    path::PathBuf,
    sync::{
        atomic::{AtomicU64, Ordering},
        Arc,
    },
};

use crossbeam_channel::Sender;
use dashmap::DashMap;
use distill_core::{AssetMetadata, AssetRef, AssetTypeId, AssetUuid};

/// Loading ID allocated by [`Loader`](crate::loader::Loader) to track loading of a particular asset
/// or an indirect reference to an asset.
#[derive(Copy, Clone, PartialEq, Eq, Debug, Hash)]
pub struct LoadHandle(pub u64);

impl LoadHandle {
    /// Returns true if the handle needs to be resolved through the [`IndirectionTable`] before use.
    /// An "indirect" LoadHandle represents a load operation for an identifier that is late-bound,
    /// meaning the identifier may change which [`AssetUuid`] it resolves to.
    /// An example of an indirect LoadHandle would be one that loads by filesystem path.
    /// The specific asset at a path may change as files change, move or are deleted, while a direct
    /// LoadHandle (one that addresses by AssetUuid) is guaranteed to refer to an AssetUuid for its
    /// whole lifetime.
    pub fn is_indirect(&self) -> bool {
        (self.0 & (1 << 63)) == 1 << 63
    }

    pub(crate) fn set_indirect(self) -> LoadHandle {
        LoadHandle(self.0 | (1 << 63))
    }
}

pub(crate) enum HandleOp {
    Error(LoadHandle, u32, Box<dyn Error + Send>),
    Complete(LoadHandle, u32),
    Drop(LoadHandle, u32),
}

/// Type that allows the downstream asset storage implementation to signal that an asset update
/// operation has completed. See [`AssetStorage::update_asset`].
pub struct AssetLoadOp {
    sender: Option<Sender<HandleOp>>,
    handle: LoadHandle,
    version: u32,
}

impl AssetLoadOp {
    pub(crate) fn new(sender: Sender<HandleOp>, handle: LoadHandle, version: u32) -> Self {
        Self {
            sender: Some(sender),
            handle,
            version,
        }
    }

    /// Returns the `LoadHandle` associated with the load operation
    pub fn load_handle(&self) -> LoadHandle {
        self.handle
    }

    /// Signals that this load operation has completed succesfully.
    pub fn complete(mut self) {
        let _ = self
            .sender
            .as_ref()
            .unwrap()
            .send(HandleOp::Complete(self.handle, self.version));
        self.sender = None;
    }

    /// Signals that this load operation has completed with an error.
    pub fn error<E: Error + 'static + Send>(mut self, error: E) {
        let _ = self.sender.as_ref().unwrap().send(HandleOp::Error(
            self.handle,
            self.version,
            Box::new(error),
        ));
        self.sender = None;
    }
}

impl Drop for AssetLoadOp {
    fn drop(&mut self) {
        if let Some(ref sender) = self.sender {
            let _ = sender.send(HandleOp::Drop(self.handle, self.version));
        }
    }
}

/// Storage for all assets of all asset types.
///
/// Consumers are expected to provide the implementation for this, as this is the bridge between
/// [`Loader`](crate::loader::Loader) and the application.
pub trait AssetStorage {
    /// Updates the backing data of an asset.
    ///
    /// An example usage of this is when a texture such as "player.png" changes while the
    /// application is running. The asset ID is the same, but the underlying pixel data can differ.
    ///
    /// # Parameters
    ///
    /// * `loader`: Loader implementation calling this function.
    /// * `asset_type_id`: UUID of the asset type.
    /// * `data`: The updated asset byte data.
    /// * `load_handle`: ID allocated by [`Loader`](crate::loader::Loader) to track loading of a particular asset.
    /// * `load_op`: Allows the loading implementation to signal when loading is done / errors.
    /// * `version`: Runtime load version of this asset, increments each time the asset is updated.
    fn update_asset(
        &self,
        loader_info: &dyn LoaderInfoProvider,
        asset_type_id: &AssetTypeId,
        data: Vec<u8>,
        load_handle: LoadHandle,
        load_op: AssetLoadOp,
        version: u32,
    ) -> Result<(), Box<dyn Error + Send + 'static>>;

    /// Commits the specified asset version as loaded and ready to use.
    ///
    /// # Parameters
    ///
    /// * `asset_type_id`: UUID of the asset type.
    /// * `load_handle`: ID allocated by [`Loader`](crate::loader::Loader) to track loading of a particular asset.
    /// * `version`: Runtime load version of this asset, increments each time the asset is updated.
    fn commit_asset_version(&self, asset_type: &AssetTypeId, load_handle: LoadHandle, version: u32);

    /// Frees the asset identified by the load handle.
    ///
    /// # Parameters
    ///
    /// * `asset_type_id`: UUID of the asset type.
    /// * `load_handle`: ID allocated by [`Loader`](crate::loader::Loader) to track loading of a particular asset.
    fn free(&self, asset_type_id: &AssetTypeId, load_handle: LoadHandle, version: u32);
}

/// Asset loading status.
#[derive(Debug)]
pub enum LoadStatus {
    /// There is no request for the asset to be loaded.
    NotRequested,
    /// The asset is an indirect reference which has not been resolved yet.
    Unresolved,
    /// The asset is being loaded.
    Loading,
    /// The asset is loaded.
    Loaded,
    /// The asset is being unloaded.
    Unloading,
    /// The asset does not exist.
    DoesNotExist,
    /// There was an error during loading / unloading of the asset.
    Error(Box<dyn Error>),
}

/// Information about an asset load operation.
///
/// **Note:** The information is true at the time the `LoadInfo` is retrieved. The actual number of
/// references may change.
#[derive(Debug)]
pub struct LoadInfo {
    /// UUID of the asset.
    pub asset_id: AssetUuid,
    /// Number of references to the asset.
    pub refs: u32,
    /// Path to asset's source file. Not guaranteed to always be available.
    pub path: Option<String>,
    /// Name of asset's source file. Not guaranteed to always be available.
    pub file_name: Option<String>,
    /// Asset name. Not guaranteed to always be available.
    pub asset_name: Option<String>,
}

/// Provides information about mappings between `AssetUuid` and `LoadHandle`.
/// Intended to be used for `Handle` serde.
pub trait LoaderInfoProvider: Send + Sync {
    /// Returns the load handle for the asset with the given UUID, if present.
    ///
    /// This will only return `Some(..)` if there has been a previous call to [`crate::loader::Loader::add_ref`].
    ///
    /// # Parameters
    ///
    /// * `id`: UUID of the asset.
    fn get_load_handle(&self, asset_ref: &AssetRef) -> Option<LoadHandle>;

    /// Returns the AssetUUID for the given LoadHandle, if present.
    ///
    /// # Parameters
    ///
    /// * `load_handle`: ID allocated by [`Loader`](crate::loader::Loader) to track loading of the asset.
    fn get_asset_id(&self, load: LoadHandle) -> Option<AssetUuid>;
}

/// Allocates LoadHandles for [`Loader`](crate::loader::Loader) implementations.
pub trait HandleAllocator: Send + Sync + 'static {
    /// Allocates a [`LoadHandle`] for use by a [`crate::loader::Loader`].
    /// The same LoadHandle must not be returned by this function until it has been passed to `free`.
    /// NOTE: The most significant bit of the u64 in the LoadHandle returned MUST be unset,
    /// as it is reserved for indicating whether the handle is indirect or not.
    fn alloc(&self) -> LoadHandle;
    /// Frees a [`LoadHandle`], allowing the handle to be returned by a future `alloc` call.
    fn free(&self, handle: LoadHandle);
}

/// An implementation of [`HandleAllocator`] which uses an incrementing AtomicU64 internally to allocate LoadHandle IDs.
pub struct AtomicHandleAllocator(AtomicU64);
impl AtomicHandleAllocator {
    pub const fn new(starting_value: u64) -> Self {
        Self(AtomicU64::new(starting_value))
    }
}
impl Default for AtomicHandleAllocator {
    fn default() -> Self {
        Self(AtomicU64::new(1))
    }
}
impl HandleAllocator for AtomicHandleAllocator {
    fn alloc(&self) -> LoadHandle {
        LoadHandle(self.0.fetch_add(1, Ordering::Relaxed))
    }

    fn free(&self, _handle: LoadHandle) {}
}

impl HandleAllocator for &'static AtomicHandleAllocator {
    fn alloc(&self) -> LoadHandle {
        LoadHandle(self.0.fetch_add(1, Ordering::Relaxed))
    }

    fn free(&self, _handle: LoadHandle) {}
}

/// An indirect identifier that can be resolved to a specific [`AssetUuid`] by an [`IndirectionResolver`] impl.
#[derive(Clone, PartialEq, Eq, Debug, Hash)]
pub enum IndirectIdentifier {
    PathWithTagAndType(String, String, AssetTypeId),
    PathWithType(String, AssetTypeId),
    Path(String),
}
impl IndirectIdentifier {
    pub fn path(&self) -> &str {
        match self {
            IndirectIdentifier::PathWithTagAndType(path, _, _) => path.as_str(),
            IndirectIdentifier::PathWithType(path, _) => path.as_str(),
            IndirectIdentifier::Path(path) => path.as_str(),
        }
    }

    pub fn type_id(&self) -> Option<&AssetTypeId> {
        match self {
            IndirectIdentifier::PathWithTagAndType(_, _, ty) => Some(ty),
            IndirectIdentifier::PathWithType(_, ty) => Some(ty),
            IndirectIdentifier::Path(_) => None,
        }
    }
}
/// Resolves ambiguous [`IndirectIdentifier`]s to a single asset ID given a set of candidates.
pub trait IndirectionResolver {
    fn resolve(
        &self,
        id: &IndirectIdentifier,
        candidates: Vec<(PathBuf, Vec<AssetMetadata>)>,
    ) -> Option<AssetUuid>;
}

/// Default implementation of [`IndirectionResolver`] which resolves to the first asset in the list of candidates
/// of the appropriate type.
pub struct DefaultIndirectionResolver;
impl IndirectionResolver for DefaultIndirectionResolver {
    fn resolve(
        &self,
        id: &IndirectIdentifier,
        candidates: Vec<(PathBuf, Vec<AssetMetadata>)>,
    ) -> Option<AssetUuid> {
        let id_type = id.type_id();
        for candidate in candidates {
            for asset in candidate.1 {
                if let Some(artifact) = asset.artifact {
                    if id_type.is_none() || *id_type.unwrap() == artifact.type_id {
                        return Some(asset.id);
                    }
                }
            }
        }
        None
    }
}

/// Resolves indirect [`LoadHandle`]s. See [`LoadHandle::is_indirect`] for details.
#[derive(Clone)]
pub struct IndirectionTable(pub(crate) Arc<DashMap<LoadHandle, LoadHandle>>);
impl IndirectionTable {
    pub fn resolve(&self, indirect_handle: LoadHandle) -> Option<LoadHandle> {
        self.0.get(&indirect_handle).map(|l| *l)
    }
}