chore: prepare 0.2.0-alpha.2 release (#1465)

1 files changed, 105 insertions, 39 deletions

diff --git a/tokio/README.md b/tokio/README.md
index 8cf2cd94..2de30e7e 100644
--- a/tokio/README.md
+++ b/tokio/README.md
@@ -1,5 +1,7 @@
 # Tokio
 
+ _NOTE_: Tokio's [`master`](https://github.com/tokio-rs/tokio) branch is currently in the process of moving to [`std::future::Future`](https://doc.rust-lang.org/std/future/trait.Future.html), for `v0.1.x` based tokio releases please check out the [`v0.1.x`](https://github.com/tokio-rs/tokio/tree/v0.1.x) branch.
+
 A runtime for writing reliable, asynchronous, and slim applications with
 the Rust programming language. It is:
 
@@ -20,7 +22,7 @@ the Rust programming language. It is:
 [crates-badge]: https://img.shields.io/crates/v/tokio.svg
 [crates-url]: https://crates.io/crates/tokio
 [mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
-[mit-url]: LICENSE-MIT
+[mit-url]: LICENSE
 [azure-badge]: https://dev.azure.com/tokio-rs/Tokio/_apis/build/status/tokio-rs.tokio?branchName=master
 [azure-url]: https://dev.azure.com/tokio-rs/Tokio/_build/latest?definitionId=1&branchName=master
 [gitter-badge]: https://img.shields.io/gitter/room/tokio-rs/tokio.svg
@@ -28,7 +30,7 @@ the Rust programming language. It is:
 
 [Website](https://tokio.rs) |
 [Guides](https://tokio.rs/docs/) |
-[API Docs](https://docs.rs/tokio/0.2.0-alpha.1/tokio) |
+[API Docs](https://docs.rs/tokio/0.2.0-alpha.2/tokio) |
 [Chat](https://gitter.im/tokio-rs/tokio)
 
 ## Overview
@@ -38,61 +40,65 @@ asynchronous applications with the Rust programming language. At a high
 level, it provides a few major components:
 
 * A multithreaded, work-stealing based task [scheduler].
-* A [reactor] backed by the operating system's event queue (epoll, kqueue,
+* A reactor backed by the operating system's event queue (epoll, kqueue,
   IOCP, etc...).
 * Asynchronous [TCP and UDP][net] sockets.
 
 These components provide the runtime components necessary for building
 an asynchronous application.
 
-[net]: https://docs.rs/tokio/0.2.0-alpha.1/tokio/net/index.html
-[reactor]: https://docs.rs/tokio/0.2.0-alpha.1/tokio/reactor/index.html
-[scheduler]: https://docs.rs/tokio/0.2.0-alpha.1/tokio/runtime/index.html
+[net]: https://docs.rs/tokio/0.2.0-alpha.2/tokio/net/index.html
+[scheduler]: https://docs.rs/tokio/0.2.0-alpha.2/tokio/runtime/index.html
 
 ## Example
 
 A basic TCP echo server with Tokio:
 
 ```rust
-use tokio::prelude::*;
-use tokio::io::copy;
+#![feature(async_await)]
+
 use tokio::net::TcpListener;
+use tokio::prelude::*;
 
-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)
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let addr = "127.0.0.1:8080".parse()?;
+    let mut listener = TcpListener::bind(&addr).unwrap();
+
+    loop {
+        let (mut socket, _) = listener.accept().await?;
+
+        tokio::spawn(async move {
+            let mut buf = [0; 1024];
+
+            // In a loop, read data from the socket and write the data back.
+            loop {
+                let n = match socket.read(&mut buf).await {
+                    // socket closed
+                    Ok(n) if n == 0 => return,
+                    Ok(n) => n,
+                    Err(e) => {
+                        println!("failed to read from socket; err = {:?}", e);
+                        return;
+                    }
+                };
+
+                // Write the data back
+                if let Err(e) = socket.write_all(&buf[0..n]).await {
+                    println!("failed to write to socket; err = {:?}", e);
+                    return;
+                }
+            }
         });
-
-    // Start the Tokio runtime
-    tokio::run(server);
+    }
 }
 ```
 
-More examples can be found [here](examples).
+More examples can be found [here](tokio/examples). Note that the `master` branch
+is currently being updated to use `async` / `await`.  The examples are
+not fully ported. Examples for stable Tokio can be found
+[here](https://github.com/tokio-rs/tokio/tree/v0.1.x/tokio/examples).
+
 
 ## Getting Help
 
@@ -101,9 +107,69 @@ First, see if the answer to your question can be found in the [Guides] or the
 the [Tokio Gitter channel][chat]. We would be happy to try to answer your
 question.  Last, if that doesn't work, try opening an [issue] with the question.
 
+[Guides]: https://tokio.rs/docs/
+[API documentation]: https://docs.rs/tokio/0.2.0-alpha.2/tokio
 [chat]: https://gitter.im/tokio-rs/tokio
 [issue]: https://github.com/tokio-rs/tokio/issues/new
 
+## Contributing
+
+:balloon: Thanks for your help improving the project! We are so happy to have
+you! We have a [contributing guide][guide] to help you get involved in the Tokio
+project.
+
+[guide]: CONTRIBUTING.md
+
+## Project layout
+
+The `tokio` crate, found at the root, is primarily intended for use by
+application developers.  Library authors should depend on the sub crates, which
+have greater guarantees of stability.
+
+The crates included as part of Tokio are:
+
+* [`tokio-executor`]: Task executors and related utilities. Includes a
+  single-threaded executor and a multi-threaded, work-stealing, executor.
+
+* [`tokio-fs`]: Filesystem (and standard in / out) APIs.
+
+* [`tokio-codec`]: Utilities for encoding and decoding protocol frames.
+
+* [`tokio-io`]: Asynchronous I/O related traits and utilities.
+
+* [`tokio-macros`]: Macros for usage with Tokio.
+
+* [`tokio-net`]: Event loop that drives I/O resources as well as TCP, UDP, and
+  unix domain socket apis.
+
+* [ `tokio-timer`]: Time related APIs.
+
+[`tokio-codec`]: tokio-codec
+[`tokio-current-thread`]: tokio-current-thread
+[`tokio-executor`]: tokio-executor
+[`tokio-fs`]: tokio-fs
+[`tokio-io`]: tokio-io
+[`tokio-macros`]: tokio-macros
+[`tokio-net`]: tokio-net
+[`tokio-timer`]: tokio-timer
+
+## Related Projects
+
+In addition to the crates in this repository, the Tokio project also maintains
+several other libraries, including:
+
+* [`tracing`] (formerly `tokio-trace`): A framework for application-level
+  tracing and async-aware diagnostics.
+
+* [`mio`]: A low-level, cross-platform abstraction over OS I/O APIs that powers
+  `tokio`.
+
+* [`bytes`]: Utilities for working with bytes, including efficient byte buffers.
+
+[`tracing`]: https://github.com/tokio-rs/tracing
+[`mio`]: https://github.com/tokio-rs/mio
+[`bytes`]: https://github.com/tokio-rs/bytes
+
 ## Supported Rust Versions
 
 Tokio is built against the latest stable, nightly, and beta Rust releases. The