update docs

examples/handlers/README.md

@@ -18,6 +18,7 @@ We recommend reviewing our handler examples in the order shown below:
 1. [Request Data](request_data) - Accessing common request information
 1. [Stateful Handlers](stateful) - Keeping state in a handler
 1. [Simple Async Handlers](simple_async_handlers) - Async Request Handlers 101
+1. [Simple Async Handlers (.await version)](simple_async_handlers_await) - Request Handlers that use async/.await
 1. [Async Handlers](async_handlers) - More complicated async request handlers
 
 ## Help

examples/handlers/simple_async_handlers/README.md

@@ -24,6 +24,9 @@ find yourself doing lots of CPU/memory intensive operations on the web server,
 then futures are probably not going to help your performance, and you might be
 better off spawning a new thread per request.
 
+If you came here looking for an example that uses async/.await, please read
+[Async Request Handlers (.await version)](../simple_async_handlers).
+
 ## Running
 
 From the `examples/handlers/async_handlers` directory:

examples/handlers/simple_async_handlers_await/README.md

@@ -1,28 +1,15 @@
-# Async Request Handlers
+# Async Request Handlers (.await version)
 
 The idea of async handlers has already been introduced by the post_handler example in
 [Request Data](../request_data), which waits for the POST body asyncronously, and resolves
-the response future once it has processed the body.
-
-This example contains a pair of endpoints that sleep for a number of seconds,
-in different ways. Note that we never call `std::thread::sleep` in this example,
-so none of our request handlers block the thread from handling other requests
-in parallel. Instead, in each case, we return a future, which will resolve when
-the requested time has elapsed, and cause Gotham to respond to the http request.
-
-The approach of using futures to track the status of long-running operations
-is significantly lower overhead than that of spawning a new thread per request.
-In our case, the long-running operations are sleeps, but in
-[Async Handlers](../async_handlers), the long-running operations are http
-requests.
-
-You will often find that most of the time that a web server spends dealing
-with a web request, it is waiting on another service (e.g. a database, or an
-external api). If you can track these operations using futures, you should end
-up with a very lightweight and performant web server. On the other hand, if you
-find yourself doing lots of CPU/memory intensive operations on the web server,
-then futures are probably not going to help your performance, and you might be
-better off spawning a new thread per request.
+the response future once it has processed the body. The combinator-based version
+of this example can be found at [Async Request Handlers](../simple_async_handlers).
+
+This example has exactly the same behavior and API as the combinator-based version,
+and it can be used as a reference when converting your code to use async/await.
+It also leaves the versions of gotham, tokio and hyper the same, and uses the
+compatibility helpers from the `futures` crate to convert things at the
+interface boundaries.
 
 ## Running