tokio/io/
async_seek.rs

Help
1use std::io::{self, SeekFrom};
2use std::ops::DerefMut;
3use std::pin::Pin;
4use std::task::{Context, Poll};
5
6/// Seek bytes asynchronously.
7///
8/// This trait is analogous to the [`std::io::Seek`] trait, but integrates
9/// with the asynchronous task system. In particular, the `start_seek`
10/// method, unlike [`Seek::seek`], will not block the calling thread.
11///
12/// Utilities for working with `AsyncSeek` values are provided by
13/// [`AsyncSeekExt`].
14///
15/// [`std::io::Seek`]: std::io::Seek
16/// [`Seek::seek`]: std::io::Seek::seek()
17/// [`AsyncSeekExt`]: crate::io::AsyncSeekExt
18pub trait AsyncSeek {
19    /// Attempts to seek to an offset, in bytes, in a stream.
20    ///
21    /// A seek beyond the end of a stream is allowed, but behavior is defined
22    /// by the implementation.
23    ///
24    /// If this function returns successfully, then the job has been submitted.
25    /// To find out when it completes, call `poll_complete`.
26    ///
27    /// # Errors
28    ///
29    /// This function can return [`io::ErrorKind::Other`] in case there is
30    /// another seek in progress. To avoid this, it is advisable that any call
31    /// to `start_seek` is preceded by a call to `poll_complete` to ensure all
32    /// pending seeks have completed.
33    fn start_seek(self: Pin<&mut Self>, position: SeekFrom) -> io::Result<()>;
34
35    /// Waits for a seek operation to complete.
36    ///
37    /// If the seek operation completed successfully, this method returns the
38    /// new position from the start of the stream. That position can be used
39    /// later with [`SeekFrom::Start`].
40    ///
41    /// The position returned by calling this method can only be relied on right
42    /// after `start_seek`. If you have changed the position by e.g. reading or
43    /// writing since calling `start_seek`, then it is unspecified whether the
44    /// returned position takes that position change into account. Similarly, if
45    /// `start_seek` has never been called, then it is unspecified whether
46    /// `poll_complete` returns the actual position or some other placeholder
47    /// value (such as 0).
48    ///
49    /// # Errors
50    ///
51    /// Seeking to a negative offset is considered an error.
52    fn poll_complete(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<u64>>;
53}
54
55macro_rules! deref_async_seek {
56    () => {
57        fn start_seek(mut self: Pin<&mut Self>, pos: SeekFrom) -> io::Result<()> {
58            Pin::new(&mut **self).start_seek(pos)
59        }
60
61        fn poll_complete(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<u64>> {
62            Pin::new(&mut **self).poll_complete(cx)
63        }
64    };
65}
66
67impl<T: ?Sized + AsyncSeek + Unpin> AsyncSeek for Box<T> {
68    deref_async_seek!();
69}
70
71impl<T: ?Sized + AsyncSeek + Unpin> AsyncSeek for &mut T {
72    deref_async_seek!();
73}
74
75impl<P> AsyncSeek for Pin<P>
76where
77    P: DerefMut,
78    P::Target: AsyncSeek,
79{
80    fn start_seek(self: Pin<&mut Self>, pos: SeekFrom) -> io::Result<()> {
81        crate::util::pin_as_deref_mut(self).start_seek(pos)
82    }
83
84    fn poll_complete(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<u64>> {
85        crate::util::pin_as_deref_mut(self).poll_complete(cx)
86    }
87}
88
89impl<T: AsRef<[u8]> + Unpin> AsyncSeek for io::Cursor<T> {
90    fn start_seek(mut self: Pin<&mut Self>, pos: SeekFrom) -> io::Result<()> {
91        io::Seek::seek(&mut *self, pos).map(drop)
92    }
93    fn poll_complete(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<u64>> {
94        Poll::Ready(Ok(self.get_mut().position()))
95    }
96}
tokio/io/async_seek.rs

tokio/io/
async_seek.rs
