From 51e9e1500b18a5ce55f90085f1397ef8f6c3d1cf Mon Sep 17 00:00:00 2001 From: Rob Ede <robjtede@icloud.com> Date: Wed, 6 Jan 2021 18:52:06 +0000 Subject: [PATCH] add docs to recent additions --- actix-http/src/h1/dispatcher.rs | 16 ++++++++-------- actix-http/src/h1/service.rs | 14 +++++++------- actix-http/src/h2/dispatcher.rs | 6 +++--- actix-http/src/h2/service.rs | 8 ++++---- actix-http/src/lib.rs | 9 ++++++--- actix-http/src/service.rs | 18 +++++++++--------- 6 files changed, 37 insertions(+), 34 deletions(-) diff --git a/actix-http/src/h1/dispatcher.rs b/actix-http/src/h1/dispatcher.rs index 60552d10..a914880c 100644 --- a/actix-http/src/h1/dispatcher.rs +++ b/actix-http/src/h1/dispatcher.rs @@ -91,7 +91,7 @@ where U: Service<(Request, Framed<T, Codec>), Response = ()>, U::Error: fmt::Display, { - services: Rc<RefCell<HttpFlow<S, X, U>>>, + flow: Rc<RefCell<HttpFlow<S, X, U>>>, on_connect_data: OnConnectData, flags: Flags, peer_addr: Option<net::SocketAddr>, @@ -230,7 +230,7 @@ where io: Some(io), codec, read_buf, - services, + flow: services, on_connect_data, flags, peer_addr, @@ -384,7 +384,7 @@ where Poll::Ready(Ok(req)) => { self.as_mut().send_continue(); this = self.as_mut().project(); - let fut = this.services.borrow_mut().service.call(req); + let fut = this.flow.borrow_mut().service.call(req); this.state.set(State::ServiceCall(fut)); continue; } @@ -474,12 +474,12 @@ where if req.head().expect() { // set dispatcher state so the future is pinned. let mut this = self.as_mut().project(); - let task = this.services.borrow_mut().expect.call(req); + let task = this.flow.borrow_mut().expect.call(req); this.state.set(State::ExpectCall(task)); } else { // the same as above. let mut this = self.as_mut().project(); - let task = this.services.borrow_mut().service.call(req); + let task = this.flow.borrow_mut().service.call(req); this.state.set(State::ServiceCall(task)); }; @@ -492,7 +492,7 @@ where Poll::Ready(Ok(req)) => { self.as_mut().send_continue(); let mut this = self.as_mut().project(); - let task = this.services.borrow_mut().service.call(req); + let task = this.flow.borrow_mut().service.call(req); this.state.set(State::ServiceCall(task)); continue; } @@ -564,7 +564,7 @@ where this.on_connect_data.merge_into(&mut req); if pl == MessageType::Stream - && this.services.borrow().upgrade.is_some() + && this.flow.borrow().upgrade.is_some() { this.messages.push_back(DispatcherMessage::Upgrade(req)); break; @@ -830,7 +830,7 @@ where parts.write_buf = mem::take(inner_p.write_buf); let framed = Framed::from_parts(parts); let upgrade = inner_p - .services + .flow .borrow_mut() .upgrade .take() diff --git a/actix-http/src/h1/service.rs b/actix-http/src/h1/service.rs index 19272c13..067c8b64 100644 --- a/actix-http/src/h1/service.rs +++ b/actix-http/src/h1/service.rs @@ -367,7 +367,7 @@ where X: Service<Request>, U: Service<(Request, Framed<T, Codec>)>, { - services: Rc<RefCell<HttpFlow<S, X, U>>>, + flow: Rc<RefCell<HttpFlow<S, X, U>>>, on_connect_ext: Option<Rc<ConnectCallback<T>>>, cfg: ServiceConfig, _phantom: PhantomData<B>, @@ -392,7 +392,7 @@ where on_connect_ext: Option<Rc<ConnectCallback<T>>>, ) -> H1ServiceHandler<T, S, B, X, U> { H1ServiceHandler { - services: HttpFlow::new(service, expect, upgrade), + flow: HttpFlow::new(service, expect, upgrade), cfg, on_connect_ext, _phantom: PhantomData, @@ -418,8 +418,8 @@ where type Future = Dispatcher<T, S, B, X, U>; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { - let mut services = self.services.borrow_mut(); - let ready = services + let mut flow = self.flow.borrow_mut(); + let ready = flow .expect .poll_ready(cx) .map_err(|e| { @@ -429,7 +429,7 @@ where })? .is_ready(); - let ready = services + let ready = flow .service .poll_ready(cx) .map_err(|e| { @@ -440,7 +440,7 @@ where .is_ready() && ready; - let ready = if let Some(ref mut upg) = services.upgrade { + let ready = if let Some(ref mut upg) = flow.upgrade { upg.poll_ready(cx) .map_err(|e| { let e = e.into(); @@ -467,7 +467,7 @@ where Dispatcher::new( io, self.cfg.clone(), - self.services.clone(), + self.flow.clone(), on_connect_data, addr, ) diff --git a/actix-http/src/h2/dispatcher.rs b/actix-http/src/h2/dispatcher.rs index 62103586..959c34f1 100644 --- a/actix-http/src/h2/dispatcher.rs +++ b/actix-http/src/h2/dispatcher.rs @@ -37,7 +37,7 @@ where S: Service<Request>, B: MessageBody, { - services: Rc<RefCell<HttpFlow<S, X, U>>>, + flow: Rc<RefCell<HttpFlow<S, X, U>>>, connection: Connection<T, Bytes>, on_connect_data: OnConnectData, config: ServiceConfig, @@ -80,7 +80,7 @@ where }; Dispatcher { - services, + flow: services, config, peer_addr, connection, @@ -138,7 +138,7 @@ where let svc = ServiceResponse::<S::Future, S::Response, S::Error, B> { state: ServiceResponseState::ServiceCall( - this.services.borrow_mut().service.call(req), + this.flow.borrow_mut().service.call(req), Some(res), ), config: this.config.clone(), diff --git a/actix-http/src/h2/service.rs b/actix-http/src/h2/service.rs index f94aae79..95ff3de2 100644 --- a/actix-http/src/h2/service.rs +++ b/actix-http/src/h2/service.rs @@ -249,7 +249,7 @@ pub struct H2ServiceHandler<T, S, B> where S: Service<Request>, { - services: Rc<RefCell<HttpFlow<S, (), ()>>>, + flow: Rc<RefCell<HttpFlow<S, (), ()>>>, cfg: ServiceConfig, on_connect_ext: Option<Rc<ConnectCallback<T>>>, _phantom: PhantomData<B>, @@ -269,7 +269,7 @@ where service: S, ) -> H2ServiceHandler<T, S, B> { H2ServiceHandler { - services: HttpFlow::new(service, (), None), + flow: HttpFlow::new(service, (), None), cfg, on_connect_ext, _phantom: PhantomData, @@ -291,7 +291,7 @@ where type Future = H2ServiceHandlerResponse<T, S, B>; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { - self.services + self.flow .borrow_mut() .service .poll_ready(cx) @@ -308,7 +308,7 @@ where H2ServiceHandlerResponse { state: State::Handshake( - Some(self.services.clone()), + Some(self.flow.clone()), Some(self.cfg.clone()), addr, on_connect_data, diff --git a/actix-http/src/lib.rs b/actix-http/src/lib.rs index 0c58df2e..3879bae8 100644 --- a/actix-http/src/lib.rs +++ b/actix-http/src/lib.rs @@ -72,7 +72,7 @@ pub mod http { pub use crate::message::ConnectionType; } -/// Http protocol +/// HTTP protocol #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] pub enum Protocol { Http1, @@ -82,6 +82,9 @@ pub enum Protocol { type ConnectCallback<IO> = dyn Fn(&IO, &mut Extensions); /// Container for data that extract with ConnectCallback. +/// +/// # Implementation Details +/// Uses Option to reduce necessary allocations when merging with request extensions. pub(crate) struct OnConnectData(Option<Extensions>); impl Default for OnConnectData { @@ -91,7 +94,7 @@ impl Default for OnConnectData { } impl OnConnectData { - // construct self from io. + /// Construct by calling the on-connect callback with the underlying transport I/O. pub(crate) fn from_io<T>( io: &T, on_connect_ext: Option<&ConnectCallback<T>>, @@ -105,7 +108,7 @@ impl OnConnectData { Self(ext) } - // merge self to given request's head extension. + /// Merge self into given request's extensions. #[inline] pub(crate) fn merge_into(&mut self, req: &mut Request) { if let Some(ref mut ext) = self.0 { diff --git a/actix-http/src/service.rs b/actix-http/src/service.rs index eb16a6e7..e137ab6f 100644 --- a/actix-http/src/service.rs +++ b/actix-http/src/service.rs @@ -441,13 +441,13 @@ where X: Service<Request>, U: Service<(Request, Framed<T, h1::Codec>)>, { - services: Rc<RefCell<HttpFlow<S, X, U>>>, + flow: Rc<RefCell<HttpFlow<S, X, U>>>, cfg: ServiceConfig, on_connect_ext: Option<Rc<ConnectCallback<T>>>, _phantom: PhantomData<B>, } -// a collection of service for http. +/// A collection of services that describe an HTTP request flow. pub(super) struct HttpFlow<S, X, U> { pub(super) service: S, pub(super) expect: X, @@ -486,7 +486,7 @@ where HttpServiceHandler { cfg, on_connect_ext, - services: HttpFlow::new(service, expect, upgrade), + flow: HttpFlow::new(service, expect, upgrade), _phantom: PhantomData, } } @@ -511,8 +511,8 @@ where type Future = HttpServiceHandlerResponse<T, S, B, X, U>; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { - let mut services = self.services.borrow_mut(); - let ready = services + let mut flow = self.flow.borrow_mut(); + let ready = flow .expect .poll_ready(cx) .map_err(|e| { @@ -522,7 +522,7 @@ where })? .is_ready(); - let ready = services + let ready = flow .service .poll_ready(cx) .map_err(|e| { @@ -533,7 +533,7 @@ where .is_ready() && ready; - let ready = if let Some(ref mut upg) = services.upgrade { + let ready = if let Some(ref mut upg) = flow.upgrade { upg.poll_ready(cx) .map_err(|e| { let e = e.into(); @@ -565,7 +565,7 @@ where state: State::H2Handshake(Some(( server::handshake(io), self.cfg.clone(), - self.services.clone(), + self.flow.clone(), on_connect_data, peer_addr, ))), @@ -575,7 +575,7 @@ where state: State::H1(h1::Dispatcher::new( io, self.cfg.clone(), - self.services.clone(), + self.flow.clone(), on_connect_data, peer_addr, )),