From 04ca92e05006369d0c9f56b35dcae1885af3b6e3 Mon Sep 17 00:00:00 2001 From: David Laban Date: Sat, 16 Nov 2019 11:32:39 +0000 Subject: [PATCH] update docs --- examples/handlers/README.md | 1 + .../handlers/simple_async_handlers/README.md | 3 ++ .../simple_async_handlers_await/README.md | 31 ++++++------------- 3 files changed, 13 insertions(+), 22 deletions(-) diff --git a/examples/handlers/README.md b/examples/handlers/README.md index 486ed38ed..fa98ba9a8 100644 --- a/examples/handlers/README.md +++ b/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 diff --git a/examples/handlers/simple_async_handlers/README.md b/examples/handlers/simple_async_handlers/README.md index c06af72b4..b0993ca1c 100644 --- a/examples/handlers/simple_async_handlers/README.md +++ b/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: diff --git a/examples/handlers/simple_async_handlers_await/README.md b/examples/handlers/simple_async_handlers_await/README.md index c06af72b4..ee8f9eb10 100644 --- a/examples/handlers/simple_async_handlers_await/README.md +++ b/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