Struct TokioCompatFile

pub struct TokioCompatFile { /* private fields */ }

File that implements AsyncRead, AsyncBufRead, AsyncSeek and AsyncWrite, which is compatible with tokio::fs::File.

Implementations

impl TokioCompatFile

pub fn new(inner: File) -> Self

Create a TokioCompatFile using DEFAULT_BUFLEN.

pub fn with_capacity(inner: File, buffer_len: NonZeroUsize) -> Self

Create a TokioCompatFile.

• buffer_len - buffer len to be used in AsyncBufRead and the minimum length to read in AsyncRead.

pub fn into_inner(self) -> File

Return the inner File.

pub fn capacity(&self) -> usize

Return capacity of the internal buffer

Note that if there are pending requests, then the actual capacity might be more than the returned value.

pub fn reserve(&mut self, new_cap: usize)

Reserve the capacity of the internal buffer for at least cap bytes.

pub fn shrink_to(&mut self, new_cap: usize)

Shrink the capacity of the internal buffer to at most cap bytes.

pub async fn fill_buf(self: Pin<&mut Self>) -> Result<(), Error>

This function is a low-level call.

It needs to be paired with the consume method or TokioCompatFile::consume_and_return_buffer to function properly.

When calling this method, none of the contents will be “read” in the sense that later calling read may return the same contents.

As such, you must consume the corresponding bytes using the methods listed above.

An empty buffer returned indicates that the stream has reached EOF.

This function does not change the offset into the file.

pub fn consume_and_return_buffer(&mut self, amt: usize) -> Bytes

This can be used together with AsyncBufRead implementation for TokioCompatFile or TokioCompatFile::fill_buf or TokioCompatFile::read_into_buffer to avoid copying data.

Return empty Bytes on EOF.

This function does change the offset into the file.

pub fn poll_read_into_buffer( self: Pin<&mut Self>, cx: &mut Context<'_>, amt: NonZeroU32, ) -> Poll<Result<(), Error>>

• amt - Amount of data to read into the buffer.

This function is a low-level call.

It needs to be paired with the consume method or TokioCompatFile::consume_and_return_buffer to function properly.

When calling this method, none of the contents will be “read” in the sense that later calling read may return the same contents.

As such, you must consume the corresponding bytes using the methods listed above.

An empty buffer returned indicates that the stream has reached EOF.

This function does not change the offset into the file.

pub async fn read_into_buffer( self: Pin<&mut Self>, amt: NonZeroU32, ) -> Result<(), Error>

• amt - Amount of data to read into the buffer.

This function is a low-level call.

It needs to be paired with the consume method or TokioCompatFile::consume_and_return_buffer to function properly.

When calling this method, none of the contents will be “read” in the sense that later calling read may return the same contents.

As such, you must consume the corresponding bytes using the methods listed above.

An empty buffer returned indicates that the stream has reached EOF.

This function does not change the offset into the file.

pub fn as_mut_file(self: Pin<&mut Self>) -> &mut File

Return the inner file

Methods from Deref<Target = File>

pub async fn set_metadata(&mut self, metadata: MetaData) -> Result<(), Error>

Change the metadata of a file or a directory.

Cancel Safety

This function is cancel safe.

pub async fn set_len(&mut self, size: u64) -> Result<(), Error>

Truncates or extends the underlying file, updating the size of this file to become size.

If the size is less than the current file’s size, then the file will be shrunk.

If it is greater than the current file’s size, then the file will be extended to size and have all of the intermediate data filled in with 0s.

Cancel Safety

This function is cancel safe.

pub async fn sync_all(&mut self) -> Result<(), Error>

Attempts to sync all OS-internal metadata to disk.

This function will attempt to ensure that all in-core data reaches the filesystem before returning.

Precondition

Require extension fsync

You can check it with Sftp::support_fsync.

Cancel Safety

This function is cancel safe.

pub async fn set_permissions(&mut self, perm: Permissions) -> Result<(), Error>

Changes the permissions on the underlying file.

Cancel Safety

This function is cancel safe.

pub async fn metadata(&mut self) -> Result<MetaData, Error>

Queries metadata about the underlying file.

pub async fn read( &mut self, n: u32, buffer: BytesMut, ) -> Result<Option<BytesMut>, Error>

• n - number of bytes to read in

If the File has reached EOF or n == 0, then None is returned.

NOTE that the returned buffer might be smaller than n.

pub async fn write(&mut self, buf: &[u8]) -> Result<usize, Error>

Write data into the file.

NOTE that this API might only write part of the buf.

pub async fn write_vectorized( &mut self, bufs: &[IoSlice<'_>], ) -> Result<usize, Error>

Write from multiple buffer at once.

NOTE that this API might only write part of the buf.

pub async fn write_zero_copy( &mut self, bytes_slice: &[Bytes], ) -> Result<usize, Error>

Zero copy write.

NOTE that this API might only write part of the buf.

pub async fn read_all( &mut self, n: usize, buffer: BytesMut, ) -> Result<BytesMut, Error>

• n - number of bytes to read in.

If n == 0 or EOF is reached, then buffer is returned unchanged.

Cancel Safety

This function is cancel safe.

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

Write entire buf.

Cancel Safety

This function is cancel safe.

pub async fn write_all_vectorized( &mut self, bufs: &mut [IoSlice<'_>], ) -> Result<(), Error>

Write entire buf.

Cancel Safety

This function is cancel safe.

pub async fn write_all_zero_copy( &mut self, bufs: &mut [Bytes], ) -> Result<(), Error>

Write entire buf.

Cancel Safety

This function is cancel safe.

pub fn offset(&self) -> u64

Return the offset of the file.

pub async fn copy_to( &mut self, dst: &mut Self, n: NonZeroU64, ) -> Result<(), Error>

Copy n bytes of data from self to dst.

The server MUST copy the data exactly as if the data is copied using a series of read and write.

There are no protocol restictions on this operation; however, the server MUST ensure that the user does not exceed quota, etc. The server is, as always, free to complete this operation out of order if it is too large to complete immediately, or to refuse a request that is too large.

After a successful function call, the offset of self and dst are increased by n.

Precondition

Requires extension copy-data. For openssh-portable, this is available from V_9_0_P1.

You can check it with Sftp::support_copy.

If the extension is not supported by the server, this function would fail with Error::UnsupportedExtension.

pub async fn copy_all_to(&mut self, dst: &mut Self) -> Result<(), Error>

Copy data from self to dst until EOF is encountered.

The server MUST copy the data exactly as if the data is copied using a series of read and write.

There are no protocol restictions on this operation; however, the server MUST ensure that the user does not exceed quota, etc. The server is, as always, free to complete this operation out of order if it is too large to complete immediately, or to refuse a request that is too large.

After a successful function call, the offset of self and dst are unchanged.

Precondition

Requires extension copy-data. For openssh-portable, this is available from V_9_0_P1.

You can check it with Sftp::support_copy.

If the extension is not supported by the server, this function would fail with Error::UnsupportedExtension.

pub fn as_mut_file(&mut self) -> &mut File

No-op to be compatible with TokioCompatFile::as_mut_file

Trait Implementations

impl AsyncBufRead for TokioCompatFile

fn poll_fill_buf( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<&[u8]>>

Attempts to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(self: Pin<&mut Self>, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read.

impl AsyncRead for TokioCompatFile

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, read_buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl AsyncSeek for TokioCompatFile

fn start_seek(self: Pin<&mut Self>, position: SeekFrom) -> Result<()>

Attempts to seek to an offset, in bytes, in a stream.

fn poll_complete( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<u64>>

Waits for a seek operation to complete.

impl AsyncWrite for TokioCompatFile

TokioCompatFile::poll_write only writes data to the buffer.

TokioCompatFile::poll_write and TokioCompatFile::poll_write_vectored would send at most one sftp request.

It is perfectly safe to buffer requests and send them in one go, since sftp v3 guarantees that requests on the same file handler is processed sequentially.

NOTE that these writes cannot be cancelled.

One maybe obvious note when using append-mode:

make sure that all data that belongs together is written to the file in one operation.

This can be done by concatenating strings before passing them to AsyncWrite::poll_write or AsyncWrite::poll_write_vectored and calling AsyncWrite::poll_flush on TokioCompatFile when the message is complete.

Calling AsyncWrite::poll_flush on TokioCompatFile would wait on writes in the order they are sent.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl Clone for TokioCompatFile

Creates a new TokioCompatFile instance that shares the same underlying file handle as the existing File instance.

Reads, writes, and seeks can be performed independently.

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TokioCompatFile

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

Formats the value using the given formatter.

impl Deref for TokioCompatFile

type Target = File

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for TokioCompatFile

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for TokioCompatFile

fn drop(&mut self)

Executes the destructor for this type.

impl From<File> for TokioCompatFile

fn from(inner: File) -> Self

Converts to this type from the input type.

impl From<TokioCompatFile> for File

fn from(file: TokioCompatFile) -> Self

Converts to this type from the input type.

impl<'pin> Unpin for TokioCompatFile

where PinnedFieldsOf<__TokioCompatFile<'pin>>: Unpin,