From e575d35da2dde16ee487e2e6904c43e0b0d43661 Mon Sep 17 00:00:00 2001 From: Matt Fellenz Date: Fri, 15 Apr 2022 08:26:12 -0700 Subject: [PATCH 1/3] Improve documentation for FromRequest::Future --- actix-web/src/extract.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/actix-web/src/extract.rs b/actix-web/src/extract.rs index 1b2f0bd197c..684afb0aa79 100644 --- a/actix-web/src/extract.rs +++ b/actix-web/src/extract.rs @@ -67,6 +67,10 @@ pub trait FromRequest: Sized { type Error: Into; /// Future that resolves to a Self. + /// + /// To refer to the type of an async function or block here, you have two options. + /// The first is to use a boxed future such as `futures::future::BoxFuture`. This works on stable and nightly. + /// The second is to use `impl Future`, which requires `#![feature(type_alias_impl_trait)]` so only works on nightly. type Future: Future>; /// Create a Self from request parts asynchronously. From cf71b847e778e09e7dc9127f8f8b67af1699f227 Mon Sep 17 00:00:00 2001 From: Matt Fellenz Date: Mon, 18 Apr 2022 10:54:01 -0700 Subject: [PATCH 2/3] Suggest LocalBoxFuture specifically --- actix-web/src/extract.rs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/actix-web/src/extract.rs b/actix-web/src/extract.rs index 684afb0aa79..88a401a3dff 100644 --- a/actix-web/src/extract.rs +++ b/actix-web/src/extract.rs @@ -68,9 +68,13 @@ pub trait FromRequest: Sized { /// Future that resolves to a Self. /// - /// To refer to the type of an async function or block here, you have two options. - /// The first is to use a boxed future such as `futures::future::BoxFuture`. This works on stable and nightly. - /// The second is to use `impl Future`, which requires `#![feature(type_alias_impl_trait)]` so only works on nightly. + /// To use an async function or block here, you can a boxed future such as `futures::future::LocalBoxFuture`. + /// This is an alias for a pinned Box, so you can create it with the following syntax: + /// ``` + /// Box::pin(async { + /// ... + /// }) + /// ``` type Future: Future>; /// Create a Self from request parts asynchronously. From a6420145652db48de65d0e2b707a122d6de9d64d Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Sat, 23 Apr 2022 20:58:32 +0100 Subject: [PATCH 3/3] tweak FromRequest::Future docs --- actix-web/src/extract.rs | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/actix-web/src/extract.rs b/actix-web/src/extract.rs index 88a401a3dff..9d9ca889ec9 100644 --- a/actix-web/src/extract.rs +++ b/actix-web/src/extract.rs @@ -66,21 +66,29 @@ pub trait FromRequest: Sized { /// The associated error which can be returned. type Error: Into; - /// Future that resolves to a Self. + /// Future that resolves to a `Self`. /// - /// To use an async function or block here, you can a boxed future such as `futures::future::LocalBoxFuture`. - /// This is an alias for a pinned Box, so you can create it with the following syntax: - /// ``` - /// Box::pin(async { - /// ... - /// }) + /// To use an async function or block, the futures must be boxed. The following snippet will be + /// common when creating async/await extractors (that do not consume the body). + /// + /// ```ignore + /// type Future = Pin>>>; + /// // or + /// type Future = futures_util::future::LocalBoxFuture<'static, Result>; + /// + /// fn from_request(req: HttpRequest, ...) -> Self::Future { + /// let req = req.clone(); + /// Box::pin(async move { + /// ... + /// }) + /// } /// ``` type Future: Future>; - /// Create a Self from request parts asynchronously. + /// Create a `Self` from request parts asynchronously. fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future; - /// Create a Self from request head asynchronously. + /// Create a `Self` from request head asynchronously. /// /// This method is short for `T::from_request(req, &mut Payload::None)`. fn extract(req: &HttpRequest) -> Self::Future {