Module async_vfs 

Available on crate feature async only.

Asynchronous virtual file system traits.

These traits are similar to the ones in the vfs module, but they use asynchronous I/O operations, and return Futures resolving to Results instead of directly returning Results, in line with Rust’s async programming model.

These traits require the async feature to be enabled.

They are designed to be used with async runtimes like Tokio or async-std.

You should refer to the documentation of the vfs module for more details on the individual methods, as the async versions have the same semantics, just with async I/O.

An important difference between the VfsAsync traits and their synchronous counterparts is that the methods take owned paths instead of references. This is because the async methods typically need to move the path into the future, and references would not be valid for the entire duration of the future.

Tool specific extensions of the async VFS traits

Similarly to the synchronous VFS traits, there are also tool-specific extensions of the async VFS traits, which are required to use certain tools with a specific VfsAsync implementation.

We list them here for convenience, but you should refer to the documentation of the individual tools for more details.

AtomicDir<T>

To use the AtomicDir<T> wrapper type with your async VFS implementation, the VFS type itself must implement the VfsSupportsTemporaryDirectories trait. See its documentation for more details.

Images

To allow reading and writing image files using the types and traits from the image module, the following traits need to be implemented for your async VFS type YourVfsType:

• impl<T: ImgFormat> ReadImageFromAsync<T> for YourVfsType to satisfy the bound T: ReadFromAsync<'vfs, YourVfsType>
• impl<'a> WriteImageToAsync<'a> for YourVfsType to satisfy the bound T: WriteToAsync<'a, YourVfsType>
• impl<'a> WriteImageToAsyncRef<'a, YourVfsType> for YourVfsType to satisfy the bound T: WriteToAsyncRef<'a, YourVfsType>

These impls are required because the image encoding and decoding operations are CPU-bound and blocking, and thus cannot be implemented in a generic way for all async VFS implementations. They need to be implemented specifically for each async VFS type.

You can see the implementations for the TokioFsVfs VFS, which use [tokio::task::spawn_blocking] to offload the blocking operations to a separate thread pool.

Your async VFS implementation might use a different async runtime, and thus might need to use a different method to offload blocking operations, but that is the ideal approach to take.

You can of course not implement these impls, but then you will not be able to use the image encoding and decoding operations with your async VFS implementation.

Traits

VfsAsync

An asynchronous virtual file system.

VfsAsyncExt

Extension trait for VfsAsync that provides additional convenience methods.

VfsAsyncWithSeekRead

Marks that the RFile type of this VfsAsync also implements AsyncSeek, allowing it to be used in contexts that require seeking, such as image decoding.

VfsAsyncWithSeekWrite

Marks that the WFile type of this WriteSupportingVfsAsync also implements AsyncSeek, allowing it to be used in contexts that require seeking.

WriteSupportingVfsAsync

A virtual file system that supports writing operations.

WriteSupportingVfsAsyncExt

Extension trait for WriteSupportingVfsAsync that provides additional convenience methods.