Skip to content

Apache Lucene open-source search software

PanamaDocValuesRangeSupport: OR mask directly into FixedBitSet instead of per-bit loop (#16123)

Sagar Upadhyaya1b41317f33d0
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt
index 75ef7e8db29..aa0935250e6 100644
--- a/lucene/CHANGES.txt
+++ b/lucene/CHANGES.txt
@@ -429,6 +429,9 @@ Optimizations
* GITHUB#16097: Implement DocIdSetIterator#intoBitSet in dense implememntatios of the
Lucene90DocValuesProducer. (Ignacio Vera)
+* GITHUB#16123: PanamaDocValuesRangeSupport: OR mask directly into FixedBitSet instead of per-bit
+ loop. (Sagar Upadhyaya)
+
* GITHUB#16107: Add method SparseFixedBitSet#set(int startIndex, int endIndex). (Ignacio Vera)
* GITHUB#16126: Implement #intoBitSet and #docIDRunEnd in DocValuesWriter implementations. (Ignacio Vera)
diff --git a/lucene/core/src/java/org/apache/lucene/util/FixedBitSet.java b/lucene/core/src/java/org/apache/lucene/util/FixedBitSet.java
index afac09b1fe0..071098edf03 100644
--- a/lucene/core/src/java/org/apache/lucene/util/FixedBitSet.java
+++ b/lucene/core/src/java/org/apache/lucene/util/FixedBitSet.java
@@ -299,6 +299,28 @@ public final class FixedBitSet extends BitSet {
bits[wordNum] |= bitmask;
}
+ /**
+ * ORs a small mask of consecutive bits starting at {@code startBit}. The mask must have at most
+ * {@code maskLen} significant bits. This is useful for bulk-setting bits from a SIMD comparison
+ * result without per-bit extraction.
+ *
+ * @param startBit the first bit position to set (inclusive)
+ * @param mask the bitmask to OR in, where bit 0 corresponds to startBit
+ * @param maskLen the number of significant bits in the mask (e.g., 2, 4, or 8)
+ */
+ public void orMask(int startBit, long mask, int maskLen) {
+ assert startBit >= 0 && startBit + maskLen <= numBits
+ : "startBit=" + startBit + ", maskLen=" + maskLen + ", numBits=" + numBits;
+ int wordIndex = startBit >> 6;
+ int bitOffset = startBit & 63;
+ if (bitOffset + maskLen <= 64) {
+ bits[wordIndex] |= mask << bitOffset;
+ } else {
+ bits[wordIndex] |= mask << bitOffset;
+ bits[wordIndex + 1] |= mask >>> (64 - bitOffset);
+ }
+ }
+
@Override
public boolean getAndSet(int index) {
assert index >= 0 && index < numBits : "index=" + index + ", numBits=" + numBits;
diff --git a/lucene/core/src/java25/org/apache/lucene/internal/vectorization/PanamaDocValuesRangeSupport.java b/lucene/core/src/java25/org/apache/lucene/internal/vectorization/PanamaDocValuesRangeSupport.java
index 8b8fe6c2ff7..72fef3c31b6 100644
--- a/lucene/core/src/java25/org/apache/lucene/internal/vectorization/PanamaDocValuesRangeSupport.java
+++ b/lucene/core/src/java25/org/apache/lucene/internal/vectorization/PanamaDocValuesRangeSupport.java
@@ -57,12 +57,7 @@ final class PanamaDocValuesRangeSupport implements DocValuesRangeSupport {
v.compare(VectorOperators.GE, minValue).and(v.compare(VectorOperators.LE, maxValue));
long maskBits = inRange.toLong();
if (maskBits != 0) {
- int base = d - offset;
- while (maskBits != 0) {
- int bit = Long.numberOfTrailingZeros(maskBits);
- bitSet.set(base + bit);
- maskBits &= maskBits - 1;
- }
+ bitSet.orMask(d - offset, maskBits, vectorLen);
}
}
diff --git a/lucene/core/src/test/org/apache/lucene/search/TestSkipBlockRangeIteratorIntoBitSet.java b/lucene/core/src/test/org/apache/lucene/search/TestSkipBlockRangeIteratorIntoBitSet.java
index 49e69dda20d..6bc9d2e23db 100644
--- a/lucene/core/src/test/org/apache/lucene/search/TestSkipBlockRangeIteratorIntoBitSet.java
+++ b/lucene/core/src/test/org/apache/lucene/search/TestSkipBlockRangeIteratorIntoBitSet.java
@@ -539,4 +539,63 @@ public class TestSkipBlockRangeIteratorIntoBitSet extends BaseDocValuesSkipperTe
assertTrue("Doc " + d + " set in bitset but not in expected", expected.contains(d));
}
}
+
+ /**
+ * Tests that rangeIntoBitSet (SIMD/fast path) produces the exact same results as per-doc
+ * evaluation (slow path) across random data with various densities and range selectivities.
+ */
+ public void testRangeIntoBitSetMatchesPerDocEvaluation() throws Exception {
+ Random rng = random();
+ for (int iter = 0; iter < 10; iter++) {
+ int numDocs = rng.nextInt(4096, 4096 * 5);
+ long maxValue = rng.nextInt(100, 10000);
+ // Random range selectivity
+ long rangeMin = rng.nextLong(0, maxValue / 2);
+ long rangeMax = rangeMin + rng.nextLong(1, maxValue / 2);
+
+ try (Directory dir = newDirectory()) {
+ IndexWriterConfig iwc = new IndexWriterConfig().setCodec(new Lucene104Codec());
+ try (IndexWriter w = new IndexWriter(dir, iwc)) {
+ for (int i = 0; i < numDocs; i++) {
+ Document doc = new Document();
+ doc.add(NumericDocValuesField.indexedField("val", rng.nextLong(0, maxValue)));
+ w.addDocument(doc);
+ }
+ w.forceMerge(1);
+ }
+
+ try (DirectoryReader reader = DirectoryReader.open(dir)) {
+ LeafReaderContext ctx = reader.leaves().get(0);
+
+ // Slow path: per-doc evaluation
+ FixedBitSet expected = new FixedBitSet(numDocs);
+ NumericDocValues slowDv = ctx.reader().getNumericDocValues("val");
+ for (int d = 0; d < numDocs; d++) {
+ if (slowDv.advanceExact(d)) {
+ long v = slowDv.longValue();
+ if (v >= rangeMin && v <= rangeMax) {
+ expected.set(d);
+ }
+ }
+ }
+
+ // Fast path: rangeIntoBitSet
+ FixedBitSet actual = new FixedBitSet(numDocs);
+ NumericDocValues fastDv = ctx.reader().getNumericDocValues("val");
+ fastDv.rangeIntoBitSet(0, numDocs, rangeMin, rangeMax, actual, 0);
+
+ assertEquals(
+ "rangeIntoBitSet must match per-doc evaluation (numDocs="
+ + numDocs
+ + ", range=["
+ + rangeMin
+ + ","
+ + rangeMax
+ + "])",
+ expected,
+ actual);
+ }
+ }
+ }
+ }
}
diff --git a/lucene/core/src/test/org/apache/lucene/util/TestFixedBitSet.java b/lucene/core/src/test/org/apache/lucene/util/TestFixedBitSet.java
index 08abc745b8a..4d5c89c9703 100644
--- a/lucene/core/src/test/org/apache/lucene/util/TestFixedBitSet.java
+++ b/lucene/core/src/test/org/apache/lucene/util/TestFixedBitSet.java
@@ -841,4 +841,68 @@ public class TestFixedBitSet extends BaseBitSetTestCase<FixedBitSet> {
assertEquals(size, index[0]);
}
}
+
+ /** Tests that orMask produces the same result as setting bits individually. */
+ public void testOrMask() {
+ Random rng = random();
+ // Test with various mask lengths (simulating 2/4/8 SIMD lanes) and all alignments
+ for (int maskLen : new int[] {2, 4, 8}) {
+ // Test all possible bit offsets within a word (0-63) to cover alignment cases
+ for (int startBit = 0; startBit < 128; startBit++) {
+ long mask = rng.nextLong() & ((1L << maskLen) - 1);
+
+ FixedBitSet fast = new FixedBitSet(256);
+ FixedBitSet slow = new FixedBitSet(256);
+ // This is done to ensure some bits are already set and get don't wiped off.
+ for (int i = 0; i < 256; i += 7) {
+ fast.set(i);
+ slow.set(i);
+ }
+
+ // Fast path: orMask
+ fast.orMask(startBit, mask, maskLen);
+
+ // Slow path: per-bit set
+ long m = mask;
+ while (m != 0) {
+ int bit = Long.numberOfTrailingZeros(m);
+ slow.set(startBit + bit);
+ m &= m - 1;
+ }
+
+ // Verify fast and slow path bit matches
+ assertEquals(
+ "orMask mismatch: startBit="
+ + startBit
+ + ", mask=0b"
+ + Long.toBinaryString(mask)
+ + ", maskLen="
+ + maskLen,
+ slow,
+ fast);
+ }
+ }
+ }
+
+ /** Tests orMask at word boundaries (straddling two longs). */
+ public void testOrMaskStraddling() {
+ // Force straddling: startBit near end of a 64-bit word
+ for (int maskLen : new int[] {4, 8}) {
+ for (int bitOffset = 64 - maskLen + 1; bitOffset < 64; bitOffset++) {
+ // positions 61-63 for maskLen=4, 57-63 for maskLen=8
+ long mask = (1L << maskLen) - 1; // all bits set
+
+ FixedBitSet fast = new FixedBitSet(128);
+ fast.orMask(bitOffset, mask, maskLen);
+
+ FixedBitSet slow = new FixedBitSet(128);
+ for (int i = 0; i < maskLen; i++) {
+ slow.set(bitOffset + i);
+ }
+
+ assertEquals(
+ "Straddling mismatch: startBit=" + bitOffset + ", maskLen=" + maskLen, slow, fast);
+ }
+ }
+ }
}