io: bring back split utility (#1521)

Bring back `split` utility as a free fn instead of a method on
`AsyncRead`. This utility wraps the `stream` in an `Arc` and uses mutual
exclusion to ensure correct access.

Additionally, the specialized `split_mut` fn on TcpStream and UdsStream
is promoted to `split`.

tokio/examples/connect.rs

@@ -93,7 +93,8 @@ mod tcp {
         stdin: impl Stream<Item = Result<Vec<u8>, io::Error>> + Unpin,
         mut stdout: impl Sink<Vec<u8>, Error = io::Error> + Unpin,
     ) -> Result<(), Box<dyn Error>> {
-        let (r, w) = TcpStream::connect(addr).await?.split();
+        let mut stream = TcpStream::connect(addr).await?;
+        let (r, w) = stream.split();
         let sink = FramedWrite::new(w, codec::Bytes);
         let mut stream = FramedRead::new(r, codec::Bytes).filter_map(|i| match i {
             Ok(i) => future::ready(Some(i)),

tokio/examples/proxy.rs

@@ -52,8 +52,8 @@ async fn main() -> Result<(), Box<dyn Error>> {
     Ok(())
 }
 
-async fn transfer(inbound: TcpStream, proxy_addr: String) -> Result<(), Box<dyn Error>> {
-    let outbound = TcpStream::connect(proxy_addr).await?;
+async fn transfer(mut inbound: TcpStream, proxy_addr: String) -> Result<(), Box<dyn Error>> {
+    let mut outbound = TcpStream::connect(proxy_addr).await?;
 
     let (mut ri, mut wi) = inbound.split();
     let (mut ro, mut wo) = outbound.split();

tokio/src/io.rs

@@ -39,6 +39,7 @@
 // standard input, output, and error
 #[cfg(feature = "fs")]
 pub use tokio_fs::{stderr, stdin, stdout, Stderr, Stdin, Stdout};
+pub use tokio_io::split::split;
 pub use tokio_io::{
     AsyncBufRead, AsyncBufReadExt, AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt, BufReader,
     BufWriter,