Seeking heuristic tweaks

src/iter.rs

@@ -62,7 +62,7 @@ where
 pub struct ProgressBarIter<T> {
     pub(crate) it: T,
     pub progress: ProgressBar,
-    pub(crate) dejitter: MaxSeekHeuristic,
+    pub(crate) seek_max: SeekMax,
 }
 
 impl<T> ProgressBarIter<T> {
@@ -157,7 +157,7 @@ impl<R: io::Read> io::Read for ProgressBarIter<R> {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         let inc = self.it.read(buf)?;
         self.progress.set_position(
-            self.dejitter
+            self.seek_max
                 .update_seq(self.progress.position(), inc as u64),
         );
         Ok(inc)
@@ -166,7 +166,7 @@ impl<R: io::Read> io::Read for ProgressBarIter<R> {
     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
         let inc = self.it.read_vectored(bufs)?;
         self.progress.set_position(
-            self.dejitter
+            self.seek_max
                 .update_seq(self.progress.position(), inc as u64),
         );
         Ok(inc)
@@ -175,7 +175,7 @@ impl<R: io::Read> io::Read for ProgressBarIter<R> {
     fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
         let inc = self.it.read_to_string(buf)?;
         self.progress.set_position(
-            self.dejitter
+            self.seek_max
                 .update_seq(self.progress.position(), inc as u64),
         );
         Ok(inc)
@@ -184,7 +184,7 @@ impl<R: io::Read> io::Read for ProgressBarIter<R> {
     fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
         self.it.read_exact(buf)?;
         self.progress.set_position(
-            self.dejitter
+            self.seek_max
                 .update_seq(self.progress.position(), buf.len() as u64),
         );
         Ok(())
@@ -199,7 +199,7 @@ impl<R: io::BufRead> io::BufRead for ProgressBarIter<R> {
     fn consume(&mut self, amt: usize) {
         self.it.consume(amt);
         self.progress.set_position(
-            self.dejitter
+            self.seek_max
                 .update_seq(self.progress.position(), amt.try_into().unwrap()),
         );
     }
@@ -208,14 +208,13 @@ impl<R: io::BufRead> io::BufRead for ProgressBarIter<R> {
 impl<S: io::Seek> io::Seek for ProgressBarIter<S> {
     fn seek(&mut self, f: io::SeekFrom) -> io::Result<u64> {
         self.it.seek(f).map(|pos| {
-            // this kind of seek is used to find the current position, but does not alter it
-            // generally equivalent to stream_position()
-            if let io::SeekFrom::Current(0) = f {
-                pos
-            } else {
-                self.progress.set_position(self.dejitter.update_seek(pos));
-                pos
+            if f != io::SeekFrom::Current(0) {
+                // this kind of seek is used to find the current position, but does not alter it
+                // generally equivalent to stream_position()
+                self.progress.set_position(self.seek_max.update_seek(pos));
             }
+
+            pos
         })
     }
     // Pass this through to preserve optimizations that the inner I/O object may use here
@@ -227,28 +226,28 @@ impl<S: io::Seek> io::Seek for ProgressBarIter<S> {
 
 /// Calculates a more stable visual position from jittery seeks to show to the user.
 ///
-/// It does so by holding the maximum position encountered out of the last HISTORY read/write positions.
-/// As an optimization it deallocates the history when only sequential operations are performed RESET times in a row.
+/// Holds the maximum position encountered out of the last HISTORY read/write positions.
+/// Drops history when only sequential operations are performed RESET times in a row.
 #[derive(Debug, Default)]
-pub(crate) struct MaxSeekHeuristic<const RESET: u8 = 5, const HISTORY: usize = 10> {
+pub(crate) struct SeekMax<const RESET: u8 = 5, const HISTORY: usize = 10> {
     buf: Option<(Box<MaxRingBuf<HISTORY>>, u8)>,
 }
 
-impl<const RESET: u8, const HISTORY: usize> MaxSeekHeuristic<RESET, HISTORY> {
+impl<const RESET: u8, const HISTORY: usize> SeekMax<RESET, HISTORY> {
     fn update_seq(&mut self, prev_pos: u64, delta: u64) -> u64 {
         let new_pos = prev_pos + delta;
-        if let Some((buf, seq)) = &mut self.buf {
-            *seq += 1;
-            if *seq >= RESET {
-                self.buf = None;
-                return new_pos;
-            }
+        let Some((buf, seq)) = &mut self.buf else {
+            return new_pos;
+        };
 
-            buf.update(new_pos);
-            buf.max()
-        } else {
-            new_pos
+        *seq += 1;
+        if *seq >= RESET {
+            self.buf = None;
+            return new_pos;
         }
+
+        buf.update(new_pos);
+        buf.max()
     }
 
     fn update_seek(&mut self, newpos: u64) -> u64 {
@@ -262,41 +261,27 @@ impl<const RESET: u8, const HISTORY: usize> MaxSeekHeuristic<RESET, HISTORY> {
 }
 
 /// Ring buffer that remembers the maximum contained value.
-///
-/// can be used to quickly calculate the maximum value of a history of data points.
 #[derive(Debug)]
 struct MaxRingBuf<const HISTORY: usize = 10> {
     history: [u64; HISTORY],
-    // invariant_h: always a valid index into history
-    head: u8,
-    // invariant_m: always a valid index into history
-    max_pos: u8,
+    head: u8,    // must be < HISTORY
+    max_pos: u8, // must be < HISTORY
 }
 
 impl<const HISTORY: usize> MaxRingBuf<HISTORY> {
-    /// Adds a value to the history.
-    /// Updates internal bookkeeping to remember the maximum value.
+    /// Updates internal bookkeeping to remember the maximum value
     ///
-    /// # Performance:
-    /// amortized O(1):
-    /// each regular update is O(1).
-    /// Only updates that overwrite the position the maximum was stored in with a smaller number do a seek of the buffer,
-    /// searching for the new maximum.
-    /// This only happens on average each 1/HISTORY and has a cost of HISTORY,
-    /// therefore amortizing to O(1).
+    /// Updates that overwrite the position the maximum was stored in with a smaller number do a
+    /// seek of the buffer, searching for the new maximum. This only happens on average each
+    /// 1 / HISTORY and has a cost of HISTORY, therefore amortizing to O(1).
     ///
-    /// In case there is some linear increase with jitter,
-    ///   as expected in this specific use-case,
+    /// In case there is some linear increase with jitter, as expected in this specific use-case,
     /// as long as there is one bigger update each HISTORY updates the scan is never triggered at all.
     ///
     /// Worst case would be linearly decreasing values, which is still O(1).
     fn update(&mut self, new: u64) {
-        // exploit invariant_h to eliminate bounds checks & panic code path
         let head = usize::from(self.head) % self.history.len();
-        // exploit invariant_m to eliminate bounds checks & panic code path
         let max_pos = usize::from(self.max_pos) % self.history.len();
-
-        // save max now in case it gets overwritten in the next line
         let prev_max = self.history[max_pos];
         self.history[head] = new;
 
@@ -313,15 +298,12 @@ impl<const HISTORY: usize> MaxRingBuf<HISTORY> {
                 .max_by_key(|(_, v)| *v)
                 .expect("array has fixded size > 0");
             // invariant_m: idx is from an enumeration of history
-            self.max_pos = idx.try_into().expect("history.len() <= u8::MAX");
+            self.max_pos = idx as u8;
         }
 
-        // invariant_h: head is kept in bounds by %-ing with history.len()
-        //     it is a ring buffer so wrapping around is expected behaviour.
         self.head = (self.head + 1) % (self.history.len() as u8);
     }
 
-    /// Returns the maximum value out of the memorized entries
     fn max(&self) -> u64 {
         // exploit invariant_m to eliminate bounds checks & panic code path
         self.history[self.max_pos as usize % self.history.len()]
@@ -334,9 +316,7 @@ impl<const HISTORY: usize> Default for MaxRingBuf<HISTORY> {
         assert!(HISTORY > 0);
         Self {
             history: [0; HISTORY],
-            // invariant_h: we asserted that history has at least one element, therefore index 0 is valid
             head: 0,
-            // invariant_m: we asserted that history has at least one element, therefore index 0 is valid
             max_pos: 0,
         }
     }
@@ -352,9 +332,9 @@ impl<W: tokio::io::AsyncWrite + Unpin> tokio::io::AsyncWrite for ProgressBarIter
     ) -> Poll<io::Result<usize>> {
         Pin::new(&mut self.it).poll_write(cx, buf).map(|poll| {
             poll.map(|inc| {
-                let oldprog = self.progress.position();
-                let newprog = self.dejitter.update_seq(oldprog, inc.try_into().unwrap());
-                self.progress.set_position(newprog);
+                let pos = self.progress.position();
+                let new = self.seek_max.update_seq(pos, inc as u64);
+                self.progress.set_position(new);
                 inc
             })
         })
@@ -381,9 +361,9 @@ impl<W: tokio::io::AsyncRead + Unpin> tokio::io::AsyncRead for ProgressBarIter<W
         let poll = Pin::new(&mut self.it).poll_read(cx, buf);
         if let Poll::Ready(_e) = &poll {
             let inc = buf.filled().len() as u64 - prev_len;
-            let oldprog = self.progress.position();
-            let newprog = self.dejitter.update_seq(oldprog, inc);
-            self.progress.set_position(newprog);
+            let pos = self.progress.position();
+            let new = self.seek_max.update_seq(pos, inc);
+            self.progress.set_position(new);
         }
         poll
     }
@@ -399,8 +379,8 @@ impl<W: tokio::io::AsyncSeek + Unpin> tokio::io::AsyncSeek for ProgressBarIter<W
     fn poll_complete(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<u64>> {
         let poll = Pin::new(&mut self.it).poll_complete(cx);
         if let Poll::Ready(Ok(pos)) = &poll {
-            let newpos = self.dejitter.update_seek(*pos);
-            self.progress.set_position(newpos);
+            let new = self.seek_max.update_seek(*pos);
+            self.progress.set_position(new);
         }
 
         poll
@@ -419,9 +399,9 @@ impl<W: tokio::io::AsyncBufRead + Unpin + tokio::io::AsyncRead> tokio::io::Async
 
     fn consume(mut self: Pin<&mut Self>, amt: usize) {
         Pin::new(&mut self.it).consume(amt);
-        let oldprog = self.progress.position();
-        let newprog = self.dejitter.update_seq(oldprog, amt.try_into().unwrap());
-        self.progress.set_position(newprog);
+        let pos = self.progress.position();
+        let new = self.seek_max.update_seq(pos, amt as u64);
+        self.progress.set_position(new);
     }
 }
 
@@ -449,7 +429,7 @@ impl<W: io::Write> io::Write for ProgressBarIter<W> {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.it.write(buf).map(|inc| {
             self.progress.set_position(
-                self.dejitter
+                self.seek_max
                     .update_seq(self.progress.position(), inc as u64),
             );
             inc
@@ -459,7 +439,7 @@ impl<W: io::Write> io::Write for ProgressBarIter<W> {
     fn write_vectored(&mut self, bufs: &[io::IoSlice]) -> io::Result<usize> {
         self.it.write_vectored(bufs).map(|inc| {
             self.progress.set_position(
-                self.dejitter
+                self.seek_max
                     .update_seq(self.progress.position(), inc as u64),
             );
             inc
@@ -480,7 +460,7 @@ impl<S, T: Iterator<Item = S>> ProgressIterator for T {
         ProgressBarIter {
             it: self,
             progress,
-            dejitter: MaxSeekHeuristic::default(),
+            seek_max: SeekMax::default(),
         }
     }
 }

src/progress_bar.rs

@@ -498,7 +498,7 @@ impl ProgressBar {
         ProgressBarIter {
             progress: self.clone(),
             it: read,
-            dejitter: iter::MaxSeekHeuristic::default(),
+            seek_max: iter::SeekMax::default(),
         }
     }
 
@@ -520,7 +520,7 @@ impl ProgressBar {
         ProgressBarIter {
             progress: self.clone(),
             it: write,
-            dejitter: iter::MaxSeekHeuristic::default(),
+            seek_max: iter::SeekMax::default(),
         }
     }
 
@@ -547,7 +547,7 @@ impl ProgressBar {
         ProgressBarIter {
             progress: self.clone(),
             it: write,
-            dejitter: iter::MaxSeekHeuristic::default(),
+            seek_max: iter::SeekMax::default(),
         }
     }
 
@@ -571,7 +571,7 @@ impl ProgressBar {
         ProgressBarIter {
             progress: self.clone(),
             it: read,
-            dejitter: iter::MaxSeekHeuristic::default(),
+            seek_max: iter::SeekMax::default(),
         }
     }
 
@@ -594,7 +594,7 @@ impl ProgressBar {
         ProgressBarIter {
             progress: self.clone(),
             it: stream,
-            dejitter: iter::MaxSeekHeuristic::default(),
+            seek_max: iter::SeekMax::default(),
         }
     }
 

src/rayon.rs

@@ -1,7 +1,7 @@
 use rayon::iter::plumbing::{Consumer, Folder, Producer, ProducerCallback, UnindexedConsumer};
 use rayon::iter::{IndexedParallelIterator, ParallelIterator};
 
-use crate::{iter::MaxSeekHeuristic, ProgressBar, ProgressBarIter};
+use crate::{iter::SeekMax, ProgressBar, ProgressBarIter};
 
 /// Wraps a Rayon parallel iterator.
 ///
@@ -44,7 +44,7 @@ impl<S: Send, T: ParallelIterator<Item = S>> ParallelProgressIterator for T {
         ProgressBarIter {
             it: self,
             progress,
-            dejitter: MaxSeekHeuristic::default(),
+            seek_max: SeekMax::default(),
         }
     }
 }
@@ -103,7 +103,7 @@ impl<T, P: Producer<Item = T>> Producer for ProgressProducer<P> {
         ProgressBarIter {
             it: self.base.into_iter(),
             progress: self.progress,
-            dejitter: MaxSeekHeuristic::default(),
+            seek_max: SeekMax::default(),
         }
     }