diff --git a/actix-http/CHANGES.md b/actix-http/CHANGES.md index 598ef9c0e..806e32cc0 100644 --- a/actix-http/CHANGES.md +++ b/actix-http/CHANGES.md @@ -1,12 +1,19 @@ # Changes ## Unreleased - 2021-xx-xx +### Added +* New method on `MessageBody` trait, `try_into_bytes`, with default implementation, for optimizations on body types that complete in exactly one poll. Replaces `is_complete_body` and `take_complete_body`. [#2522] + ### Changed * Rename trait `IntoHeaderPair => TryIntoHeaderPair`. [#2510] * Rename `TryIntoHeaderPair::{try_into_header_pair => try_into_pair}`. [#2510] * Rename trait `IntoHeaderValue => TryIntoHeaderValue`. [#2510] +### Removed +* `MessageBody::{is_complete_body,take_complete_body}`. [#2522] + [#2510]: https://github.com/actix/actix-web/pull/2510 +[#2522]: https://github.com/actix/actix-web/pull/2522 ## 3.0.0-beta.15 - 2021-12-11 @@ -27,7 +34,7 @@ * `Request::take_conn_data()`. [#2491] * `Request::take_req_data()`. [#2487] * `impl Clone` for `RequestHead`. [#2487] -* New methods on `MessageBody` trait, `is_complete_body` and `take_complete_body`, both with default implementations, for optimisations on body types that are done in exactly one poll/chunk. [#2497] +* New methods on `MessageBody` trait, `is_complete_body` and `take_complete_body`, both with default implementations, for optimizations on body types that are done in exactly one poll/chunk. [#2497] * New `boxed` method on `MessageBody` trait for wrapping body type. [#2520] ### Changed diff --git a/actix-http/src/body/message_body.rs b/actix-http/src/body/message_body.rs index cf65bac2d..0a605a69a 100644 --- a/actix-http/src/body/message_body.rs +++ b/actix-http/src/body/message_body.rs @@ -17,11 +17,15 @@ use super::{BodySize, BoxBody}; /// An interface types that can converted to bytes and used as response bodies. // TODO: examples pub trait MessageBody { - // TODO: consider this bound to only fmt::Display since the error type is not really used - // and there is an impl for Into> on String + /// The type of error that will be returned if streaming body fails. + /// + /// Since it is not appropriate to generate a response mid-stream, it only requires `Error` for + /// internal use and logging. type Error: Into>; /// Body size hint. + /// + /// If [`BodySize::None`] is returned, optimizations that skip reading the body are allowed. fn size(&self) -> BodySize; /// Attempt to pull out the next chunk of body bytes. @@ -31,9 +35,17 @@ pub trait MessageBody { cx: &mut Context<'_>, ) -> Poll>>; - /// Convert this body into `Bytes`. + /// Try to convert into the complete chunk of body bytes. /// - /// Body types with `BodySize::None` are allowed to return empty `Bytes`. + /// Implement this method if the entire body can be trivially extracted. This is useful for + /// optimizations where `poll_next` calls can be avoided. + /// + /// Body types with [`BodySize::None`] are allowed to return empty `Bytes`. Although, if calling + /// this method, it is recommended to check `size` first and return early. + /// + /// # Errors + /// The default implementation will error and return the original type back to the caller for + /// further use. #[inline] fn try_into_bytes(self) -> Result where diff --git a/actix-http/src/response.rs b/actix-http/src/response.rs index aee9e80b4..a0e6d9b7c 100644 --- a/actix-http/src/response.rs +++ b/actix-http/src/response.rs @@ -170,7 +170,7 @@ impl Response { /// Returns split head and body. /// /// # Implementation Notes - /// Due to internal performance optimisations, the first element of the returned tuple is a + /// Due to internal performance optimizations, the first element of the returned tuple is a /// `Response` as well but only contains the head of the response this was called on. pub fn into_parts(self) -> (Response<()>, B) { self.replace_body(())