Add `io` facade and update `reactor` docs (#166)

This patch updates the documentation for a number of APIs. It also
introduces a prelude module and an io facade module, re-exporting types
from tokio-io.

1 files changed, 45 insertions, 0 deletions

diff --git a/README.md b/README.md
index 3b98d7c6..33cf1748 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,51 @@ an asynchronous application.
 [reactor]: https://docs.rs/tokio/0.1.1/tokio/reactor/index.html
 [scheduler]: https://tokio-rs.github.io/tokio/tokio/runtime/index.html
 
+## Example
+
+A basic TCP echo server with Tokio:
+
+```rust
+extern crate tokio;
+
+use tokio::prelude::*;
+use tokio::io::copy;
+use tokio::net::TcpListener;
+
+fn main() {
+    // Bind the server's socket.
+    let addr = "127.0.0.1:12345".parse().unwrap();
+    let listener = TcpListener::bind(&addr)
+        .expect("unable to bind TCP listener");
+
+    // Pull out a stream of sockets for incoming connections
+    let server = listener.incoming()
+        .map_err(|e| eprintln!("accept failed = {:?}", e))
+        .for_each(|sock| {
+            // Split up the reading and writing parts of the
+            // socket.
+            let (reader, writer) = sock.split();
+
+            // A future that echos the data and returns how
+            // many bytes were copied...
+            let bytes_copied = copy(reader, writer);
+
+            // ... after which we'll print what happened.
+            let handle_conn = bytes_copied.map(|amt| {
+                println!("wrote {:?} bytes", amt)
+            }).map_err(|err| {
+                eprintln!("IO error {:?}", err)
+            });
+
+            // Spawn the future as a concurrent task.
+            tokio::spawn(handle_conn)
+        });
+
+    // Start the Tokio runtime
+    tokio::run(server);
+}
+```
+
 # License
 
 This project is licensed under either of