You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by th...@apache.org on 2026/09/03 11:01:52 UTC
(lucene) branch main updated: Avoid a blocking direct read when creating a DirectIODirectory slice (#16619)
This is an automated email from the ASF dual-hosted git repository.
thecoop pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/lucene.git
The following commit(s) were added to refs/heads/main by this push:
new 1f5d30938bf Avoid a blocking direct read when creating a DirectIODirectory slice (#16619)
1f5d30938bf is described below
commit 1f5d30938bf136f4d751d034f18a2838019f8396
Author: John Maurice <83...@users.noreply.github.com>
AuthorDate: Thu Sep 3 14:01:45 2026 +0300
Avoid a blocking direct read when creating a DirectIODirectory slice (#16619)
Rather than forcing an initial read on slice() calls, record where the slice should be starting from, and only do the initial read when the slice is actually used - this means that slices that don't have any IO performed on them them don't cause spurious IO, which can disrupt the page cache.
---
lucene/CHANGES.txt | 3 +
.../lucene/misc/store/DirectIODirectory.java | 64 ++++-
.../lucene/misc/store/TestDirectIODirectory.java | 260 +++++++++++++++++++++
3 files changed, 321 insertions(+), 6 deletions(-)
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt
index 4121b695d7c..e77c3057b65 100644
--- a/lucene/CHANGES.txt
+++ b/lucene/CHANGES.txt
@@ -212,6 +212,9 @@ Optimizations
* GITHUB#12324: ELiminate redundant work in AbstractKnnVectorQuery.rewrite (Mike Sokolov)
+* GITHUB#16619: DirectIODirectory's slice() no longer performs a blocking direct read when
+ creating a slice; the first read resolves the deferred start position instead. (John Maurice)
+
Bug Fixes
---------------------
* GITHUB#16553: Fix stored-fields corruption when PerField#finish throws: the stored-fields frame
diff --git a/lucene/misc/src/java/org/apache/lucene/misc/store/DirectIODirectory.java b/lucene/misc/src/java/org/apache/lucene/misc/store/DirectIODirectory.java
index 94723546b6c..f76bda39eac 100644
--- a/lucene/misc/src/java/org/apache/lucene/misc/store/DirectIODirectory.java
+++ b/lucene/misc/src/java/org/apache/lucene/misc/store/DirectIODirectory.java
@@ -300,7 +300,7 @@ public class DirectIODirectory extends FilterDirectory {
}
}
- private static final class DirectIOIndexInput extends IndexInput {
+ static final class DirectIOIndexInput extends IndexInput { // package-private, visible for test
private final ByteBuffer buffer;
private final FileChannel channel;
private final int blockSize;
@@ -310,6 +310,17 @@ public class DirectIODirectory extends FilterDirectory {
private boolean isOpen;
private long filePos;
+ /**
+ * Where a lazily positioned clone/slice starts, until its first fill: -1 when nothing is
+ * pending, otherwise the number of bytes from the start of the block at {@code filePos +
+ * buffer.capacity()} to this input's position 0. Consumed by the first {@link #refill(int)};
+ * dropped by a repositioning {@link #seek(long)} or {@link #seekInternal(long)}. The sentinel
+ * is -1 rather than 0 because 0 is a legal pending value (a block-aligned start), and such a
+ * slice must still take the first-fill path so that its EOF check uses the pending value rather
+ * than the length of the caller's read.
+ */
+ private int pendingDelta = -1;
+
/**
* Creates a new instance of DirectIOIndexInput for reading index input with direct IO bypassing
* OS buffer
@@ -344,10 +355,19 @@ public class DirectIODirectory extends FilterDirectory {
this.isClosable = false;
this.length = length;
this.offset = offset;
- this.filePos = -bufferSize;
+ // Remember the start position instead of reading it now; the first refill() resolves it, so
+ // slice() does no I/O even when offset is not block-aligned.
+ final long alignedStart = offset - (offset % this.blockSize);
+ this.filePos = alignedStart - bufferSize;
+ this.pendingDelta = (int) (offset - alignedStart);
buffer.limit(0);
}
+ // visible for test: true until the first fill
+ boolean isDeferred() {
+ return pendingDelta >= 0;
+ }
+
private static ByteBuffer allocateBuffer(int bufferSize, int blockSize) {
return ByteBuffer.allocateDirect(bufferSize + blockSize - 1)
.alignedSlice(blockSize)
@@ -370,7 +390,9 @@ public class DirectIODirectory extends FilterDirectory {
// refill) first,
// will result in negative value equal to bufferSize being returned,
// due to the initialization method filePos = -bufferSize used in constructor.
- assert filePointer == -buffer.capacity() - offset || filePointer >= 0
+ // Before its first fill a lazily positioned clone/slice is further offset by its pending
+ // delta, because its filePos starts at alignedStart - bufferSize rather than -bufferSize.
+ assert filePointer == -buffer.capacity() - Math.max(pendingDelta, 0) || filePointer >= 0
: "filePointer should either be initial value equal to negative buffer capacity, or larger than or equal to 0";
return Math.max(filePointer, 0);
}
@@ -378,6 +400,15 @@ public class DirectIODirectory extends FilterDirectory {
@Override
public void seek(long pos) throws IOException {
if (pos != getFilePointer()) {
+ if (pendingDelta >= 0) {
+ // A slice that has not been read yet fills first, so the window check below sees the
+ // same buffer the eager code had: a seek past this input's length that lands in that
+ // block repositions within it instead of failing, as it always has.
+ final int parked = pendingDelta;
+ pendingDelta = -1;
+ fill(parked);
+ buffer.position(parked);
+ }
final long absolutePos = pos + offset;
if (absolutePos >= filePos && absolutePos <= filePos + buffer.limit()) {
// the new position is within the existing buffer
@@ -390,6 +421,10 @@ public class DirectIODirectory extends FilterDirectory {
}
private void seekInternal(long pos) throws IOException {
+ // An explicit seek replaces a pending start, and its refill must check EOF against this
+ // position rather than the pending one. Only clone() gets here with a pending start: it
+ // positions a fresh clone at the parent's file pointer.
+ pendingDelta = -1;
final long absPos = pos + offset;
final long alignedPos = absPos - (absPos % blockSize);
filePos = alignedPos - buffer.capacity();
@@ -441,6 +476,23 @@ public class DirectIODirectory extends FilterDirectory {
}
private void refill(int bytesToRead) throws IOException {
+ final int parked = pendingDelta;
+ if (parked >= 0) {
+ // First fill of a slice with a pending start: fill and position exactly as the constructor
+ // used to, so the EOF check uses the pending offset and an over-long first read behaves as
+ // before. If that leaves nothing to read (a zero-length slice at the very end of the file),
+ // fall through so the caller's own read throws EOFException as it always did.
+ pendingDelta = -1;
+ fill(parked);
+ buffer.position(parked);
+ if (buffer.hasRemaining()) {
+ return;
+ }
+ }
+ fill(bytesToRead);
+ }
+
+ private void fill(int bytesToRead) throws IOException {
filePos += buffer.capacity();
// BaseDirectoryTestCase#testSeekPastEOF test for consecutive read past EOF,
@@ -553,9 +605,9 @@ public class DirectIODirectory extends FilterDirectory {
throw new IllegalArgumentException(
"slice() " + sliceDescription + " out of bounds: " + this);
}
- var slice = new DirectIOIndexInput(sliceDescription, this, this.offset + offset, length);
- slice.seekInternal(0L);
- return slice;
+ // The constructor remembers the start position and the first read resolves it, so
+ // constructing a slice performs no I/O.
+ return new DirectIOIndexInput(sliceDescription, this, this.offset + offset, length);
}
}
}
diff --git a/lucene/misc/src/test/org/apache/lucene/misc/store/TestDirectIODirectory.java b/lucene/misc/src/test/org/apache/lucene/misc/store/TestDirectIODirectory.java
index 32f375cd28f..6b533bca257 100644
--- a/lucene/misc/src/test/org/apache/lucene/misc/store/TestDirectIODirectory.java
+++ b/lucene/misc/src/test/org/apache/lucene/misc/store/TestDirectIODirectory.java
@@ -16,6 +16,8 @@
*/
package org.apache.lucene.misc.store;
+import static org.hamcrest.Matchers.greaterThanOrEqualTo;
+
import com.carrotsearch.randomizedtesting.RandomizedTest;
import java.io.EOFException;
import java.io.IOException;
@@ -38,6 +40,7 @@ import org.apache.lucene.store.IndexOutput;
import org.apache.lucene.store.MergeInfo;
import org.apache.lucene.tests.index.RandomIndexWriter;
import org.apache.lucene.tests.store.BaseDirectoryTestCase;
+import org.apache.lucene.util.ArrayUtil;
import org.junit.BeforeClass;
public class TestDirectIODirectory extends BaseDirectoryTestCase {
@@ -218,6 +221,263 @@ public class TestDirectIODirectory extends BaseDirectoryTestCase {
}
}
+ private static byte[] writeRandomFile(Directory dir, String name, int size) throws IOException {
+ byte[] bytes = new byte[size];
+ random().nextBytes(bytes);
+ try (IndexOutput o = dir.createOutput(name, IOContext.DEFAULT)) {
+ o.writeBytes(bytes, 0, size);
+ }
+ return bytes;
+ }
+
+ /**
+ * Slice offsets to exercise: the start of the file, a few unaligned offsets inside the first
+ * block (the shape of a codec header), two block starts and an unaligned offset after one, the
+ * last four bytes of the file, plus random offsets. Offsets stop at {@code fileSize - 2} so every
+ * slice is at least two bytes long, which the correctness matrix relies on for its inner-slice
+ * and clone cases.
+ */
+ private static long[] sliceOffsets(int blockSize, int fileSize) {
+ assert fileSize >= 4 * blockSize;
+ long[] fixed = {0, 1, 7, 96, blockSize, blockSize + 188, 2L * blockSize, fileSize - 4};
+ long[] offsets = ArrayUtil.growExact(fixed, fixed.length + atLeast(3));
+ for (int i = fixed.length; i < offsets.length; i++) {
+ offsets[i] = RandomizedTest.randomLongBetween(0, fileSize - 2);
+ }
+ return offsets;
+ }
+
+ public void testSliceDefersIOAtEveryOffset() throws Exception {
+ Path path = createTempDir("testSliceDefersIOAtEveryOffset");
+ final int blockSize = Math.toIntExact(Files.getFileStore(path).getBlockSize());
+ final int fileSize = 4 * blockSize;
+ try (Directory dir = getDirectory(path)) {
+ byte[] bytes = writeRandomFile(dir, "out", fileSize);
+ final long[] offsets = sliceOffsets(blockSize, fileSize);
+ try (IndexInput in = dir.openInput("out", IOContext.DEFAULT)) {
+ for (long offset : offsets) {
+ IndexInput slice = in.slice("slice@" + offset, offset, fileSize - offset);
+ DirectIODirectory.DirectIOIndexInput directSlice =
+ (DirectIODirectory.DirectIOIndexInput) slice;
+ assertTrue(
+ "slice at offset " + offset + " did not defer its first fill",
+ directSlice.isDeferred());
+ assertEquals(0L, slice.getFilePointer());
+ assertEquals(
+ "first byte of slice at offset " + offset, bytes[(int) offset], slice.readByte());
+ assertFalse(directSlice.isDeferred());
+ }
+ }
+ }
+ }
+
+ public void testSliceCorrectnessMatrix() throws Exception {
+ Path path = createTempDir("testSliceCorrectnessMatrix");
+ final int blockSize = Math.toIntExact(Files.getFileStore(path).getBlockSize());
+ final int fileSize = 4 * blockSize;
+ try (Directory dir = getDirectory(path)) {
+ byte[] bytes = writeRandomFile(dir, "out", fileSize);
+ final long[] offsets = sliceOffsets(blockSize, fileSize);
+ try (IndexInput in = dir.openInput("out", IOContext.DEFAULT)) {
+ for (long offset : offsets) {
+ final long[] lengths = {1, 4, blockSize - 7, blockSize, blockSize + 3, fileSize - offset};
+ for (long length : lengths) {
+ if (length <= 0 || length > fileSize - offset) {
+ continue;
+ }
+ final int len = (int) length;
+ // full read-through of the slice equals the same range of the parent
+ IndexInput slice = in.slice("s", offset, length);
+ byte[] actual = new byte[len];
+ slice.readBytes(actual, 0, len);
+ assertArrayEquals(
+ "offset " + offset + " length " + length,
+ ArrayUtil.copyOfSubArray(bytes, (int) offset, (int) offset + len),
+ actual);
+ if (len >= 2) {
+ // slice-of-slice at a non-zero inner offset
+ IndexInput inner = in.slice("s", offset, length).slice("ss", 1, length - 1);
+ byte[] innerBytes = new byte[len - 1];
+ inner.readBytes(innerBytes, 0, len - 1);
+ assertArrayEquals(
+ "inner slice at offset " + offset + " length " + length,
+ ArrayUtil.copyOfSubArray(bytes, (int) offset + 1, (int) offset + len),
+ innerBytes);
+ // clone-after-partial-read starts at the parent's position
+ IndexInput partial = in.slice("s", offset, length);
+ partial.readBytes(new byte[len / 2], 0, len / 2);
+ IndexInput clone = partial.clone();
+ assertEquals(len / 2, clone.getFilePointer());
+ byte[] rest = new byte[len - len / 2];
+ clone.readBytes(rest, 0, rest.length);
+ assertArrayEquals(
+ "clone at offset " + offset + " length " + length,
+ ArrayUtil.copyOfSubArray(bytes, (int) offset + len / 2, (int) offset + len),
+ rest);
+ }
+ }
+ }
+ }
+ }
+ }
+
+ public void testSeekResolvesFreshParkedSlice() throws Exception {
+ Path path = createTempDir("testSeekResolvesFreshParkedSlice");
+ final int blockSize = Math.toIntExact(Files.getFileStore(path).getBlockSize());
+ final int fileSize = DirectIODirectory.DEFAULT_MERGE_BUFFER_SIZE + 3 * blockSize;
+ try (Directory dir = getDirectory(path)) {
+ byte[] bytes = writeRandomFile(dir, "out", fileSize);
+ final long[] offsets = {1, 96, blockSize + 188};
+ try (IndexInput in = dir.openInput("out", IOContext.DEFAULT)) {
+ for (long offset : offsets) {
+ final long length =
+ Math.min(DirectIODirectory.DEFAULT_MERGE_BUFFER_SIZE, fileSize - offset);
+ IndexInput slice = in.slice("s", offset, length);
+ // seek() on a slice that has not been read yet must position it correctly: the byte
+ // read is the slice's own last byte, not one relative to the wrong base.
+ slice.seek(length - 1);
+ assertEquals("offset " + offset, bytes[(int) (offset + length - 1)], slice.readByte());
+ assertEquals(length, slice.getFilePointer());
+ }
+ }
+ }
+ }
+
+ public void testCloneOfPartiallyReadUnalignedSliceResolvesToItsPosition() throws Exception {
+ // clone() positions a fresh clone at the parent's file pointer through seekInternal, and is
+ // the only caller that reaches it with a pending start. If seekInternal did not drop that
+ // pending start first, a clone taken after a partial read of a short unaligned slice would
+ // read the wrong bytes or throw EOFException.
+ Path path = createTempDir("testCloneOfPartiallyReadSlice");
+ final int blockSize = Math.toIntExact(Files.getFileStore(path).getBlockSize());
+ final int fileSize = 4 * blockSize;
+ try (Directory dir = getDirectory(path)) {
+ byte[] bytes = writeRandomFile(dir, "out", fileSize);
+ final long[] offsets = {1, 96, blockSize + 188, 3L * blockSize - 4};
+ try (IndexInput in = dir.openInput("out", IOContext.DEFAULT)) {
+ for (long offset : offsets) {
+ final long length = Math.min(blockSize - 7, fileSize - offset);
+ IndexInput partial = in.slice("s", offset, length);
+ final int half = (int) length / 2;
+ partial.readBytes(new byte[half], 0, half);
+ IndexInput clone = partial.clone();
+ assertEquals("offset " + offset, half, clone.getFilePointer());
+ byte[] rest = new byte[(int) length - half];
+ clone.readBytes(rest, 0, rest.length);
+ assertArrayEquals(
+ "offset " + offset,
+ ArrayUtil.copyOfSubArray(bytes, (int) offset + half, (int) offset + (int) length),
+ rest);
+ }
+ }
+ }
+ }
+
+ /**
+ * A characterization test, not an endorsement. Today a read past a slice's own length is served
+ * from the buffered block as long as it stays inside the window, and only a read that runs off
+ * the end of the window throws {@link EOFException}. That quirk predates this change; the lazy
+ * first fill must reproduce it exactly rather than "fix" it in passing. If the quirk is ever
+ * removed on purpose, this test should change with it.
+ */
+ public void testFirstFillEofSemanticsMatchEagerFill() throws Exception {
+ Path path = createTempDir("testFirstFillEofSemantics");
+ final int blockSize = Math.toIntExact(Files.getFileStore(path).getBlockSize());
+ final int fileSize = 4 * blockSize;
+ // the oracle below relies on the whole file fitting in one buffer window
+ assumeTrue(
+ "file must fit in one buffer window",
+ fileSize <= DirectIODirectory.DEFAULT_MERGE_BUFFER_SIZE);
+ try (Directory dir = getDirectory(path)) {
+ byte[] bytes = writeRandomFile(dir, "out", fileSize);
+ final long[] offsets = {0, 96, blockSize, fileSize - 5};
+ final long[] lengths = {0, 1, 4, blockSize};
+ try (IndexInput in = dir.openInput("out", IOContext.DEFAULT)) {
+ for (long offset : offsets) {
+ for (long l : lengths) {
+ final long length = Math.min(l, fileSize - offset);
+ final int[] readLens = {1, 4, (int) length + 2, blockSize + 32, fileSize};
+ for (int readLen : readLens) {
+ IndexInput slice = in.slice("s", offset, length);
+ final String cell = "offset=" + offset + " length=" + length + " readLen=" + readLen;
+ // if the first fill ever checked EOF against the caller's read length instead of
+ // the pending offset, the in-window cells below would fail
+ if (readLen <= fileSize - offset) {
+ byte[] dst = new byte[readLen];
+ slice.readBytes(dst, 0, readLen);
+ assertArrayEquals(
+ cell,
+ ArrayUtil.copyOfSubArray(bytes, (int) offset, (int) offset + readLen),
+ dst);
+ } else {
+ expectThrows(
+ EOFException.class, cell, () -> slice.readBytes(new byte[readLen], 0, readLen));
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+
+ public void testZeroLengthSliceAtFileEndThrowsEOF() throws Exception {
+ Path path = createTempDir("testZeroLengthSliceAtFileEnd");
+ final int blockSize = Math.toIntExact(Files.getFileStore(path).getBlockSize());
+ // one file whose length is a multiple of the block size (pending offset 0) and one whose
+ // length is not
+ final int[] fileSizes = {2 * blockSize, 2 * blockSize + 300};
+ try (Directory dir = getDirectory(path)) {
+ for (int fileSize : fileSizes) {
+ String name = "out" + fileSize;
+ writeRandomFile(dir, name, fileSize);
+ try (IndexInput in = dir.openInput(name, IOContext.DEFAULT)) {
+ IndexInput slice = in.slice("end", in.length(), 0);
+ // the exception type matters: a first fill that finds nothing to read must fall
+ // through to the caller's own read and throw EOFException, not a
+ // BufferUnderflowException from an empty buffer
+ expectThrows(EOFException.class, "file size " + fileSize, slice::readByte);
+ }
+ }
+ }
+ }
+
+ public void testSeekBeyondSliceLengthMatchesEagerBehaviour() throws Exception {
+ Path path = createTempDir("testSeekBeyondSliceLength");
+ final int blockSize = Math.toIntExact(Files.getFileStore(path).getBlockSize());
+ final int fileSize = 4 * blockSize;
+ assumeTrue(
+ "file must fit in one buffer window",
+ fileSize <= DirectIODirectory.DEFAULT_MERGE_BUFFER_SIZE);
+ try (Directory dir = getDirectory(path)) {
+ byte[] bytes = writeRandomFile(dir, "out", fileSize);
+ try (IndexInput in = dir.openInput("out", IOContext.DEFAULT)) {
+ // seek targets inside the block the eager code buffered at construction: today the
+ // seek silently repositions and the read serves the byte beyond the slice's end. A
+ // fresh lazy slice must do the same rather than throw EOFException, and
+ // getFilePointer() must return normally afterwards (assertions are enabled)
+ final long[] offsets = {blockSize, blockSize + 188};
+ final long[] seekTargets = {10, blockSize + 50L};
+ for (long offset : offsets) {
+ for (long target : seekTargets) {
+ IndexInput slice = in.slice("s", offset, 4);
+ slice.seek(target);
+ assertEquals(
+ "offset " + offset + " target " + target,
+ bytes[(int) (offset + target)],
+ slice.readByte());
+ assertEquals(target + 1, slice.getFilePointer());
+ }
+ }
+ // a target outside the buffered window: the refill checks EOF against the slice's own
+ // end and throws, as today; getFilePointer() must still return normally afterwards
+ IndexInput far = in.slice("s", blockSize + 188, 4);
+ expectThrows(
+ EOFException.class, () -> far.seek(DirectIODirectory.DEFAULT_MERGE_BUFFER_SIZE + 100L));
+ assertThat(far.getFilePointer(), greaterThanOrEqualTo(0L));
+ }
+ }
+ }
+
// Ping-pong seeks should be really fast, since the position should be within buffer.
// The test should complete within sub-second times, not minutes.
public void testSeekSmall() throws IOException {