feat: Add InOrderIter to 'parallel' module (#293)

This iterator makes possible identifies results using a sequence id
and returns only consecutive items.

Use it to collect unordered results produced by threads.
It's advantage to collecting yourself and sorting is the potential
for a smaller memory footprint of in-flight results, one doesn't
have to collect them all for ordering, necessarily.

Author: Byron

git-features/src/parallel/in_order.rs

@@ -0,0 +1,86 @@
+use std::{cmp::Ordering, collections::BTreeMap};
+
+/// A counter for chunks to be able to put them back into original order later.
+pub type ChunkId = usize;
+
+/// An iterator which olds iterated items with a **sequential** ID starting at 0 long enough to dispense them in order.
+///
+/// Note that this iterator is made specifically to support the signature of the iterator returned
+/// by [from_counts_iter(…)][super::entry::iter_from_counts()].
+pub struct InOrderIter<T, I> {
+    /// The iterator yielding the out-of-order elements we are to yield in order.
+    pub inner: I,
+    store: BTreeMap<ChunkId, T>,
+    next_chunk: ChunkId,
+    is_done: bool,
+}
+
+impl<T, E, I> From<I> for InOrderIter<T, I>
+where
+    I: Iterator<Item = Result<(ChunkId, T), E>>,
+{
+    fn from(iter: I) -> Self {
+        InOrderIter {
+            inner: iter,
+            store: Default::default(),
+            next_chunk: 0,
+            is_done: false,
+        }
+    }
+}
+
+impl<T, E, I> Iterator for InOrderIter<T, I>
+where
+    I: Iterator<Item = Result<(ChunkId, T), E>>,
+{
+    type Item = Result<T, E>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.is_done {
+            return None;
+        }
+        'find_next_in_sequence: loop {
+            match self.inner.next() {
+                Some(Ok((c, v))) => match c.cmp(&self.next_chunk) {
+                    Ordering::Equal => {
+                        self.next_chunk += 1;
+                        return Some(Ok(v));
+                    }
+                    Ordering::Less => {
+                        unreachable!("in a correctly ordered sequence we can never see keys again, got {}", c)
+                    }
+                    Ordering::Greater => {
+                        let previous = self.store.insert(c, v);
+                        assert!(
+                            previous.is_none(),
+                            "Chunks are returned only once, input is an invalid sequence"
+                        );
+                        if let Some(v) = self.store.remove(&self.next_chunk) {
+                            self.next_chunk += 1;
+                            return Some(Ok(v));
+                        }
+                        continue 'find_next_in_sequence;
+                    }
+                },
+                Some(Err(e)) => {
+                    self.is_done = true;
+                    self.store.clear();
+                    return Some(Err(e));
+                }
+                None => match self.store.remove(&self.next_chunk) {
+                    Some(v) => {
+                        self.next_chunk += 1;
+                        return Some(Ok(v));
+                    }
+                    None => {
+                        debug_assert!(
+                            self.store.is_empty(),
+                            "When iteration is done we should not have stored items left"
+                        );
+                        return None;
+                    }
+                },
+            }
+        }
+    }
+}

git-features/src/parallel/mod.rs

@@ -41,6 +41,9 @@ mod serial;
 #[cfg(not(feature = "parallel"))]
 pub use serial::{in_parallel, join, threads};
 
+mod in_order;
+pub use in_order::InOrderIter;
+
 mod eager_iter;
 pub use eager_iter::{EagerIter, EagerIterIf};
 

git-features/tests/parallel/in_order_iter.rs

@@ -0,0 +1,53 @@
+use git_features::parallel::InOrderIter;
+use std::convert::Infallible;
+
+#[test]
+fn in_order_stays_in_order() {
+    assert_eq!(
+        InOrderIter::from(vec![Ok::<_, Infallible>((0usize, 'a')), Ok((1, 'b')), Ok((2, 'c'))].into_iter())
+            .collect::<Result<Vec<_>, _>>()
+            .expect("infallible"),
+        vec!['a', 'b', 'c']
+    )
+}
+
+#[test]
+fn out_of_order_items_are_held_until_the_sequence_is_complete() {
+    assert_eq!(
+        InOrderIter::from(
+            vec![
+                Ok::<_, Infallible>((2usize, 'c')),
+                Ok((1, 'b')),
+                Ok((0, 'a')),
+                Ok((3, 'd'))
+            ]
+            .into_iter()
+        )
+        .collect::<Result<Vec<_>, _>>()
+        .expect("infallible"),
+        vec!['a', 'b', 'c', 'd']
+    )
+}
+
+#[test]
+fn in_sequence_errors_immediately_trigger_a_fuse() {
+    let mut iter = InOrderIter::from(vec![Ok::<_, &'static str>((0usize, 'a')), Err("err"), Ok((1, 'b'))].into_iter());
+    assert_eq!(iter.next(), Some(Ok('a')));
+    assert_eq!(iter.next(), Some(Err("err")));
+    assert_eq!(
+        iter.next(),
+        None,
+        "fuse should have triggered so we don't see anything else"
+    );
+}
+
+#[test]
+fn out_of_sequence_errors_immediately_trigger_a_fuse() {
+    let mut iter = InOrderIter::from(vec![Ok::<_, &'static str>((1usize, 'b')), Err("err"), Ok((0, 'a'))].into_iter());
+    assert_eq!(iter.next(), Some(Err("err")));
+    assert_eq!(
+        iter.next(),
+        None,
+        "fuse should have triggered so we don't see anything else"
+    );
+}

git-features/tests/parallel/mod.rs

@@ -1,6 +1,8 @@
 //! Tests that are working similarly in parallel and serial mode
 use git_features::parallel;
 
+mod in_order_iter;
+
 #[derive(Default)]
 struct Adder {
     count: usize,