Release candidate (3.7.0) (#2136)

* Release candidate (3.7.0)

* some extra comments.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -45,12 +45,16 @@ It is fine to report bugs against our main branch, but if that is what you are d
 
 **Configuration (please complete the following information if relevant)**
  - OS: [e.g. Ubuntu 16.04.6 LTS]
- - Compiler [e.g. Apple clang version 11.0.3 (clang-1103.0.32.59) x86_64-apple-darwin19.4.0]
+ - Compiler* [e.g. Apple clang version 11.0.3 (clang-1103.0.32.59) x86_64-apple-darwin19.4.0]
  - Version [e.g. 22]
  - Optimization setting (e.g., -O3)
 
 We support up-to-date 64-bit ARM and x64 FreeBSD, macOS, Windows and Linux systems. Please ensure that your configuration is supported before labelling the issue as a bug.
 
+* We do not support unreleased or experimental compilers. If you encounter an issue with a
+pre-release version of a compiler, do not report it as a bug to simdjson. However, we always
+invite contributions either in the form an analysis or of a code contribution.
+
 **Indicate whether you are willing or able to provide a bug fix as a pull request**
 
 If you plan to contribute to simdjson, please read our guide:

.vscode/settings.json

@@ -100,6 +100,9 @@
         "ranges": "cpp",
         "span": "cpp",
         "__verbose_abort": "cpp",
-        "charconv": "cpp"
+        "charconv": "cpp",
+        "source_location": "cpp",
+        "strstream": "cpp",
+        "typeindex": "cpp"
     }
 }

CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.14)
 project(
     simdjson
     # The version number is modified by tools/release.py
-    VERSION 3.6.4
+    VERSION 3.7.0
     DESCRIPTION "Parsing gigabytes of JSON per second"
     HOMEPAGE_URL "https://simdjson.org/"
     LANGUAGES CXX C
@@ -20,8 +20,8 @@ string(
 # ---- Options, variables ----
 
 # These version numbers are modified by tools/release.py
-set(SIMDJSON_LIB_VERSION "19.0.0" CACHE STRING "simdjson library version")
-set(SIMDJSON_LIB_SOVERSION "19" CACHE STRING "simdjson library soversion")
+set(SIMDJSON_LIB_VERSION "20.0.0" CACHE STRING "simdjson library version")
+set(SIMDJSON_LIB_SOVERSION "20" CACHE STRING "simdjson library soversion")
 
 option(SIMDJSON_BUILD_STATIC_LIB "Build simdjson_static library along with simdjson" OFF)
 

CONTRIBUTING.md

@@ -52,10 +52,11 @@ General Guidelines
 Contributors are encouraged to :
 
 - Document their changes. Though we do not enforce a rule regarding code comments, we prefer that non-trivial algorithms and techniques be somewhat documented in the code.
-- Follow as much as possible the existing code style. We do not enforce a specific code style, but we prefer consistency.
+- Follow as much as possible the existing code style. We do not enforce a specific code style, but we prefer consistency. We avoid contractions (isn't, aren't) in the comments.
 - Modify as few lines of code as possible when working on an issue. The more lines you modify, the harder it is for your fellow human beings to understand what is going on.
 - Tools may report "problems" with the code, but we never delegate programming to tools: if there is a problem with the code, we need to understand it. Thus we will not "fix" code merely to please a static analyzer.
 - Provide tests for any new feature. We will not merge a new feature without tests.
+- Run before/after benchmarks so that we can appreciate the effect of the changes on the performance.
 
 Pull Requests
 --------------

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = simdjson
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "3.6.4"
+PROJECT_NUMBER         = "3.7.0"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

doc/tape.md

@@ -29,7 +29,7 @@ It is sometimes useful to start with an example. Consider the following JSON doc
 The following is a dump of the content of the tape, with the first number of each line representing the index of a tape element.
 
 ### The Tape
-| index | element (64 bit word)                                               |
+| index | element (64-bit word)                                               |
 | ----- | ------------------------------------------------------------------- |
 | 0     | r	// pointing to 39 (right after last node)                         |
 | 1     | {	// pointing to next tape location 38 (first node after the scope) |

fuzz/build_fuzzer_variants.sh

@@ -78,7 +78,7 @@ fi
 # Different levels may uncover different types of bugs, see this interesting
 # thread: https://github.com/google/oss-fuzz/issues/2295#issuecomment-481493392
 # Oss-fuzz uses -O1 so it may be relevant to use something else than that,
-# to do something oss-fuzz doesn't.
+# to do something oss-fuzz does not do.
 variant=sanitizers-O3
 
     if [ ! -d build-$variant ] ; then

include/simdjson/dom/element.h

@@ -293,7 +293,7 @@ public:
    *
    * @return The integer value.
    * @exception simdjson_error(INCORRECT_TYPE) if the JSON element is not an integer
-   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer doesn't fit in 64 bits or is negative
+   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer does not fit in 64 bits or is negative
    */
   inline operator uint64_t() const noexcept(false);
   /**
@@ -301,7 +301,7 @@ public:
    *
    * @return The integer value.
    * @exception simdjson_error(INCORRECT_TYPE) if the JSON element is not an integer
-   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer doesn't fit in 64 bits
+   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer does not fit in 64 bits
    */
   inline operator int64_t() const noexcept(false);
   /**
@@ -309,7 +309,6 @@ public:
    *
    * @return The double value.
    * @exception simdjson_error(INCORRECT_TYPE) if the JSON element is not a number
-   * @exception simdjson_error(NUMBER_OUT_OF_RANGE) if the integer doesn't fit in 64 bits or is negative
    */
   inline operator double() const noexcept(false);
   /**

include/simdjson/generic/numberparsing.h

@@ -412,7 +412,7 @@ simdjson_inline error_code parse_exponent(simdjson_unused const uint8_t *const s
   // If there were more than 18 digits, we may have overflowed the integer. We have to do
   // something!!!!
   if (simdjson_unlikely(p > start_exp+18)) {
-    // Skip leading zeroes: 1e000000000000000000001 is technically valid and doesn't overflow
+    // Skip leading zeroes: 1e000000000000000000001 is technically valid and does not overflow
     while (*start_exp == '0') { start_exp++; }
     // 19 digits could overflow int64_t and is kind of absurd anyway. We don't
     // support exponents smaller than -999,999,999,999,999,999 and bigger
@@ -609,7 +609,7 @@ simdjson_inline error_code parse_number(const uint8_t *const src, W &writer) {
     }  else if (src[0] != uint8_t('1') || i <= uint64_t(INT64_MAX)) { return INVALID_NUMBER(src); }
   }
 
-  // Write unsigned if it doesn't fit in a signed integer.
+  // Write unsigned if it does not fit in a signed integer.
   if (i > uint64_t(INT64_MAX)) {
     WRITE_UNSIGNED(i, src, writer);
   } else {

include/simdjson/generic/ondemand/field-inl.h

@@ -12,7 +12,7 @@ namespace simdjson {
 namespace SIMDJSON_IMPLEMENTATION {
 namespace ondemand {
 
-// clang 6 doesn't think the default constructor can be noexcept, so we make it explicit
+// clang 6 does not think the default constructor can be noexcept, so we make it explicit
 simdjson_inline field::field() noexcept : std::pair<raw_json_string, ondemand::value>() {}
 
 simdjson_inline field::field(raw_json_string key, ondemand::value &&value) noexcept

include/simdjson/generic/ondemand/json_iterator.h

@@ -146,7 +146,7 @@ public:
    * @param delta The relative position of the token to retrieve. e.g. 0 = next token, -1 = prev token.
    *
    * TODO consider a string_view, assuming the length will get stripped out by the optimizer when
-   * it isn't used ...
+   * it is not used ...
    */
   simdjson_inline const uint8_t *peek(int32_t delta=0) const noexcept;
   /**
@@ -174,7 +174,7 @@ public:
    * @param position The position of the token to retrieve.
    *
    * TODO consider a string_view, assuming the length will get stripped out by the optimizer when
-   * it isn't used ...
+   * it is not used ...
    */
   simdjson_inline const uint8_t *peek(token_position position) const noexcept;
   /**
@@ -191,7 +191,7 @@ public:
    * This is not null-terminated; it is a view into the JSON.
    *
    * TODO consider a string_view, assuming the length will get stripped out by the optimizer when
-   * it isn't used ...
+   * it is not used ...
    */
   simdjson_inline const uint8_t *peek_last() const noexcept;
 

include/simdjson/generic/ondemand/token_iterator.h

@@ -47,7 +47,7 @@ public:
    *              1 = next token, -1 = prev token.
    *
    * TODO consider a string_view, assuming the length will get stripped out by the optimizer when
-   * it isn't used ...
+   * it is not used...
    */
   simdjson_inline const uint8_t *peek(int32_t delta=0) const noexcept;
   /**

include/simdjson/simdjson.h

@@ -1,6 +1,6 @@
 /**
  * @file
- * @deprecated We'll be removing this file so it isn't confused with the top level simdjson.h
+ * @deprecated We will be removing this file so it is not confused with the top level simdjson.h
  */
 #ifndef SIMDJSON_SIMDJSON_H
 #define SIMDJSON_SIMDJSON_H

include/simdjson/simdjson_version.h

@@ -4,7 +4,7 @@
 #define SIMDJSON_SIMDJSON_VERSION_H
 
 /** The version of simdjson being used (major.minor.revision) */
-#define SIMDJSON_VERSION "3.6.4"
+#define SIMDJSON_VERSION "3.7.0"
 
 namespace simdjson {
 enum {
@@ -15,11 +15,11 @@ enum {
   /**
    * The minor version (major.MINOR.revision) of simdjson being used.
    */
-  SIMDJSON_VERSION_MINOR = 6,
+  SIMDJSON_VERSION_MINOR = 7,
   /**
    * The revision (major.minor.REVISION) of simdjson being used.
    */
-  SIMDJSON_VERSION_REVISION = 4
+  SIMDJSON_VERSION_REVISION = 0
 };
 } // namespace simdjson
 

singleheader/simdjson.cpp

@@ -1,4 +1,4 @@
-/* auto-generated on 2024-02-04 22:03:23 -0500. Do not edit! */
+/* auto-generated on 2024-02-18 11:50:12 -0500. Do not edit! */
 /* including simdjson.cpp:  */
 /* begin file simdjson.cpp */
 #define SIMDJSON_SRC_SIMDJSON_CPP
@@ -7134,6 +7134,38 @@ static const simdjson::westmere::implementation* get_westmere_singleton() {
 namespace simdjson {
 namespace internal {
 
+// When there is a single implementation, we should not pay a price
+// for dispatching to the best implementation. We should just use the
+// one we have. This is a compile-time check.
+#define SIMDJSON_SINGLE_IMPLEMENTATION (SIMDJSON_IMPLEMENTATION_ICELAKE \
+             + SIMDJSON_IMPLEMENTATION_HASWELL + SIMDJSON_IMPLEMENTATION_WESTMERE \
+             + SIMDJSON_IMPLEMENTATION_ARM64 + SIMDJSON_IMPLEMENTATION_PPC64 \
+             + SIMDJSON_IMPLEMENTATION_FALLBACK == 1)
+
+#if SIMDJSON_SINGLE_IMPLEMENTATION
+  static const implementation* get_single_implementation() {
+    return
+#if SIMDJSON_IMPLEMENTATION_ICELAKE
+    get_icelake_singleton();
+#endif
+#if SIMDJSON_IMPLEMENTATION_HASWELL
+    get_haswell_singleton();
+#endif
+#if SIMDJSON_IMPLEMENTATION_WESTMERE
+    get_westmere_singleton();
+#endif
+#if SIMDJSON_IMPLEMENTATION_ARM64
+    get_arm64_singleton();
+#endif
+#if SIMDJSON_IMPLEMENTATION_PPC64
+    get_ppc64_singleton();
+#endif
+#if SIMDJSON_IMPLEMENTATION_FALLBACK
+    get_fallback_singleton();
+#endif
+}
+#endif
+
 // Static array of known implementations. We're hoping these get baked into the executable
 // without requiring a static initializer.
 
@@ -7263,9 +7295,16 @@ SIMDJSON_DLLIMPORTEXPORT const internal::available_implementation_list& get_avai
 }
 
 SIMDJSON_DLLIMPORTEXPORT internal::atomic_ptr<const implementation>& get_active_implementation() {
-    static const internal::detect_best_supported_implementation_on_first_use detect_best_supported_implementation_on_first_use_singleton;
-    static internal::atomic_ptr<const implementation> active_implementation{&detect_best_supported_implementation_on_first_use_singleton};
-    return active_implementation;
+#if SIMDJSON_SINGLE_IMPLEMENTATION
+  // We immediately select the only implementation we have, skipping the
+  // detect_best_supported_implementation_on_first_use_singleton.
+  static internal::atomic_ptr<const implementation> active_implementation{internal::get_single_implementation()};
+  return active_implementation;
+#else
+  static const internal::detect_best_supported_implementation_on_first_use detect_best_supported_implementation_on_first_use_singleton;
+  static internal::atomic_ptr<const implementation> active_implementation{&detect_best_supported_implementation_on_first_use_singleton};
+  return active_implementation;
+#endif
 }
 
 simdjson_warn_unused error_code minify(const char *buf, size_t len, char *dst, size_t &dst_len) noexcept {
@@ -9014,7 +9053,7 @@ simdjson_inline error_code parse_exponent(simdjson_unused const uint8_t *const s
   // If there were more than 18 digits, we may have overflowed the integer. We have to do
   // something!!!!
   if (simdjson_unlikely(p > start_exp+18)) {
-    // Skip leading zeroes: 1e000000000000000000001 is technically valid and doesn't overflow
+    // Skip leading zeroes: 1e000000000000000000001 is technically valid and does not overflow
     while (*start_exp == '0') { start_exp++; }
     // 19 digits could overflow int64_t and is kind of absurd anyway. We don't
     // support exponents smaller than -999,999,999,999,999,999 and bigger
@@ -9211,7 +9250,7 @@ simdjson_inline error_code parse_number(const uint8_t *const src, W &writer) {
     }  else if (src[0] != uint8_t('1') || i <= uint64_t(INT64_MAX)) { return INVALID_NUMBER(src); }
   }
 
-  // Write unsigned if it doesn't fit in a signed integer.
+  // Write unsigned if it does not fit in a signed integer.
   if (i > uint64_t(INT64_MAX)) {
     WRITE_UNSIGNED(i, src, writer);
   } else {
@@ -12115,7 +12154,7 @@ simdjson_inline size_t trim_partial_utf8(const uint8_t *buf, size_t len) {
 //    up enough CPU: the second half of the functions is highly serial, only using 1 execution core
 //    at a time. The second input's scans has some dependency on the first ones finishing it, but
 //    they can make a lot of progress before they need that information.
-// 3. Step 1 doesn't use enough capacity, so we run some extra stuff while we're waiting for that
+// 3. Step 1 does not use enough capacity, so we run some extra stuff while we're waiting for that
 //    to finish: utf-8 checks and generating the output from the last iteration.
 //
 // The reason we run 2 inputs at a time, is steps 2 and 3 are *still* not enough to soak up all
@@ -15302,7 +15341,7 @@ simdjson_inline error_code parse_exponent(simdjson_unused const uint8_t *const s
   // If there were more than 18 digits, we may have overflowed the integer. We have to do
   // something!!!!
   if (simdjson_unlikely(p > start_exp+18)) {
-    // Skip leading zeroes: 1e000000000000000000001 is technically valid and doesn't overflow
+    // Skip leading zeroes: 1e000000000000000000001 is technically valid and does not overflow
     while (*start_exp == '0') { start_exp++; }
     // 19 digits could overflow int64_t and is kind of absurd anyway. We don't
     // support exponents smaller than -999,999,999,999,999,999 and bigger
@@ -15499,7 +15538,7 @@ simdjson_inline error_code parse_number(const uint8_t *const src, W &writer) {
     }  else if (src[0] != uint8_t('1') || i <= uint64_t(INT64_MAX)) { return INVALID_NUMBER(src); }
   }
 
-  // Write unsigned if it doesn't fit in a signed integer.
+  // Write unsigned if it does not fit in a signed integer.
   if (i > uint64_t(INT64_MAX)) {
     WRITE_UNSIGNED(i, src, writer);
   } else {
@@ -18280,7 +18319,7 @@ simdjson_inline size_t trim_partial_utf8(const uint8_t *buf, size_t len) {
 //    up enough CPU: the second half of the functions is highly serial, only using 1 execution core
 //    at a time. The second input's scans has some dependency on the first ones finishing it, but
 //    they can make a lot of progress before they need that information.
-// 3. Step 1 doesn't use enough capacity, so we run some extra stuff while we're waiting for that
+// 3. Step 1 does not use enough capacity, so we run some extra stuff while we're waiting for that
 //    to finish: utf-8 checks and generating the output from the last iteration.
 //
 // The reason we run 2 inputs at a time, is steps 2 and 3 are *still* not enough to soak up all
@@ -21462,7 +21501,7 @@ simdjson_inline error_code parse_exponent(simdjson_unused const uint8_t *const s
   // If there were more than 18 digits, we may have overflowed the integer. We have to do
   // something!!!!
   if (simdjson_unlikely(p > start_exp+18)) {
-    // Skip leading zeroes: 1e000000000000000000001 is technically valid and doesn't overflow
+    // Skip leading zeroes: 1e000000000000000000001 is technically valid and does not overflow
     while (*start_exp == '0') { start_exp++; }
     // 19 digits could overflow int64_t and is kind of absurd anyway. We don't
     // support exponents smaller than -999,999,999,999,999,999 and bigger
@@ -21659,7 +21698,7 @@ simdjson_inline error_code parse_number(const uint8_t *const src, W &writer) {
     }  else if (src[0] != uint8_t('1') || i <= uint64_t(INT64_MAX)) { return INVALID_NUMBER(src); }
   }
 
-  // Write unsigned if it doesn't fit in a signed integer.
+  // Write unsigned if it does not fit in a signed integer.
   if (i > uint64_t(INT64_MAX)) {
     WRITE_UNSIGNED(i, src, writer);
   } else {
@@ -24438,7 +24477,7 @@ simdjson_inline size_t trim_partial_utf8(const uint8_t *buf, size_t len) {
 //    up enough CPU: the second half of the functions is highly serial, only using 1 execution core
 //    at a time. The second input's scans has some dependency on the first ones finishing it, but
 //    they can make a lot of progress before they need that information.
-// 3. Step 1 doesn't use enough capacity, so we run some extra stuff while we're waiting for that
+// 3. Step 1 does not use enough capacity, so we run some extra stuff while we're waiting for that
 //    to finish: utf-8 checks and generating the output from the last iteration.
 //
 // The reason we run 2 inputs at a time, is steps 2 and 3 are *still* not enough to soak up all
@@ -27778,7 +27817,7 @@ simdjson_inline error_code parse_exponent(simdjson_unused const uint8_t *const s
   // If there were more than 18 digits, we may have overflowed the integer. We have to do
   // something!!!!
   if (simdjson_unlikely(p > start_exp+18)) {
-    // Skip leading zeroes: 1e000000000000000000001 is technically valid and doesn't overflow
+    // Skip leading zeroes: 1e000000000000000000001 is technically valid and does not overflow
     while (*start_exp == '0') { start_exp++; }
     // 19 digits could overflow int64_t and is kind of absurd anyway. We don't
     // support exponents smaller than -999,999,999,999,999,999 and bigger
@@ -27975,7 +28014,7 @@ simdjson_inline error_code parse_number(const uint8_t *const src, W &writer) {
     }  else if (src[0] != uint8_t('1') || i <= uint64_t(INT64_MAX)) { return INVALID_NUMBER(src); }
   }
 
-  // Write unsigned if it doesn't fit in a signed integer.
+  // Write unsigned if it does not fit in a signed integer.
   if (i > uint64_t(INT64_MAX)) {
     WRITE_UNSIGNED(i, src, writer);
   } else {
@@ -30867,7 +30906,7 @@ simdjson_inline size_t trim_partial_utf8(const uint8_t *buf, size_t len) {
 //    up enough CPU: the second half of the functions is highly serial, only using 1 execution core
 //    at a time. The second input's scans has some dependency on the first ones finishing it, but
 //    they can make a lot of progress before they need that information.
-// 3. Step 1 doesn't use enough capacity, so we run some extra stuff while we're waiting for that
+// 3. Step 1 does not use enough capacity, so we run some extra stuff while we're waiting for that
 //    to finish: utf-8 checks and generating the output from the last iteration.
 //
 // The reason we run 2 inputs at a time, is steps 2 and 3 are *still* not enough to soak up all
@@ -34460,7 +34499,7 @@ simdjson_inline error_code parse_exponent(simdjson_unused const uint8_t *const s
   // If there were more than 18 digits, we may have overflowed the integer. We have to do
   // something!!!!
   if (simdjson_unlikely(p > start_exp+18)) {
-    // Skip leading zeroes: 1e000000000000000000001 is technically valid and doesn't overflow
+    // Skip leading zeroes: 1e000000000000000000001 is technically valid and does not overflow
     while (*start_exp == '0') { start_exp++; }
     // 19 digits could overflow int64_t and is kind of absurd anyway. We don't
     // support exponents smaller than -999,999,999,999,999,999 and bigger
@@ -34657,7 +34696,7 @@ simdjson_inline error_code parse_number(const uint8_t *const src, W &writer) {
     }  else if (src[0] != uint8_t('1') || i <= uint64_t(INT64_MAX)) { return INVALID_NUMBER(src); }
   }
 
-  // Write unsigned if it doesn't fit in a signed integer.
+  // Write unsigned if it does not fit in a signed integer.
   if (i > uint64_t(INT64_MAX)) {
     WRITE_UNSIGNED(i, src, writer);
   } else {
@@ -37870,7 +37909,7 @@ simdjson_inline size_t trim_partial_utf8(const uint8_t *buf, size_t len) {
 //    up enough CPU: the second half of the functions is highly serial, only using 1 execution core
 //    at a time. The second input's scans has some dependency on the first ones finishing it, but
 //    they can make a lot of progress before they need that information.
-// 3. Step 1 doesn't use enough capacity, so we run some extra stuff while we're waiting for that
+// 3. Step 1 does not use enough capacity, so we run some extra stuff while we're waiting for that
 //    to finish: utf-8 checks and generating the output from the last iteration.
 //
 // The reason we run 2 inputs at a time, is steps 2 and 3 are *still* not enough to soak up all
@@ -40569,7 +40608,7 @@ simdjson_inline error_code parse_exponent(simdjson_unused const uint8_t *const s
   // If there were more than 18 digits, we may have overflowed the integer. We have to do
   // something!!!!
   if (simdjson_unlikely(p > start_exp+18)) {
-    // Skip leading zeroes: 1e000000000000000000001 is technically valid and doesn't overflow
+    // Skip leading zeroes: 1e000000000000000000001 is technically valid and does not overflow
     while (*start_exp == '0') { start_exp++; }
     // 19 digits could overflow int64_t and is kind of absurd anyway. We don't
     // support exponents smaller than -999,999,999,999,999,999 and bigger
@@ -40766,7 +40805,7 @@ simdjson_inline error_code parse_number(const uint8_t *const src, W &writer) {
     }  else if (src[0] != uint8_t('1') || i <= uint64_t(INT64_MAX)) { return INVALID_NUMBER(src); }
   }
 
-  // Write unsigned if it doesn't fit in a signed integer.
+  // Write unsigned if it does not fit in a signed integer.
   if (i > uint64_t(INT64_MAX)) {
     WRITE_UNSIGNED(i, src, writer);
   } else {

src/generic/stage1/json_structural_indexer.h

@@ -183,7 +183,7 @@ simdjson_inline size_t trim_partial_utf8(const uint8_t *buf, size_t len) {
 //    up enough CPU: the second half of the functions is highly serial, only using 1 execution core
 //    at a time. The second input's scans has some dependency on the first ones finishing it, but
 //    they can make a lot of progress before they need that information.
-// 3. Step 1 doesn't use enough capacity, so we run some extra stuff while we're waiting for that
+// 3. Step 1 does not use enough capacity, so we run some extra stuff while we're waiting for that
 //    to finish: utf-8 checks and generating the output from the last iteration.
 //
 // The reason we run 2 inputs at a time, is steps 2 and 3 are *still* not enough to soak up all