Struct zaplib::universal_file::UniversalFile

pub struct UniversalFile(_);

A file handle that abstracts over the different ways we have to deal with different kinds of files (local files, file URLs, dragged in files).

It tries to somewhat follow the std::fs::File API, but there are some major differences:

• For the WebAssembly target, opening a file will read the entire file in memory synchronously, over HTTP(S). This is quite different from the native behavior. This is required if we never want std::io::Seek::seek to fail. TODO(JP): We should consider different behaviors here – potentially configurable by the user – such as completely disallowing seeking, or seeking into a buffer with a certain size, or even using HTTP Range Requests when available to fetch the data starting at a seek point (when not buffered already). This can somewhat mirror std::fs::OpenOptions. We can take some inspiration from https://github.com/cruise-automation/webviz/blob/4dcd47d/packages/webviz-core/src/util/CachedFilelike.js and https://github.com/cruise-automation/webviz/blob/4dcd47d/packages/webviz-core/src/dataProviders/BrowserHttpReader.js. Even just an option to defer loading until the first read would be useful, so you can open a file on the main thread and pass it to another thread for processing (without having to create multiple functions for processing e.g. handles from crate::AppOpenFilesEvent differently).
• UniversalFile::open_url exists, which is not available in the regular std::fs::File API. This matches the behavior of the WebAssembly URL loading described above, but works on both WebAssembly and native targets.
• You can use std::clone::Clone::clone to get a truly new handle, e.g. with its own std::io::Seek state. Also note that it’s not a try_clone – it will always succeed. This means that if you clone a handle to a file that doesn’t exist anymore, then you’ll get that error on the next read, not while cloning.
• Currently it only supports reading, not writing. This might change in the future, but requires some thinking about how that should work in WebAssembly.

Note that you typically want to load files in a thread. Even on native targets the file system can be slow, e.g. when the user has mounted a remote file system, so you want to avoid blocking the UI thread when possible.

TODO(JP): File handles in WebAssembly ([UniversalFileInner::WasmFile]) can’t be moved used in threads that were spawned before the file handle became available. It would be nice to figure out some way around this, or to prevent (at compile time) from using these file handles in older threads.

Implementations

impl UniversalFile

pub fn open(path: &str) -> Result<Self>

Open a local/relative file. On the web target this will block until the entire file is loaded.

Will return an error if the file does not exist.

This is mostly intended for reading application files. User files should typically be obtained through an crate::AppOpenFilesEvent.

On the web target, this will load files relative to the base path, which you can override using the tag.

pub fn open_url(url: &str) -> Result<Self>

Open an absolute URL. This will always block until the entire file is loaded.

Will return an error if the file does not exist.

Trait Implementations

impl Clone for UniversalFile

fn clone(&self) -> Self

Resets the cursor position, as opposed to std::fs::File.

If the underlying file doesn’t exist anymore, you will get an error during the next read or seek call.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UniversalFile

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

Formats the value using the given formatter.

impl Read for UniversalFile

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Adapted from std::io::Cursor.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adapter which will read at most limit bytes from it.

impl Seek for UniversalFile

fn seek(&mut self, style: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬 This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

Returns the current seek position from the start of the stream.

impl ReadSeek for UniversalFile