Clarify 'Responder' async I/O usage in docs.

Resolves #2286.
This commit is contained in:
Sergio Benitez 2023-03-26 19:32:49 -07:00
parent 9c052be2dc
commit 372e9671eb
1 changed files with 9 additions and 2 deletions

View File

@ -106,8 +106,7 @@ use crate::request::Request;
/// ///
/// # Return Value /// # Return Value
/// ///
/// A `Responder` returns a `Future` whose output type is a `Result<Response, /// A `Responder` returns a `Result<Response, Status>`.
/// Status>`.
/// ///
/// * An `Ok(Response)` indicates success. The `Response` will be written out /// * An `Ok(Response)` indicates success. The `Response` will be written out
/// to the client. /// to the client.
@ -145,6 +144,14 @@ use crate::request::Request;
/// _handler_ from its type signature also becomes more difficult. You should /// _handler_ from its type signature also becomes more difficult. You should
/// avoid varying responses based on the `Request` value as much as possible. /// avoid varying responses based on the `Request` value as much as possible.
/// ///
/// 4. Perform `async` I/O in Constructors
///
/// The `Responder` trait is not an `async` trait. This is not an oversight.
/// Instead of performing `async` operations in what would be the
/// `respond_to` method, perform them in a constructor for the responder. As
/// an example, see [`NamedFile::open()`](crate::fs::NamedFile::open()),
/// which performs the requisite I/O for `NamedFile`'s responder.
///
/// ## Lifetimes /// ## Lifetimes
/// ///
/// `Responder` has two lifetimes: `Responder<'r, 'o: 'r>`. /// `Responder` has two lifetimes: `Responder<'r, 'o: 'r>`.