net: add ReadHalf::{poll,poll_peak} (#2151)

The `&mut self` requirements for `TcpStream` methods ensure that there are at
most two tasks using the stream--one for reading and one for writing.

`TcpStream::split` allows two separate tasks to hold a reference to a single
`TcpStream`. `TcpStream::{peek,poll_peek}` only poll for read readiness, and
therefore are safe to use with a `ReadHalf`.

Instead of duplicating `TcpStream::poll_peek`, a private method is now used by
both `poll_peek` methods that uses the fact that only a `&TcpStream` is
required.

Closes #2136

tokio/tests/tcp_split.rs

@@ -1 +1,42 @@
-// TODO: write tests using TcpStream::split()
+#![warn(rust_2018_idioms)]
+#![cfg(feature = "full")]
+
+use std::io::Result;
+use std::io::{Read, Write};
+use std::{net, thread};
+
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpStream;
+
+#[tokio::test]
+async fn split() -> Result<()> {
+    const MSG: &[u8] = b"split";
+
+    let listener = net::TcpListener::bind("127.0.0.1:0")?;
+    let addr = listener.local_addr()?;
+
+    let handle = thread::spawn(move || {
+        let (mut stream, _) = listener.accept().unwrap();
+        stream.write(MSG).unwrap();
+
+        let mut read_buf = [0u8; 32];
+        let read_len = stream.read(&mut read_buf).unwrap();
+        assert_eq!(&read_buf[..read_len], MSG);
+    });
+
+    let mut stream = TcpStream::connect(&addr).await?;
+    let (mut read_half, mut write_half) = stream.split();
+
+    let mut read_buf = [0u8; 32];
+    let peek_len1 = read_half.peek(&mut read_buf[..]).await?;
+    let peek_len2 = read_half.peek(&mut read_buf[..]).await?;
+    assert_eq!(peek_len1, peek_len2);
+
+    let read_len = read_half.read(&mut read_buf[..]).await?;
+    assert_eq!(peek_len1, read_len);
+    assert_eq!(&read_buf[..read_len], MSG);
+
+    write_half.write(MSG).await?;
+    handle.join().unwrap();
+    Ok(())
+}