Renamed PARALLEL to BRANCHLESS

Author: Can Gokmen

CMakeLists.txt

@@ -47,7 +47,7 @@ endif()
 
 # ── Targets ─────────────────────────────────────────────────────────────────────
 # All executables are tuned for the build host with -march=native.  This enables
-# the wider instruction set the QuART_kfp Parallel findSlot and the Node16 SSE
+# the wider instruction set the QuART_kfp Branchless findSlot and the Node16 SSE
 # compares benefit from.  Note: it applies to the WHOLE binary, so every tree type
 # is built for this CPU and the result may SIGILL on an older/different machine.
 #

sequential_findslot_report.txt

@@ -1,5 +1,5 @@
 ================================================================================
- QuART k-fp:  Why the Sequential findSlot is Slower than the Parallel findSlot
+ QuART k-fp:  Why the Sequential findSlot is Slower than the Branchless findSlot
  A profiling report + branch-misprediction explanation
 ================================================================================
 
@@ -18,7 +18,7 @@ Benchmark : test_kfp, K=3, three sorted BoDS streams interleaved uniformly at
 * The Sequential findSlot is slower because of BRANCH MISPREDICTION, not because
   of data copying or cache misses.
 
-* perf proves it: the Sequential and Parallel modes have an IDENTICAL L1 data-
+* perf proves it: the Sequential and Branchless modes have an IDENTICAL L1 data-
   cache miss rate (0.14% vs 0.15%), but Sequential suffers ~35M MORE branch
   mispredictions (55.2M vs 19.7M). Each misprediction is a ~15-20 cycle pipeline
   flush.
@@ -28,7 +28,7 @@ Benchmark : test_kfp, K=3, three sorted BoDS streams interleaved uniformly at
   uniformly at random, each key matches a random one of the 3 slots, so that
   branch is fundamentally unpredictable (~1/3 taken, no pattern).
 
-* The Parallel mode is faster because it converts K unpredictable branches into
+* The Branchless mode is faster because it converts K unpredictable branches into
   K branchless comparisons + ONE highly-predictable branch ("did ANY slot
   match?", ~96% taken) + one ctz instruction to extract which slot.
 
@@ -39,7 +39,7 @@ Benchmark : test_kfp, K=3, three sorted BoDS streams interleaved uniformly at
   REGRESSES this uniform-random benchmark.
 
 * Decision: leave the Sequential findSlot as the clean, honest baseline. The
-  Parallel mode is the answer when speed matters.
+  Branchless mode is the answer when speed matters.
 
 
 --------------------------------------------------------------------------------
@@ -58,7 +58,7 @@ upper bytes:
 findSlot has two implementations selected at compile time by the SearchMode
 template parameter:
 
-    Parallel    (default) - branchless K-way compare, collapsed to one branch.
+    Branchless  (default) - K-way compare, collapsed to one branch.
     Sequential            - the classic early-exit scan: test slots one at a
                             time, stop at the first match.
 
@@ -84,7 +84,7 @@ SEQUENTIAL (the early-exit scan; trees/QuART_kfp.h):
     }
     return {-1, MatchType::NO_MATCH};
 
-PARALLEL (branchless K-way match; trees/QuART_kfp.h):
+BRANCHLESS (K-way match; trees/QuART_kfp.h):
 
     unsigned match = 0;
     for (int i = 0; i < K; i++)
@@ -103,7 +103,7 @@ compiler.
 
 To measure each mode in isolation, test_kfp gained dedicated run modes:
 
-    ./build/test_kfp par <maxkeys>   # only the Parallel    QuART_kfp<3>
+    ./build/test_kfp par <maxkeys>   # only the Branchless  QuART_kfp<3>
     ./build/test_kfp seq <maxkeys>   # only the Sequential  QuART_kfp<3,FIFO,Sequential>
     ./build/test_kfp ff  <maxkeys>   # only the FREQ_FILTER variant
     ./build/test_kfp kfp <maxkeys>   # all three
@@ -132,9 +132,9 @@ Hotspot attribution:
  4.  RESULTS  (perf stat, isolated, 20M keys/stream)
 --------------------------------------------------------------------------------
 
-  Metric                     Sequential        Parallel        Delta
+  Metric                     Sequential        Branchless      Delta
   -----------------------    ------------      -----------     ----------------
-  Throughput (timed)         39.4 M/s          54.1 M/s        Parallel 1.37x
+  Throughput (timed)         39.4 M/s          54.1 M/s        Branchless 1.37x
   task-clock                 1528 ms           1114 ms
   instructions               12.05 B           11.80 B         seq +2%
   cycles                     5.58 B            3.94 B          seq +42%
@@ -163,7 +163,7 @@ early-exit comparison branches.
 The two telling facts:
 
   (a) The L1 data-cache miss RATE is identical (0.14% vs 0.15%). The Sequential
-      scan does NOT copy structs and does NOT miss cache more than Parallel. The
+      scan does NOT copy structs and does NOT miss cache more than Branchless. The
       hypothesis that "copying instead of references" causes the slowdown is
       DISPROVEN by the data. (The only real copies in the insert path are in
       loadSlot/saveToSlot, and the FP_INSERT hot path already uses a reference
@@ -234,10 +234,10 @@ THE SEQUENTIAL BRANCH HAS NO PATTERN
 
 
 --------------------------------------------------------------------------------
- 7.  HOW THE PARALLEL DESIGN SOLVES IT
+ 7.  HOW THE BRANCHLESS DESIGN SOLVES IT
 --------------------------------------------------------------------------------
 
-The Parallel version never branches per slot. Conceptually, for K=3:
+The Branchless version never branches per slot. Conceptually, for K=3:
 
     bit0 = (slots[0].cached_upper == keyUpper);   // branchless: cmp + sete
     bit1 = (slots[1].cached_upper == keyUpper);   // branchless
@@ -253,7 +253,7 @@ Three things change:
      with NO jump and NO control-flow change. There is nothing to mispredict --
      the CPU computes all three comparisons unconditionally. Because the three
      are independent (no data dependency), they issue on separate execution ports
-     in the same cycles. That parallelism is what gives the mode its name.
+     in the same cycles -- and none of them is a branch, which names the mode.
      Result for a key from stream B: match = 0b010.
 
   2. THE ONE REMAINING BRANCH IS PREDICTABLE.
@@ -267,7 +267,7 @@ Three things change:
      __builtin_ctz(match) (count-trailing-zeros), a single instruction returning
      the index of the lowest set bit (0b010 -> 1). No guessing.
 
-  Intuition: Parallel shows the package to all three people AT ONCE; they answer
+  Intuition: Branchless shows the package to all three people AT ONCE; they answer
   simultaneously and you read off who raised a hand. The only thing you "predict"
   is "did somebody raise a hand?", and the answer is almost always yes.
 
@@ -278,7 +278,7 @@ THE CORE IDEA
 
       Sequential : in CONTROL FLOW (a chain of data-dependent branches)
                    -> the predictor must guess random outcomes -> ~55M flushes.
-      Parallel   : in the DATAPATH (branchless sete compares + ctz), leaving only
+      Branchless : in the DATAPATH (branchless sete compares + ctz), leaving only
                    one PREDICTABLE branch ("any match?") -> ~20M misses, 1.37x.
 
   You cannot make the random "which slot" question predictable; that is the
@@ -350,7 +350,7 @@ regresses the uniform benchmark.
   NOT cache, NOT instruction count.
 
 * On THIS benchmark the Sequential scan is already at its floor. No change that
-  keeps it sequential improves it; the parallel restructuring is the only thing
+  keeps it sequential improves it; the branchless restructuring is the only thing
   that helps, and that mode already exists.
 
 * The one realistic lever is the temporal-locality hint, which only pays off if
@@ -359,7 +359,7 @@ regresses the uniform benchmark.
   construction, so it cannot show that win and in fact regresses ~2-6%.
 
 * DECISION: leave the Sequential findSlot as the clean, honest baseline. Use the
-  Parallel mode when throughput matters (1.37x here). If a future experiment uses
+  Branchless mode when throughput matters (1.37x here). If a future experiment uses
   clustered/bursty interleaves, revisit the opt-in hint as a third SearchMode.
 
 
@@ -372,7 +372,7 @@ regresses the uniform benchmark.
   cmake --build build --target test_kfp
 
   # Isolated timing
-  ./build/test_kfp par 20000000      # Parallel  ~54 M/s
+  ./build/test_kfp par 20000000      # Branchless ~54 M/s
   ./build/test_kfp seq 20000000      # Sequential ~39 M/s
   ./build/test_kfp kfp 20000000      # both + FREQ_FILTER, prints 1.37x speedup
 
@@ -384,7 +384,7 @@ regresses the uniform benchmark.
                L1-dcache-loads,L1-dcache-load-misses ./build-prof/test_kfp seq 20000000
   perf stat -e ... ./build-prof/test_kfp par 20000000
 
-  Code under study: trees/QuART_kfp.h, function findSlot (Parallel branchless
+  Code under study: trees/QuART_kfp.h, function findSlot (Branchless
   block and the Sequential early-exit scan).
 
 ================================================================================

test_kfp_grid.cpp

@@ -7,7 +7,7 @@
 // (seed 42 → identical sequence for every tree), pre-loads PRELOAD_FRAC
 // untimed, then times the remaining inserts into plain ART and into
 // QuART_kfp<K> for K in {1,2,4,8,16,32,64}, in both findSlot SearchModes
-// (Parallel and SIMD).  Emits one CSV row per (mode,K) to stdout:
+// (Branchless and SIMD).  Emits one CSV row per (mode,K) to stdout:
 //
 //   series,streams,keys_per_stream,mode,K,art_ns,kfp_ns,speedup
 //
@@ -140,7 +140,7 @@ static long long run_one(TreeT& tree, const vector<key_int_t>& vals,
 
 // Emit one CSV row (machine-readable) on stdout.  A crashed run is recorded
 // with kfp_ns = -1 and speedup = -1 so the cell is preserved (not lost) in the
-// grid.  `mode` is the findSlot SearchMode ("parallel"/"simd"), or "art" for
+// grid.  `mode` is the findSlot SearchMode ("branchless"/"simd"), or "art" for
 // the baseline row.
 static void emit_csv(const string& series, size_t streams, size_t kps,
                      const char* mode, int K, long long art_ns,
@@ -216,16 +216,16 @@ static void sweep_k_mode(const string& series, size_t streams, size_t kps,
     emit_csv(series, streams, kps, mode, K, art_ns, ns);
 }
 
-// Sweep one K value across both findSlot SearchModes (Parallel vs SIMD) so the
+// Sweep one K value across both findSlot SearchModes (Branchless vs SIMD) so the
 // grid carries a direct A/B of the SoA+AVX2 classifier against the scalar
 // branchless one.
 template <int K>
 static void sweep_k(const string& series, size_t streams, size_t kps,
                     const vector<key_int_t>& vals,
                     const vector<array<uint8_t, keyBytes>>& enc, size_t preload,
                     long long art_ns) {
-    sweep_k_mode<K, SearchMode::Parallel>(series, streams, kps, vals, enc,
-                                          preload, art_ns, "parallel");
+    sweep_k_mode<K, SearchMode::Branchless>(series, streams, kps, vals, enc,
+                                            preload, art_ns, "branchless");
     sweep_k_mode<K, SearchMode::SIMD>(series, streams, kps, vals, enc, preload,
                                       art_ns, "simd");
 }

trees/QuART_kfp.h

@@ -24,7 +24,7 @@ enum class EvictionPolicy { FIFO, FREQ_FILTER };
 
 // Strategy used by findSlot to classify a key against the K active slots.
 //
-//   Parallel    – data-parallel branchless FP_INSERT pre-pass: all K
+//   Branchless  – data-parallel FP_INSERT pre-pass: all K
 //                 upper-byte equality checks are computed with no inter-check
 //                 data dependency, so the CPU issues them together and the
 //                 whole classification collapses to a single, well-predicted
@@ -36,7 +36,7 @@ enum class EvictionPolicy { FIFO, FREQ_FILTER };
 //                 offered one) the lowest-index BRIDGE.  Simpler, but every
 //                 per-slot comparison is a hard-to-predict branch.
 //
-//   SIMD        – like Parallel, but the K upper-byte equality checks are done
+//   SIMD        – like Branchless, but the K upper-byte equality checks are done
 //                 over a packed, struct-of-arrays `cached_uppers[K]` companion
 //                 array (one machine word per slot, ~K/8 cache lines, L1-
 //                 resident) using AVX2 (_mm256_cmpeq_epi32, 8 lanes per
@@ -46,18 +46,18 @@ enum class EvictionPolicy { FIFO, FREQ_FILTER };
 //                 loop in insert() is also dropped for this mode — only the one
 //                 matched slot's fp is touched.  This keeps the per-insert tax
 //                 ~flat as K grows, so k-fp stays >1x vs ART even at high stream
-//                 counts.  Same classifier semantics as Parallel (lowest-index
+//                 counts.  Same classifier semantics as Branchless (lowest-index
 //                 FP_INSERT wins once all K slots are occupied).
 //
 // All three SearchModes are exact equivalents.  Each returns the lowest-index
 // FP_INSERT among all active slots, and only when no slot offers an FP_INSERT
-// does it return the lowest-index BRIDGE.  Parallel/SIMD compute the FP_INSERT
+// does it return the lowest-index BRIDGE.  Branchless/SIMD compute the FP_INSERT
 // pass branchlessly / with AVX2 once all K slots are full; Sequential walks the
 // slots in two scalar passes (all FP_INSERT checks, then all BRIDGE checks).
 // They differ only in instruction mix, never in the slot or match type they
 // pick — in particular a BRIDGE in a low-index slot can never pre-empt an exact
 // FP_INSERT in a higher-index slot in any mode.
-enum class SearchMode { Sequential, Parallel, SIMD };
+enum class SearchMode { Sequential, Branchless, SIMD };
 
 // QuART_kfp<K, Policy, Search>: Maintains up to K independent fast-path slots,
 // one per workload.  Uses the stail key-classification scheme (FP_INSERT /
@@ -75,9 +75,9 @@ enum class SearchMode { Sequential, Parallel, SIMD };
 //               (eviction policy selected by the Policy template parameter)
 //
 // The Search template parameter selects how findSlot scans the K slots
-// (Parallel branchless vs. Sequential early-exit); see SearchMode above.
+// (Branchless vs. Sequential early-exit); see SearchMode above.
 template <int K, EvictionPolicy Policy = EvictionPolicy::FIFO,
-          SearchMode Search = SearchMode::Parallel>
+          SearchMode Search = SearchMode::Branchless>
 class QuART_kfp : public QuART {
    public:
     QuART_kfp() : QuART(), num_active(0), next_evict(0), active_slot(-1)
@@ -349,8 +349,8 @@ class QuART_kfp : public QuART {
     std::pair<int, MatchType> findSlot(uint8_t key[]) const {
         key_int_t keyUpper = getKeyUpperBytes(key);
 
-        if constexpr (Search == SearchMode::Parallel) {
-            // Parallel branchless FP_INSERT classification.
+        if constexpr (Search == SearchMode::Branchless) {
+            // Branchless FP_INSERT classification.
             // All K equality checks are emitted as branchless sete/cmov
             // instructions with no data dependencies between them, so the CPU can
             // issue them in parallel.  The single resulting branch (match != 0) has
@@ -380,7 +380,7 @@ class QuART_kfp : public QuART {
             // _mm256_cmpeq_epi32 tests 8 slots; movemask_ps packs the 8 lane
             // results into bits, accumulated into a 64-bit `match` (bit i == slot
             // i, so ctzll picks the lowest-index match — same tie-break as
-            // Parallel).  Only runs once all K slots are full, mirroring Parallel.
+            // Branchless).  Only runs once all K slots are full, mirroring Branchless.
             if (__builtin_expect(num_active == K, 1)) {
                 uint64_t match = 0;
                 if constexpr (sizeof(key_int_t) == 4) {
@@ -414,11 +414,11 @@ class QuART_kfp : public QuART {
         // GLOBAL FP_INSERT: scan every active slot and return the lowest-index
         // exact upper-byte match.  Only if no slot offers an FP_INSERT do we make a
         // second pass for the lowest-index BRIDGE.  Splitting the passes is what
-        // makes Sequential agree with the Parallel/SIMD FP_INSERT pre-pass — a
+        // makes Sequential agree with the Branchless/SIMD FP_INSERT pre-pass — a
         // BRIDGE in a low-index slot can no longer pre-empt an exact FP_INSERT in a
         // higher-index slot.
         //
-        // In Parallel/SIMD mode, when all K slots are occupied the branchless/AVX2
+        // In Branchless/SIMD mode, when all K slots are occupied the branchless/AVX2
         // FP_INSERT pre-pass above already returned any exact match, so the first
         // pass here finds nothing and this loop is just the BRIDGE / warm-up path.
         // In Sequential mode it is the entire classifier.