pub trait AsyncSeek {
// Required methods
fn start_seek(self: Pin<&mut Self>, position: SeekFrom) -> Result<()>;
fn poll_complete(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
) -> Poll<Result<u64>>;
}
Expand description
Seek bytes asynchronously.
This trait is analogous to the std::io::Seek
trait, but integrates
with the asynchronous task system. In particular, the start_seek
method, unlike Seek::seek
, will not block the calling thread.
Utilities for working with AsyncSeek
values are provided by
AsyncSeekExt
.
Required Methods§
Sourcefn start_seek(self: Pin<&mut Self>, position: SeekFrom) -> Result<()>
fn start_seek(self: Pin<&mut Self>, position: SeekFrom) -> Result<()>
Attempts to seek to an offset, in bytes, in a stream.
A seek beyond the end of a stream is allowed, but behavior is defined by the implementation.
If this function returns successfully, then the job has been submitted.
To find out when it completes, call poll_complete
.
§Errors
This function can return io::ErrorKind::Other
in case there is
another seek in progress. To avoid this, it is advisable that any call
to start_seek
is preceded by a call to poll_complete
to ensure all
pending seeks have completed.
Sourcefn poll_complete(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
) -> Poll<Result<u64>>
fn poll_complete( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<u64>>
Waits for a seek operation to complete.
If the seek operation completed successfully,
this method returns the new position from the start of the stream.
That position can be used later with SeekFrom::Start
. Repeatedly
calling this function without calling start_seek
might return the
same result.
§Errors
Seeking to a negative offset is considered an error.
Implementations on Foreign Types§
Implementors§
impl AsyncSeek for File
impl<R: AsyncRead + AsyncSeek> AsyncSeek for BufReader<R>
Seeks to an offset, in bytes, in the underlying reader.
The position used for seeking with SeekFrom::Current(_)
is the
position the underlying reader would be at if the BufReader
had no
internal buffer.
Seeking always discards the internal buffer, even if the seek position
would otherwise fall within it. This guarantees that calling
.into_inner()
immediately after a seek yields the underlying reader
at the same position.
See AsyncSeek
for more details.
Note: In the edge case where you’re seeking with SeekFrom::Current(n)
where n
minus the internal buffer length overflows an i64
, two
seeks will be performed instead of one. If the second seek returns
Err
, the underlying reader will be left at the same position it would
have if you called seek
with SeekFrom::Current(0)
.
impl<RW: AsyncRead + AsyncWrite + AsyncSeek> AsyncSeek for BufStream<RW>
Seek to an offset, in bytes, in the underlying stream.
The position used for seeking with SeekFrom::Current(_)
is the
position the underlying stream would be at if the BufStream
had no
internal buffer.
Seeking always discards the internal buffer, even if the seek position
would otherwise fall within it. This guarantees that calling
.into_inner()
immediately after a seek yields the underlying reader
at the same position.
See AsyncSeek
for more details.
Note: In the edge case where you’re seeking with SeekFrom::Current(n)
where n
minus the internal buffer length overflows an i64
, two
seeks will be performed instead of one. If the second seek returns
Err
, the underlying reader will be left at the same position it would
have if you called seek
with SeekFrom::Current(0)
.
impl<W: AsyncWrite + AsyncSeek> AsyncSeek for BufWriter<W>
Seek to the offset, in bytes, in the underlying writer.
Seeking always writes out the internal buffer before seeking.