io: move io helpers back into tokio-io (#1377)

Utilities are made optional with a feature flag.

tokio-io/Cargo.toml

@@ -25,7 +25,14 @@ publish = false
 bytes = "0.4.7"
 log = "0.4"
 futures-core-preview = "0.3.0-alpha.17"
+memchr = { version = "2.2", optional = true }
 
 [dev-dependencies]
 pin-utils = "0.1.0-alpha.4"
+tokio = { version = "0.2.0", path = "../tokio" }
+futures-util-preview = "0.3.0-alpha.17"
 tokio-test = { version = "0.2.0", path = "../tokio-test" }
+
+[features]
+default = ["util"]
+util = ["memchr"]

tokio-io/src/io/async_buf_read_ext.rs

@@ -1,8 +1,7 @@
 use crate::io::lines::{lines, Lines};
 use crate::io::read_line::{read_line, ReadLine};
 use crate::io::read_until::{read_until, ReadUntil};
-
-use tokio_io::AsyncBufRead;
+use crate::AsyncBufRead;
 
 /// An extension trait which adds utility methods to `AsyncBufRead` types.
 pub trait AsyncBufReadExt: AsyncBufRead {
@@ -19,12 +18,6 @@ pub trait AsyncBufReadExt: AsyncBufRead {
     ///
     /// In the case of an error the buffer and the object will be discarded, with
     /// the error yielded.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn read_until<'a>(&'a mut self, byte: u8, buf: &'a mut Vec<u8>) -> ReadUntil<'a, Self>
     where
         Self: Unpin,
@@ -55,12 +48,6 @@ pub trait AsyncBufReadExt: AsyncBufRead {
     /// the event that all data read so far was valid UTF-8.
     ///
     /// [`read_until`]: AsyncBufReadExt::read_until
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn read_line<'a>(&'a mut self, buf: &'a mut String) -> ReadLine<'a, Self>
     where
         Self: Unpin,
@@ -83,12 +70,6 @@ pub trait AsyncBufReadExt: AsyncBufRead {
     /// Each line of the stream has the same error semantics as [`AsyncBufReadExt::read_line`].
     ///
     /// [`AsyncBufReadExt::read_line`]: AsyncBufReadExt::read_line
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn lines(self) -> Lines<Self>
     where
         Self: Sized,

tokio-io/src/io/async_read_ext.rs

@@ -3,8 +3,7 @@ use crate::io::read::{read, Read};
 use crate::io::read_exact::{read_exact, ReadExact};
 use crate::io::read_to_end::{read_to_end, ReadToEnd};
 use crate::io::read_to_string::{read_to_string, ReadToString};
-
-use tokio_io::{AsyncRead, AsyncWrite};
+use crate::{AsyncRead, AsyncWrite};
 
 /// An extension trait which adds utility methods to `AsyncRead` types.
 pub trait AsyncReadExt: AsyncRead {
@@ -18,12 +17,6 @@ pub trait AsyncReadExt: AsyncRead {
     /// On success the number of bytes is returned and the `reader` and `writer`
     /// are consumed. On error the error is returned and the I/O objects are
     /// consumed as well.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn copy<'a, W>(&'a mut self, dst: &'a mut W) -> Copy<'a, Self, W>
     where
         Self: Unpin,
@@ -36,12 +29,6 @@ pub trait AsyncReadExt: AsyncRead {
     ///
     /// The returned future will resolve to the number of bytes read once the
     /// read operation is completed.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn read<'a>(&'a mut self, dst: &'a mut [u8]) -> Read<'a, Self>
     where
         Self: Unpin,
@@ -50,12 +37,6 @@ pub trait AsyncReadExt: AsyncRead {
     }
 
     /// Read exactly the amount of data needed to fill the provided buffer.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn read_exact<'a>(&'a mut self, dst: &'a mut [u8]) -> ReadExact<'a, Self>
     where
         Self: Unpin,
@@ -66,12 +47,6 @@ pub trait AsyncReadExt: AsyncRead {
     /// Read all bytes until EOF in this source, placing them into `dst`.
     ///
     /// On success the total number of bytes read is returned.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn read_to_end<'a>(&'a mut self, dst: &'a mut Vec<u8>) -> ReadToEnd<'a, Self>
     where
         Self: Unpin,
@@ -82,12 +57,6 @@ pub trait AsyncReadExt: AsyncRead {
     /// Read all bytes until EOF in this source, placing them into `dst`.
     ///
     /// On success the total number of bytes read is returned.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn read_to_string<'a>(&'a mut self, dst: &'a mut String) -> ReadToString<'a, Self>
     where
         Self: Unpin,

tokio-io/src/io/async_write_ext.rs

@@ -1,18 +1,11 @@
 use crate::io::flush::{flush, Flush};
 use crate::io::write::{write, Write};
 use crate::io::write_all::{write_all, WriteAll};
-
-use tokio_io::AsyncWrite;
+use crate::AsyncWrite;
 
 /// An extension trait which adds utility methods to `AsyncWrite` types.
 pub trait AsyncWriteExt: AsyncWrite {
     /// Write a buffer into this writter, returning how many bytes were written.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ````
     fn write<'a>(&'a mut self, src: &'a [u8]) -> Write<'a, Self>
     where
         Self: Unpin,
@@ -21,12 +14,6 @@ pub trait AsyncWriteExt: AsyncWrite {
     }
 
     /// Attempt to write an entire buffer into this writter.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn write_all<'a>(&'a mut self, src: &'a [u8]) -> WriteAll<'a, Self>
     where
         Self: Unpin,
@@ -35,12 +22,6 @@ pub trait AsyncWriteExt: AsyncWrite {
     }
 
     /// Flush the contents of this writer.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// unimplemented!();
-    /// ```
     fn flush(&mut self) -> Flush<'_, Self>
     where
         Self: Unpin,

tokio-io/src/io/copy.rs

@@ -1,9 +1,9 @@
+use crate::{AsyncRead, AsyncWrite};
 use futures_core::ready;
 use std::future::Future;
 use std::io;
 use std::pin::Pin;
 use std::task::{Context, Poll};
-use tokio_io::{AsyncRead, AsyncWrite};
 
 #[derive(Debug)]
 #[must_use = "futures do nothing unless you `.await` or poll them"]

tokio-io/src/io/flush.rs

@@ -1,10 +1,9 @@
+use crate::AsyncWrite;
 use std::future::Future;
 use std::io;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-use tokio_io::AsyncWrite;
-
 /// A future used to fully flush an I/O object.
 ///
 /// Created by the [`AsyncWriteExt::flush`] function.

tokio-io/src/io/lines.rs

@@ -1,6 +1,5 @@
 use super::read_line::read_line_internal;
-
-use tokio_io::AsyncBufRead;
+use crate::AsyncBufRead;
 
 use futures_core::{ready, Stream};
 use std::io;

tokio-io/src/io/mod.rs

@@ -54,12 +54,3 @@ mod write_all;
 pub use self::async_buf_read_ext::AsyncBufReadExt;
 pub use self::async_read_ext::AsyncReadExt;
 pub use self::async_write_ext::AsyncWriteExt;
-
-// standard input, output, and error
-#[cfg(feature = "fs")]
-pub use tokio_fs::{stderr, stdin, stdout, Stderr, Stdin, Stdout};
-pub use tokio_io::{AsyncBufRead, AsyncRead, AsyncWrite};
-
-// Re-export io::Error so that users don't have to deal
-// with conflicts when `use`ing `tokio::io` and `std::io`.
-pub use std::io::{Error, ErrorKind, Result};

tokio-io/src/io/read.rs

@@ -1,9 +1,9 @@
+use crate::AsyncRead;
 use std::future::Future;
 use std::io;
 use std::marker::Unpin;
 use std::pin::Pin;
 use std::task::{Context, Poll};
-use tokio_io::AsyncRead;
 
 /// Tries to read some bytes directly into the given `buf` in asynchronous
 /// manner, returning a future type.

tokio-io/src/io/read_exact.rs

@@ -1,10 +1,10 @@
+use crate::AsyncRead;
 use futures_core::ready;
 use std::future::Future;
 use std::io;
 use std::marker::Unpin;
 use std::pin::Pin;
 use std::task::{Context, Poll};
-use tokio_io::AsyncRead;
 
 /// A future which can be used to easily read exactly enough bytes to fill
 /// a buffer.

tokio-io/src/io/read_line.rs

@@ -1,4 +1,5 @@
 use super::read_until::read_until_internal;
+use crate::AsyncBufRead;
 use futures_core::ready;
 use std::future::Future;
 use std::io;
@@ -6,7 +7,6 @@ use std::mem;
 use std::pin::Pin;
 use std::str;
 use std::task::{Context, Poll};
-use tokio_io::AsyncBufRead;
 
 /// Future for the [`read_line`](crate::io::AsyncBufReadExt::read_line) method.
 #[derive(Debug)]

tokio-io/src/io/read_to_end.rs

@@ -1,5 +1,4 @@
-use tokio_io::AsyncRead;
-
+use crate::AsyncRead;
 use futures_core::ready;
 use std::future::Future;
 use std::io;

tokio-io/src/io/read_to_string.rs

@@ -1,10 +1,10 @@
 use super::read_to_end::read_to_end_internal;
+use crate::AsyncRead;
 use futures_core::ready;
 use std::future::Future;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 use std::{io, mem, str};
-use tokio_io::AsyncRead;
 
 /// Future for the [`read_to_string`](super::AsyncReadExt::read_to_string) method.
 #[derive(Debug)]

tokio-io/src/io/read_until.rs

@@ -1,10 +1,10 @@
+use crate::AsyncBufRead;
 use futures_core::ready;
 use std::future::Future;
 use std::io;
 use std::mem;
 use std::pin::Pin;
 use std::task::{Context, Poll};
-use tokio_io::AsyncBufRead;
 
 /// Future for the [`read_until`](crate::io::AsyncBufReadExt::read_until) method.
 #[derive(Debug)]

tokio-io/src/io/write.rs

@@ -1,8 +1,8 @@
+use crate::AsyncWrite;
 use std::future::Future;
 use std::io;
 use std::pin::Pin;
 use std::task::{Context, Poll};
-use tokio_io::AsyncWrite;
 
 /// A future to write some of the buffer to an `AsyncWrite`.
 #[derive(Debug)]

tokio-io/src/io/write_all.rs

@@ -1,5 +1,4 @@
-use tokio_io::AsyncWrite;
-
+use crate::AsyncWrite;
 use futures_core::ready;
 use std::future::Future;
 use std::io;

tokio-io/src/lib.rs

@@ -1,4 +1,4 @@
-#![doc(html_root_url = "https://docs.rs/tokio-io/0.1.12")]
+#![doc(html_root_url = "https://docs.rs/tokio-io/0.2.0")]
 #![deny(missing_debug_implementations, missing_docs, rust_2018_idioms)]
 #![cfg_attr(test, deny(warnings))]
 #![doc(test(no_crate_inject, attr(deny(rust_2018_idioms))))]
@@ -15,9 +15,15 @@ mod async_buf_read;
 mod async_read;
 mod async_write;
 
+#[cfg(feature = "util")]
+mod io;
+
 pub use self::async_buf_read::AsyncBufRead;
 pub use self::async_read::AsyncRead;
 pub use self::async_write::AsyncWrite;
 
+#[cfg(feature = "util")]
+pub use self::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt};
+
 // Re-export `Buf` and `BufMut` since they are part of the API
 pub use bytes::{Buf, BufMut};

tokio-io/tests/copy.rs

@@ -1,7 +1,7 @@
 #![deny(warnings, rust_2018_idioms)]
 #![feature(async_await)]
 
-use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite};
+use tokio_io::{AsyncRead, AsyncReadExt, AsyncWrite};
 use tokio_test::assert_ok;
 
 use bytes::BytesMut;

tokio-io/tests/lines.rs

@@ -2,7 +2,7 @@
 #![feature(async_await)]
 
 use futures_util::StreamExt;
-use tokio::io::{AsyncBufRead, AsyncBufReadExt, AsyncRead};
+use tokio_io::{AsyncBufRead, AsyncBufReadExt, AsyncRead};
 use tokio_test::assert_ok;
 
 use std::io;

tokio-io/tests/read.rs

@@ -1,7 +1,7 @@
 #![deny(warnings, rust_2018_idioms)]
 #![feature(async_await)]
 
-use tokio::io::{AsyncRead, AsyncReadExt};
+use tokio_io::{AsyncRead, AsyncReadExt};
 use tokio_test::assert_ok;
 
 use std::io;

tokio-io/tests/read_exact.rs

@@ -1,7 +1,7 @@
 #![deny(warnings, rust_2018_idioms)]
 #![feature(async_await)]
 
-use tokio::io::{AsyncRead, AsyncReadExt};
+use tokio_io::{AsyncRead, AsyncReadExt};
 use tokio_test::assert_ok;
 
 use std::io;

tokio-io/tests/read_line.rs

@@ -1,7 +1,7 @@
 #![deny(warnings, rust_2018_idioms)]
 #![feature(async_await)]
 
-use tokio::io::{AsyncBufRead, AsyncBufReadExt, AsyncRead};
+use tokio_io::{AsyncBufRead, AsyncBufReadExt, AsyncRead};
 use tokio_test::assert_ok;
 
 use std::io;

tokio-io/tests/read_to_end.rs

@@ -1,7 +1,7 @@
 #![deny(warnings, rust_2018_idioms)]
 #![feature(async_await)]
 
-use tokio::io::{AsyncRead, AsyncReadExt};
+use tokio_io::{AsyncRead, AsyncReadExt};
 use tokio_test::assert_ok;
 
 use std::pin::Pin;

tokio-io/tests/read_to_string.rs

@@ -1,7 +1,7 @@
 #![deny(warnings, rust_2018_idioms)]
 #![feature(async_await)]
 
-use tokio::io::{AsyncRead, AsyncReadExt};
+use tokio_io::{AsyncRead, AsyncReadExt};
 use tokio_test::assert_ok;
 
 use std::pin::Pin;

tokio-io/tests/read_until.rs

@@ -1,7 +1,7 @@
 #![deny(warnings, rust_2018_idioms)]
 #![feature(async_await)]
 
-use tokio::io::{AsyncBufRead, AsyncBufReadExt, AsyncRead};
+use tokio_io::{AsyncBufRead, AsyncBufReadExt, AsyncRead};
 use tokio_test::assert_ok;
 
 use std::io;

tokio-io/tests/write.rs

@@ -1,7 +1,7 @@
 #![deny(warnings, rust_2018_idioms)]
 #![feature(async_await)]
 
-use tokio::io::{AsyncWrite, AsyncWriteExt};
+use tokio_io::{AsyncWrite, AsyncWriteExt};
 use tokio_test::assert_ok;
 
 use bytes::BytesMut;

tokio-io/tests/write_all.rs

@@ -1,7 +1,7 @@
 #![deny(warnings, rust_2018_idioms)]
 #![feature(async_await)]
 
-use tokio::io::{AsyncWrite, AsyncWriteExt};
+use tokio_io::{AsyncWrite, AsyncWriteExt};
 use tokio_test::assert_ok;
 
 use bytes::BytesMut;

tokio/Cargo.toml

@@ -38,9 +38,9 @@ default = [
   "uds",
 ]
 
-codec = ["io", "tokio-codec"]
+codec = ["io", "tokio-codec", "bytes"]
 fs = ["tokio-fs"]
-io = ["bytes", "tokio-io", "memchr"]
+io = ["tokio-io"]
 reactor = ["io", "tokio-reactor"]
 rt-full = [
   "num_cpus",
@@ -80,7 +80,6 @@ tokio-tcp = { version = "0.2.0", optional = true, path = "../tokio-tcp", feature
 tokio-udp = { version = "0.2.0", optional = true, path = "../tokio-udp" }
 tokio-timer = { version = "0.3.0", optional = true, path = "../tokio-timer", features = ["async-traits"] }
 tracing-core = { version = "0.1", optional = true }
-memchr = { version = "2.2", optional = true }
 
 [target.'cfg(unix)'.dependencies]
 tokio-uds = { version = "0.3.0", optional = true, path = "../tokio-uds", features = ["async-traits"] }

tokio/src/io.rs

@@ -0,0 +1,48 @@
+//! Asynchronous I/O.
+//!
+//! This module is the asynchronous version of `std::io`. Primarily, it
+//! defines two traits, [`AsyncRead`] and [`AsyncWrite`], which extend the
+//! `Read` and `Write` traits of the standard library.
+//!
+//! # AsyncRead and AsyncWrite
+//!
+//! [`AsyncRead`] and [`AsyncWrite`] must only be implemented for
+//! non-blocking I/O types that integrate with the futures type system. In
+//! other words, these types must never block the thread, and instead the
+//! current task is notified when the I/O resource is ready.
+//!
+//! # Standard input and output
+//!
+//! Tokio provides asynchronous APIs to standard [input], [output], and [error].
+//! These APIs are very similar to the ones provided by `std`, but they also
+//! implement [`AsyncRead`] and [`AsyncWrite`].
+//!
+//! Unlike *most* other Tokio APIs, the standard input / output APIs
+//! **must** be used from the context of the Tokio runtime as they require
+//! Tokio specific features to function.
+//!
+//! [input]: fn.stdin.html
+//! [output]: fn.stdout.html
+//! [error]: fn.stderr.html
+//!
+//! # `std` re-exports
+//!
+//! Additionally, [`Error`], [`ErrorKind`], and [`Result`] are re-exported
+//! from `std::io` for ease of use.
+//!
+//! [`AsyncRead`]: trait.AsyncRead.html
+//! [`AsyncWrite`]: trait.AsyncWrite.html
+//! [`Error`]: struct.Error.html
+//! [`ErrorKind`]: enum.ErrorKind.html
+//! [`Result`]: type.Result.html
+
+// standard input, output, and error
+#[cfg(feature = "fs")]
+pub use tokio_fs::{stderr, stdin, stdout, Stderr, Stdin, Stdout};
+pub use tokio_io::{
+    AsyncBufRead, AsyncBufReadExt, AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt,
+};
+
+// Re-export io::Error so that users don't have to deal
+// with conflicts when `use`ing `tokio::io` and `std::io`.
+pub use std::io::{Error, ErrorKind, Result};