From d346a0db5f6aa2d51c20944b55073060cb44bf51 Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Tue, 18 Aug 2020 17:41:34 +0100 Subject: [PATCH] rename methods on Framed to better describe usage --- actix-codec/CHANGES.md | 3 + actix-codec/src/framed.rs | 134 +++++++++++++++++++------------------- actix-codec/src/lib.rs | 2 + 3 files changed, 71 insertions(+), 68 deletions(-) diff --git a/actix-codec/CHANGES.md b/actix-codec/CHANGES.md index aa873992..353e6bb7 100644 --- a/actix-codec/CHANGES.md +++ b/actix-codec/CHANGES.md @@ -5,6 +5,9 @@ * Upgrade `tokio-util` to `0.3`. * Improve `BytesCodec` `.encode()` performance * Simplify `BytesCodec` `.decode()` +* Rename methods on `Framed` to better describe their use. +* Add method on `Framed` to get a pinned reference to the underlying I/O. +* Add method on `Framed` check emptiness of read buffer. ## [0.2.0] - 2019-12-10 diff --git a/actix-codec/src/framed.rs b/actix-codec/src/framed.rs index bfa5c7b6..cf840949 100644 --- a/actix-codec/src/framed.rs +++ b/actix-codec/src/framed.rs @@ -23,6 +23,12 @@ bitflags::bitflags! { /// A unified `Stream` and `Sink` interface to an underlying I/O object, using /// the `Encoder` and `Decoder` traits to encode and decode frames. +/// +/// Raw I/O objects work with byte sequences, but higher-level code usually +/// wants to batch these into meaningful chunks, called "frames". This +/// method layers framing on top of an I/O object, by using the `Encoder`/`Decoder` +/// traits to handle encoding and decoding of message frames. Note that +/// the incoming and outgoing frame types may be distinct. #[pin_project] pub struct Framed { #[pin] @@ -38,15 +44,6 @@ where T: AsyncRead + AsyncWrite, U: Decoder, { - /// Provides a `Stream` and `Sink` interface for reading and writing to this - /// `Io` object, using `Decode` and `Encode` to read and write the raw data. - /// - /// Raw I/O objects work with byte sequences, but higher-level code usually - /// wants to batch these into meaningful chunks, called "frames". This - /// method layers framing on top of an I/O object, by using the `Codec` - /// traits to handle encoding and decoding of messages frames. Note that - /// the incoming and outgoing frame types may be distinct. - /// /// This function returns a *single* object that is both `Stream` and /// `Sink`; grouping this into a single object is often useful for layering /// things like gzip or TLS, which require both read and write access to the @@ -63,40 +60,13 @@ where } impl Framed { - /// Provides a `Stream` and `Sink` interface for reading and writing to this - /// `Io` object, using `Decode` and `Encode` to read and write the raw data. - /// - /// Raw I/O objects work with byte sequences, but higher-level code usually - /// wants to batch these into meaningful chunks, called "frames". This - /// method layers framing on top of an I/O object, by using the `Codec` - /// traits to handle encoding and decoding of messages frames. Note that - /// the incoming and outgoing frame types may be distinct. - /// - /// This function returns a *single* object that is both `Stream` and - /// `Sink`; grouping this into a single object is often useful for layering - /// things like gzip or TLS, which require both read and write access to the - /// underlying object. - /// - /// This objects takes a stream and a readbuffer and a writebuffer. These - /// field can be obtained from an existing `Framed` with the - /// `into_parts` method. - pub fn from_parts(parts: FramedParts) -> Framed { - Framed { - io: parts.io, - codec: parts.codec, - flags: parts.flags, - write_buf: parts.write_buf, - read_buf: parts.read_buf, - } - } - /// Returns a reference to the underlying codec. - pub fn get_codec(&self) -> &U { + pub fn codec_ref(&self) -> &U { &self.codec } /// Returns a mutable reference to the underlying codec. - pub fn get_codec_mut(&mut self) -> &mut U { + pub fn codec_mut(&mut self) -> &mut U { &mut self.codec } @@ -106,20 +76,29 @@ impl Framed { /// Note that care should be taken to not tamper with the underlying stream /// of data coming in as it may corrupt the stream of frames otherwise /// being worked with. - pub fn get_ref(&self) -> &T { + pub fn io_ref(&self) -> &T { &self.io } - /// Returns a mutable reference to the underlying I/O stream wrapped by - /// `Frame`. + /// Returns a mutable reference to the underlying I/O stream. /// /// Note that care should be taken to not tamper with the underlying stream /// of data coming in as it may corrupt the stream of frames otherwise /// being worked with. - pub fn get_mut(&mut self) -> &mut T { + pub fn io_mut(&mut self) -> &mut T { &mut self.io } + /// Returns a `Pin` of a mutable reference to the underlying I/O stream. + pub fn io_pin(self: Pin<&mut Self>) -> Pin<&mut T> { + self.project().io + } + + /// Check if read buffer is empty. + pub fn is_read_buf_empty(&self) -> bool { + self.read_buf.is_empty() + } + /// Check if write buffer is empty. pub fn is_write_buf_empty(&self) -> bool { self.write_buf.is_empty() @@ -130,8 +109,15 @@ impl Framed { self.write_buf.len() >= HW } + /// Check if framed is able to write more data. + /// + /// `Framed` object considers ready if there is free space in write buffer. + pub fn is_write_ready(&self) -> bool { + self.write_buf.len() < HW + } + /// Consume the `Frame`, returning `Frame` with different codec. - pub fn into_framed(self, codec: U2) -> Framed { + pub fn replace_codec(self, codec: U2) -> Framed { Framed { codec, io: self.io, @@ -142,7 +128,7 @@ impl Framed { } /// Consume the `Frame`, returning `Frame` with different io. - pub fn map_io(self, f: F) -> Framed + pub fn into_map_io(self, f: F) -> Framed where F: Fn(T) -> T2, { @@ -156,7 +142,7 @@ impl Framed { } /// Consume the `Frame`, returning `Frame` with different codec. - pub fn map_codec(self, f: F) -> Framed + pub fn into_map_codec(self, f: F) -> Framed where F: Fn(U) -> U2, { @@ -168,22 +154,6 @@ impl Framed { write_buf: self.write_buf, } } - - /// Consumes the `Frame`, returning its underlying I/O stream, the buffer - /// with unprocessed data, and the codec. - /// - /// Note that care should be taken to not tamper with the underlying stream - /// of data coming in as it may corrupt the stream of frames otherwise - /// being worked with. - pub fn into_parts(self) -> FramedParts { - FramedParts { - io: self.io, - codec: self.codec, - flags: self.flags, - read_buf: self.read_buf, - write_buf: self.write_buf, - } - } } impl Framed { @@ -203,13 +173,6 @@ impl Framed { Ok(()) } - /// Check if framed is able to write more data. - /// - /// `Framed` object considers ready if there is free space in write buffer. - pub fn is_write_ready(&self) -> bool { - self.write_buf.len() < HW - } - /// Try to read underlying I/O stream and decode item. pub fn next_item( mut self: Pin<&mut Self>, @@ -376,6 +339,41 @@ where } } +impl Framed { + /// This function returns a *single* object that is both `Stream` and + /// `Sink`; grouping this into a single object is often useful for layering + /// things like gzip or TLS, which require both read and write access to the + /// underlying object. + /// + /// These objects take a stream, a read buffer and a write buffer. These + /// fields can be obtained from an existing `Framed` with the `into_parts` method. + pub fn from_parts(parts: FramedParts) -> Framed { + Framed { + io: parts.io, + codec: parts.codec, + flags: parts.flags, + write_buf: parts.write_buf, + read_buf: parts.read_buf, + } + } + + /// Consumes the `Frame`, returning its underlying I/O stream, the buffer + /// with unprocessed data, and the codec. + /// + /// Note that care should be taken to not tamper with the underlying stream + /// of data coming in as it may corrupt the stream of frames otherwise + /// being worked with. + pub fn into_parts(self) -> FramedParts { + FramedParts { + io: self.io, + codec: self.codec, + flags: self.flags, + read_buf: self.read_buf, + write_buf: self.write_buf, + } + } +} + /// `FramedParts` contains an export of the data of a Framed transport. /// It can be used to construct a new `Framed` with a different codec. /// It contains all current buffers and the inner transport. diff --git a/actix-codec/src/lib.rs b/actix-codec/src/lib.rs index 3035be13..d972763e 100644 --- a/actix-codec/src/lib.rs +++ b/actix-codec/src/lib.rs @@ -8,7 +8,9 @@ //! [`AsyncWrite`]: AsyncWrite //! [`Sink`]: futures_sink::Sink //! [`Stream`]: futures_core::Stream + #![deny(rust_2018_idioms)] +#![warn(missing_docs)] mod bcodec; mod framed;