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-io/tests/split.rs

@@ -0,0 +1,57 @@
+use tokio::io::{split, AsyncRead, AsyncWrite};
+
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+
+struct RW;
+
+impl AsyncRead for RW {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        _cx: &mut Context<'_>,
+        _buf: &mut [u8],
+    ) -> Poll<io::Result<usize>> {
+        Poll::Ready(Ok(1))
+    }
+}
+
+impl AsyncWrite for RW {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        _cx: &mut Context<'_>,
+        _buf: &[u8],
+    ) -> Poll<Result<usize, io::Error>> {
+        Poll::Ready(Ok(1))
+    }
+
+    fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Result<(), io::Error>> {
+        Poll::Ready(Ok(()))
+    }
+
+    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Result<(), io::Error>> {
+        Poll::Ready(Ok(()))
+    }
+}
+
+#[test]
+fn unsplit_ok() {
+    let (r, w) = split(RW);
+    r.unsplit(w);
+}
+
+#[test]
+#[should_panic]
+fn unsplit_err1() {
+    let (r, _) = split(RW);
+    let (_, w) = split(RW);
+    r.unsplit(w);
+}
+
+#[test]
+#[should_panic]
+fn unsplit_err2() {
+    let (_, w) = split(RW);
+    let (r, _) = split(RW);
+    r.unsplit(w);
+}