refactor

Author: Byron

crate-status.md

@@ -415,7 +415,7 @@ A utility crate with types and functionality related to shallow-file handling.
 * [x] decode (zero-copy)
 * [x] [error line](https://github.com/git/git/blob/master/Documentation/technical/pack-protocol.txt#L28:L28)
 * [x] [V2 additions](https://github.com/git/git/blob/master/Documentation/technical/protocol-v2.txt#L35:L36)
-* [x] [side-band mode](https://github.com/git/git/blob/master/Documentation/technical/pack-protocol.txt#L467:L467)
+* [x] [sideband mode](https://github.com/git/git/blob/master/Documentation/technical/pack-protocol.txt#L467:L467)
 * [x] `Read` from packet line with (optional) progress support via sidebands
 * [x] `Write` with built-in packet line encoding
 * [x] `async` support

gix-packetline/src/async_io/encode.rs

@@ -209,14 +209,14 @@ pub async fn flush_to_write(mut out: impl AsyncWrite + Unpin) -> io::Result<usiz
     Ok(4)
 }
 
-/// Write `data` of `kind` to `out` using side-band encoding.
+/// Write `data` of `kind` to `out` using sideband encoding.
 pub async fn band_to_write(kind: Channel, data: &[u8], out: impl AsyncWrite + Unpin) -> io::Result<usize> {
     prefixed_data_to_write(&[kind as u8], data, out).await
 }
 
-/// Serialize this instance to `out`, returning the amount of bytes written.
+/// Serialize `band` to `out`, returning the amount of bytes written.
 ///
-/// The data written to `out` can be decoded with [`Borrowed::decode_band()]`.
+/// The data written to `out` can be decoded with [`crate::PacketLineRef::decode_band()`].
 pub async fn write_band(band: &BandRef<'_>, out: impl AsyncWrite + Unpin) -> io::Result<usize> {
     match band {
         BandRef::Data(d) => band_to_write(Channel::Data, d, out),
@@ -226,19 +226,19 @@ pub async fn write_band(band: &BandRef<'_>, out: impl AsyncWrite + Unpin) -> io:
     .await
 }
 
-/// Serialize this instance to `out`, appending a newline if there is none, returning the amount of bytes written.
+/// Serialize `band` to `out`, appending a newline if there is none, returning the amount of bytes written.
 pub async fn write_text(text: &TextRef<'_>, out: impl AsyncWrite + Unpin) -> io::Result<usize> {
     text_to_write(text.0, out).await
 }
 
-/// Serialize this line as error to `out`.
+/// Serialize `error` to `out`.
 ///
-/// This includes a marker to allow decoding it outside of a side-band channel, returning the amount of bytes written.
+/// This includes a marker to allow decoding it outside a sideband channel, returning the amount of bytes written.
 pub async fn write_error(error: &ErrorRef<'_>, out: impl AsyncWrite + Unpin) -> io::Result<usize> {
     error_to_write(error.0, out).await
 }
 
-/// Serialize this instance to `out` in git `packetline` format, returning the amount of bytes written to `out`.
+/// Serialize `line` to `out` in git `packetline` format, returning the amount of bytes written to `out`.
 pub async fn write_packet_line(line: &PacketLineRef<'_>, out: impl AsyncWrite + Unpin) -> io::Result<usize> {
     match line {
         PacketLineRef::Data(d) => data_to_write(d, out).await,

gix-packetline/src/async_io/read.rs

@@ -10,12 +10,12 @@ use futures_lite::AsyncReadExt;
 pub use super::sidebands::WithSidebands;
 use crate::{
     decode,
-    read::{ExhaustiveOutcome, ProgressAction},
-    PacketLineRef, StreamingPeekableIterState, MAX_LINE_LEN, U16_HEX_BYTES,
+    read::{ExhaustiveOutcome, ProgressAction, StreamingPeekableIterState},
+    PacketLineRef, MAX_LINE_LEN, U16_HEX_BYTES,
 };
 
 /// Read pack lines one after another, without consuming more than needed from the underlying
-/// [`AsyncRead`]. [`Flush`][PacketLineRef::Flush] lines cause the reader to stop producing lines forever,
+/// [`AsyncRead`]. [`Flush`](PacketLineRef::Flush) lines cause the reader to stop producing lines forever,
 /// leaving [`AsyncRead`] at the start of whatever comes next.
 ///
 /// This implementation tries hard not to allocate at all which leads to quite some added complexity and plenty of extra memory copies.
@@ -36,7 +36,6 @@ where
         }
     }
 
-    #[allow(clippy::needless_lifetimes)] // TODO: remove once this is clippy false positive is fixed
     async fn read_line_inner<'a>(
         reader: &mut T,
         buf: &'a mut [u8],
@@ -127,33 +126,32 @@ where
     /// Returns `None` if the end of iteration is reached because of one of the following:
     ///
     ///  * natural EOF
-    ///  * ERR packet line encountered if [`fail_on_err_lines()`][StreamingPeekableIter::fail_on_err_lines()] is true.
+    ///  * ERR packet line encountered if [`fail_on_err_lines()`](StreamingPeekableIterState::fail_on_err_lines()) is true.
     ///  * A `delimiter` packet line encountered
     pub async fn read_line(&mut self) -> Option<io::Result<Result<PacketLineRef<'_>, decode::Error>>> {
-        if self.state.is_done {
+        let state = &mut self.state;
+        if state.is_done {
             return None;
         }
-        if !self.state.peek_buf.is_empty() {
-            std::mem::swap(&mut self.state.peek_buf, &mut self.state.buf);
-            self.state.peek_buf.clear();
-            Some(Ok(Ok(
-                crate::decode(&self.state.buf).expect("only valid data in peek buf")
-            )))
+        if !state.peek_buf.is_empty() {
+            std::mem::swap(&mut state.peek_buf, &mut state.buf);
+            state.peek_buf.clear();
+            Some(Ok(Ok(crate::decode(&state.buf).expect("only valid data in peek buf"))))
         } else {
-            if self.state.buf.len() != MAX_LINE_LEN {
-                self.state.buf.resize(MAX_LINE_LEN, 0);
+            if state.buf.len() != MAX_LINE_LEN {
+                state.buf.resize(MAX_LINE_LEN, 0);
             }
             let (is_done, stopped_at, res) = Self::read_line_inner_exhaustive(
-                &mut self.state.read,
-                &mut self.state.buf,
-                self.state.delimiters,
-                self.state.fail_on_err_lines,
+                &mut state.read,
+                &mut state.buf,
+                state.delimiters,
+                state.fail_on_err_lines,
                 false,
-                self.state.trace,
+                state.trace,
             )
             .await;
-            self.state.is_done = is_done;
-            self.state.stopped_at = stopped_at;
+            state.is_done = is_done;
+            state.stopped_at = stopped_at;
             res
         }
     }
@@ -163,56 +161,55 @@ where
     ///
     /// Multiple calls to peek will return the same packet line, if there is one.
     pub async fn peek_line(&mut self) -> Option<io::Result<Result<PacketLineRef<'_>, decode::Error>>> {
-        if self.state.is_done {
+        let state = &mut self.state;
+        if state.is_done {
             return None;
         }
-        if self.state.peek_buf.is_empty() {
-            self.state.peek_buf.resize(MAX_LINE_LEN, 0);
+        if state.peek_buf.is_empty() {
+            state.peek_buf.resize(MAX_LINE_LEN, 0);
             let (is_done, stopped_at, res) = Self::read_line_inner_exhaustive(
-                &mut self.state.read,
-                &mut self.state.peek_buf,
-                self.state.delimiters,
-                self.state.fail_on_err_lines,
+                &mut state.read,
+                &mut state.peek_buf,
+                state.delimiters,
+                state.fail_on_err_lines,
                 true,
-                self.state.trace,
+                state.trace,
             )
             .await;
-            self.state.is_done = is_done;
-            self.state.stopped_at = stopped_at;
+            state.is_done = is_done;
+            state.stopped_at = stopped_at;
             res
         } else {
-            Some(Ok(Ok(
-                crate::decode(&self.state.peek_buf).expect("only valid data here")
-            )))
+            Some(Ok(Ok(crate::decode(&state.peek_buf).expect("only valid data here"))))
         }
     }
 
-    /// Same as [`as_read_with_sidebands(…)`][StreamingPeekableIter::as_read_with_sidebands()], but for channels without side band support.
+    /// Same as [`as_read_with_sidebands(…)`](StreamingPeekableIter::as_read_with_sidebands()), but for channels without side band support.
     ///
     /// Due to the preconfigured function type this method can be called without 'turbofish'.
     #[allow(clippy::type_complexity)]
     pub fn as_read(&mut self) -> WithSidebands<'_, T, fn(bool, &[u8]) -> ProgressAction> {
         WithSidebands::new(self)
     }
 
-    /// Return this instance as implementor of [`Read`][io::Read] assuming side bands to be used in all received packet lines.
-    /// Each invocation of [`read_line()`][io::BufRead::read_line()] returns a packet line.
+    /// Return this instance as implementor of [`Read`](io::Read) assuming sidebands to be used in all received packet lines.
+    /// Each invocation of [`read_line()`](io::BufRead::read_line()) returns a packet line.
     ///
     /// Progress or error information will be passed to the given `handle_progress(is_error, text)` function, with `is_error: bool`
     /// being true in case the `text` is to be interpreted as error.
     ///
-    /// _Please note_ that side bands need to be negotiated with the server.
+    /// _Please note_ that sidebands need to be negotiated with the server.
     pub fn as_read_with_sidebands<F: FnMut(bool, &[u8]) -> ProgressAction + Unpin>(
         &mut self,
         handle_progress: F,
     ) -> WithSidebands<'_, T, F> {
         WithSidebands::with_progress_handler(self, handle_progress)
     }
 
-    /// Same as [`as_read_with_sidebands(…)`][StreamingPeekableIter::as_read_with_sidebands()], but for channels without side band support.
+    /// Same as [`as_read_with_sidebands(…)`](StreamingPeekableIter::as_read_with_sidebands()), but for channels without side band support.
     ///
     /// The type parameter `F` needs to be configured for this method to be callable using the 'turbofish' operator.
-    /// Use [`as_read()`][StreamingPeekableIter::as_read()].
+    /// Use [`as_read()`](StreamingPeekableIter::as_read()).
     pub fn as_read_without_sidebands<F: FnMut(bool, &[u8]) -> ProgressAction + Unpin>(
         &mut self,
     ) -> WithSidebands<'_, T, F> {

gix-packetline/src/async_io/sidebands.rs

@@ -10,8 +10,8 @@ use super::read::StreamingPeekableIter;
 use crate::{decode, read::ProgressAction, BandRef, PacketLineRef, TextRef, U16_HEX_BYTES};
 
 type ReadLineResult<'a> = Option<std::io::Result<Result<PacketLineRef<'a>, decode::Error>>>;
-/// An implementor of [`AsyncBufRead`] yielding packet lines on each call to [`read_line()`][AsyncBufRead::read_line()].
-/// It's also possible to hide the underlying packet lines using the [`Read`][AsyncRead] implementation which is useful
+/// An implementor of [`AsyncBufRead`] yielding packet lines on each call to `read_line()`.
+/// It's also possible to hide the underlying packet lines using the [`Read`](AsyncRead) implementation which is useful
 /// if they represent binary data, like the one of a pack file.
 pub struct WithSidebands<'a, T, F>
 where
@@ -32,7 +32,6 @@ where
             parent
                 .as_mut()
                 .expect("parent is always available if we are idle")
-                .state
                 .reset();
         }
     }
@@ -101,25 +100,23 @@ where
         }
     }
 
-    /// Forwards to the parent [`StreamingPeekableIter::reset_with()`]
+    /// Forwards to the parent [`StreamingPeekableIter::reset_with()`](crate::read::StreamingPeekableIterState::reset_with()).
     pub fn reset_with(&mut self, delimiters: &'static [PacketLineRef<'static>]) {
         if let State::Idle { ref mut parent } = self.state {
             parent
                 .as_mut()
                 .expect("parent is always available if we are idle")
-                .state
                 .reset_with(delimiters);
         }
     }
 
-    /// Forwards to the parent [`StreamingPeekableIter::stopped_at()`]
+    /// Forwards to the parent [`StreamingPeekableIterState::stopped_at()`](crate::read::StreamingPeekableIterState::stopped_at()).
     pub fn stopped_at(&self) -> Option<PacketLineRef<'static>> {
         match self.state {
             State::Idle { ref parent } => {
                 parent
                     .as_ref()
                     .expect("parent is always available if we are idle")
-                    .state
                     .stopped_at
             }
             _ => None,
@@ -132,7 +129,7 @@ where
     }
 
     /// Effectively forwards to the parent [`StreamingPeekableIter::peek_line()`], allowing to see what would be returned
-    /// next on a call to [`read_line()`][io::BufRead::read_line()].
+    /// next on a call to `read_line()`.
     ///
     /// # Warning
     ///
@@ -331,9 +328,7 @@ where
         }
         let range = self.pos..self.cap;
         match &self.get_mut().state {
-            State::Idle { parent } => {
-                Poll::Ready(Ok(&parent.as_ref().expect("parent always available").state.buf[range]))
-            }
+            State::Idle { parent } => Poll::Ready(Ok(&parent.as_ref().expect("parent always available").buf[range])),
             State::ReadLine { .. } => unreachable!("at least in theory"),
         }
     }

gix-packetline/src/blocking_io/encode.rs

@@ -26,21 +26,21 @@ pub fn error_to_write(message: &[u8], out: impl io::Write) -> io::Result<usize>
     prefixed_data_to_write(ERR_PREFIX, message, out)
 }
 
-/// Serialize this line as error to `out`.
+/// Serialize `error` to `out`.
 ///
-/// This includes a marker to allow decoding it outside a side-band channel, returning the amount of bytes written.
+/// This includes a marker to allow decoding it outside a sideband channel, returning the amount of bytes written.
 pub fn write_error(error: &ErrorRef<'_>, out: impl io::Write) -> io::Result<usize> {
     error_to_write(error.0, out)
 }
 
-/// Write `data` of `kind` to `out` using side-band encoding.
+/// Write `data` of `kind` to `out` using sideband encoding.
 pub fn band_to_write(kind: Channel, data: &[u8], out: impl io::Write) -> io::Result<usize> {
     prefixed_data_to_write(&[kind as u8], data, out)
 }
 
-/// Serialize [`BandRef`] to `out`, returning the amount of bytes written.
+/// Serialize `band` to `out`, returning the amount of bytes written.
 ///
-/// The data written to `out` can be decoded with [`Borrowed::decode_band()]`.
+/// The data written to `out` can be decoded with [`PacketLineRef::decode_band()`].
 pub fn write_band(band: &BandRef<'_>, out: impl io::Write) -> io::Result<usize> {
     match band {
         BandRef::Data(d) => band_to_write(Channel::Data, d, out),
@@ -54,7 +54,7 @@ pub fn data_to_write(data: &[u8], out: impl io::Write) -> io::Result<usize> {
     prefixed_data_to_write(&[], data, out)
 }
 
-/// Serialize this instance to `out` in git `packetline` format, returning the amount of bytes written to `out`.
+/// Serialize `line` to `out` in git `packetline` format, returning the amount of bytes written to `out`.
 pub fn write_packet_line(line: &PacketLineRef<'_>, out: impl io::Write) -> io::Result<usize> {
     match line {
         PacketLineRef::Data(d) => data_to_write(d, out),
@@ -69,7 +69,7 @@ pub fn text_to_write(text: &[u8], out: impl io::Write) -> io::Result<usize> {
     prefixed_and_suffixed_data_to_write(&[], text, b"\n", out)
 }
 
-/// Serialize this instance to `out`, appending a newline if there is none, returning the amount of bytes written.
+/// Serialize `text` to `out`, appending a newline if there is none, returning the amount of bytes written.
 pub fn write_text(text: &TextRef<'_>, out: impl io::Write) -> io::Result<usize> {
     text_to_write(text.0, out)
 }