Trait AssetReader 

pub trait AssetReader:
    Send
    + Sync
    + 'static {
    // Required methods
    fn read<'a>(
        &'a self,
        path: &'a Path,
        required_features: ReaderRequiredFeatures,
    ) -> impl AssetReaderFuture<Value: Reader + 'a>;
    fn read_meta<'a>(
        &'a self,
        path: &'a Path,
    ) -> impl AssetReaderFuture<Value: Reader + 'a>;
    fn read_directory<'a>(
        &'a self,
        path: &'a Path,
    ) -> impl ConditionalSendFuture<Output = Result<Box<PathStream>, AssetReaderError>>;
    fn is_directory<'a>(
        &'a self,
        path: &'a Path,
    ) -> impl ConditionalSendFuture<Output = Result<bool, AssetReaderError>>;

    // Provided method
    fn read_meta_bytes<'a>(
        &'a self,
        path: &'a Path,
    ) -> impl ConditionalSendFuture<Output = Result<Vec<u8>, AssetReaderError>> { ... }
}

Performs read operations on an asset storage. AssetReader exposes a “virtual filesystem” API, where asset bytes and asset metadata bytes are both stored and accessible for a given path. This trait is not object safe, if needed use a dyn ErasedAssetReader instead.

This trait defines asset-agnostic mechanisms to read bytes from a storage system. For the per-asset-type saving/loading logic, see AssetSaver and AssetLoader.

For a complementary version of this trait that can write assets to storage, see AssetWriter.

Required Methods

fn read<'a>( &'a self, path: &'a Path, required_features: ReaderRequiredFeatures, ) -> impl AssetReaderFuture<Value: Reader + 'a>

Returns a future to load the full file data at the provided path.

Required Features

The required_features allows the caller to request that the returned reader implements certain features, and consequently allows this trait to decide how to react to that request. Namely, the implementor could:

• Return an error if the caller requests an unsupported feature. This can give a nicer error message to make it clear that the caller (e.g., an asset loader) can’t be used with this reader.
• Use a different implementation of a reader to ensure support of a feature (e.g., reading the entire asset into memory and then providing that buffer as a reader).
• Ignore the request and provide the regular reader anyway. Practically, if the caller never actually uses the feature, it’s fine to continue using the reader. However the caller requesting a feature is a strong signal that they will use the given feature.

The recommendation is to simply return an error for unsupported features. Callers can generally work around this and have more understanding of their constraints. For example, an asset loader may know that it will only load “small” assets, so reading the entire asset into memory won’t consume too much memory, and so it can use the regular AsyncRead API to read the whole asset into memory. If this were done by this trait, the loader may accidentally be allocating too much memory for a large asset without knowing it!

Note for implementors

The preferred style for implementing this method is an async fn returning an opaque type.

impl AssetReader for MyReader {
    async fn read<'a>(&'a self, path: &'a Path, required_features: ReaderRequiredFeatures) -> Result<impl Reader + 'a, AssetReaderError> {
        // ...
    }
}

fn read_meta<'a>( &'a self, path: &'a Path, ) -> impl AssetReaderFuture<Value: Reader + 'a>

Returns a future to load the full file data at the provided path.

fn read_directory<'a>( &'a self, path: &'a Path, ) -> impl ConditionalSendFuture<Output = Result<Box<PathStream>, AssetReaderError>>

Returns an iterator of directory entry names at the provided path.

fn is_directory<'a>( &'a self, path: &'a Path, ) -> impl ConditionalSendFuture<Output = Result<bool, AssetReaderError>>

Returns true if the provided path points to a directory.

Provided Methods

fn read_meta_bytes<'a>( &'a self, path: &'a Path, ) -> impl ConditionalSendFuture<Output = Result<Vec<u8>, AssetReaderError>>

Reads asset metadata bytes at the given path into a Vec<u8>. This is a convenience function that wraps AssetReader::read_meta by default.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl AssetReader for FileAssetReader

impl AssetReader for MemoryAssetReader