Add AsyncSeek trait

Author: taiki-e

futures-io/src/lib.rs

@@ -23,11 +23,12 @@ mod if_std {
     // Re-export IoVec for convenience
     pub use iovec::IoVec;
 
-    // Re-export io::Error so that users don't have to deal
+    // Re-export some types from `std::io` so that users don't have to deal
     // with conflicts when `use`ing `futures::io` and `std::io`.
     pub use self::StdIo::Error as Error;
     pub use self::StdIo::ErrorKind as ErrorKind;
     pub use self::StdIo::Result as Result;
+    pub use self::StdIo::SeekFrom as SeekFrom;
 
     /// A type used to conditionally initialize buffers passed to `AsyncRead`
     /// methods, modeled after `std`.
@@ -241,6 +242,30 @@ mod if_std {
         fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>;
     }
 
+    /// Seek bytes asynchronously.
+    ///
+    /// This trait is analogous to the `std::io::Seek` trait, but integrates
+    /// with the asynchronous task system. In particular, the `poll_seek`
+    /// method, unlike `Seek::seek`, will automatically queue the current task
+    /// for wakeup and return if data is not yet available, rather than blocking
+    /// the calling thread.
+    pub trait AsyncSeek {
+        /// Attempt 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 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`].
+        ///
+        /// # Errors
+        ///
+        /// Seeking to a negative offset is considered an error.
+        fn poll_seek(self: Pin<&mut Self>, cx: &mut Context<'_>, pos: SeekFrom)
+            -> Poll<Result<u64>>;
+    }
+
     macro_rules! deref_async_read {
         () => {
             unsafe fn initializer(&self) -> Initializer {
@@ -429,6 +454,51 @@ mod if_std {
     impl AsyncWrite for StdIo::Sink {
         delegate_async_write_to_stdio!();
     }
+
+    macro_rules! deref_async_seek {
+        () => {
+            fn poll_seek(mut self: Pin<&mut Self>, cx: &mut Context<'_>, pos: SeekFrom)
+                -> Poll<Result<u64>>
+            {
+                Pin::new(&mut **self).poll_seek(cx, pos)
+            }
+        }
+    }
+
+    impl<T: ?Sized + AsyncSeek + Unpin> AsyncSeek for Box<T> {
+        deref_async_seek!();
+    }
+
+    impl<T: ?Sized + AsyncSeek + Unpin> AsyncSeek for &mut T {
+        deref_async_seek!();
+    }
+
+
+    impl<P> AsyncSeek for Pin<P>
+    where
+        P: DerefMut + Unpin,
+        P::Target: AsyncSeek,
+    {
+        fn poll_seek(self: Pin<&mut Self>, cx: &mut Context<'_>, pos: SeekFrom)
+            -> Poll<Result<u64>>
+        {
+            self.get_mut().as_mut().poll_seek(cx, pos)
+        }
+    }
+
+    macro_rules! delegate_async_seek_to_stdio {
+        () => {
+            fn poll_seek(mut self: Pin<&mut Self>, _: &mut Context<'_>, pos: SeekFrom)
+            -> Poll<Result<u64>>
+            {
+                Poll::Ready(StdIo::Seek::seek(&mut *self, pos))
+            }
+        }
+    }
+
+    impl<T: AsRef<[u8]> + Unpin> AsyncSeek for StdIo::Cursor<T> {
+        delegate_async_seek_to_stdio!();
+    }
 }
 
 #[cfg(feature = "std")]

futures-util/src/io/allow_std.rs

@@ -1,5 +1,5 @@
 use futures_core::task::{Context, Poll};
-use futures_io::{AsyncRead, AsyncWrite};
+use futures_io::{AsyncRead, AsyncWrite, AsyncSeek};
 use std::{fmt, io};
 use std::pin::Pin;
 use std::string::String;
@@ -116,3 +116,17 @@ impl<T> AsyncRead for AllowStdIo<T> where T: io::Read {
         Poll::Ready(Ok(try_with_interrupt!(self.0.read(buf))))
     }
 }
+
+impl<T> io::Seek for AllowStdIo<T> where T: io::Seek {
+    fn seek(&mut self, pos: io::SeekFrom) -> io::Result<u64> {
+        self.0.seek(pos)
+    }
+}
+
+impl<T> AsyncSeek for AllowStdIo<T> where T: io::Seek {
+    fn poll_seek(mut self: Pin<&mut Self>, _: &mut Context<'_>, pos: io::SeekFrom)
+        -> Poll<io::Result<u64>>
+    {
+        Poll::Ready(Ok(try_with_interrupt!(self.0.seek(pos))))
+    }
+}

futures-util/src/io/mod.rs

@@ -7,7 +7,7 @@
 
 use std::vec::Vec;
 
-pub use futures_io::{AsyncRead, AsyncWrite, IoVec};
+pub use futures_io::{AsyncRead, AsyncWrite, AsyncSeek, IoVec, SeekFrom};
 
 #[cfg(feature = "io-compat")] use crate::compat::Compat;
 
@@ -38,6 +38,9 @@ pub use self::read_to_end::ReadToEnd;
 mod close;
 pub use self::close::Close;
 
+mod seek;
+pub use self::seek::Seek;
+
 mod split;
 pub use self::split::{ReadHalf, WriteHalf};
 
@@ -324,3 +327,19 @@ pub trait AsyncWriteExt: AsyncWrite {
 }
 
 impl<W: AsyncWrite + ?Sized> AsyncWriteExt for W {}
+
+/// An extension trait which adds utility methods to `AsyncSeek` types.
+pub trait AsyncSeekExt: AsyncSeek {
+    /// Creates a future which will seek an IO object, and then yield the
+    /// new position in the object and the object itself.
+    ///
+    /// In the case of an error the buffer and the object will be discarded, with
+    /// the error yielded.
+    fn seek(&mut self, pos: SeekFrom) -> Seek<'_, Self>
+        where Self: Unpin,
+    {
+        Seek::new(self, pos)
+    }
+}
+
+impl<S: AsyncSeek + ?Sized> AsyncSeekExt for S {}

futures-util/src/io/seek.rs

@@ -0,0 +1,29 @@
+use crate::io::{AsyncSeek, SeekFrom};
+use futures_core::future::Future;
+use futures_core::task::{Context, Poll};
+use std::io;
+use std::pin::Pin;
+
+/// Future for the [`seek`](super::SeekExt::seek) method.
+#[derive(Debug)]
+pub struct Seek<'a, S: ?Sized + Unpin> {
+    seek: &'a mut S,
+    pos: SeekFrom,
+}
+
+impl<S: ?Sized + Unpin> Unpin for Seek<'_, S> {}
+
+impl<'a, S: AsyncSeek + ?Sized + Unpin> Seek<'a, S> {
+    pub(super) fn new(seek: &'a mut S, pos: SeekFrom) -> Self {
+        Self { seek, pos }
+    }
+}
+
+impl<S: AsyncSeek + ?Sized + Unpin> Future for Seek<'_, S> {
+    type Output = io::Result<u64>;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        let this = &mut *self;
+        Pin::new(&mut this.seek).poll_seek(cx, this.pos)
+    }
+}

futures/src/lib.rs

@@ -268,11 +268,12 @@ pub mod io {
     //! sinks.
 
     pub use futures_io::{
-        Error, Initializer, IoVec, ErrorKind, AsyncRead, AsyncWrite, Result
+        Error, Initializer, IoVec, ErrorKind, AsyncRead, AsyncWrite, AsyncSeek,
+        Result, SeekFrom,
     };
     pub use futures_util::io::{
-        AsyncReadExt, AsyncWriteExt, AllowStdIo, Close, CopyInto, Flush,
-        Read, ReadExact, ReadHalf, ReadToEnd, Window, WriteAll, WriteHalf,
+        AsyncReadExt, AsyncWriteExt, AsyncSeekExt, AllowStdIo, Close, CopyInto, Flush,
+        Read, ReadExact, ReadHalf, ReadToEnd, Seek, Window, WriteAll, WriteHalf,
     };
 }