- * the file pointer will be left at endOffset. - *
+ * Returns the CRC32 checksum for the range [startOffset .. endOffset) + * + * The file pointer will be left at endOffset. */ @Override public long checksum(long startOffset, long endOffset) throws IOException { diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ByteBufferReader.java b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ByteBufferReader.java index f74ec76eb..9d02269d7 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ByteBufferReader.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ByteBufferReader.java @@ -23,8 +23,13 @@ * RandomAccessReader that reads from a ByteBuffer */ public class ByteBufferReader implements RandomAccessReader { + /** The underlying ByteBuffer. */ protected final ByteBuffer bb; + /** + * Creates a ByteBufferReader from the given ByteBuffer. + * @param sourceBB the source ByteBuffer + */ public ByteBufferReader(ByteBuffer sourceBB) { bb = sourceBB; } diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/IndexWriter.java b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/IndexWriter.java index 9a214425b..1ec2730ab 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/IndexWriter.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/IndexWriter.java @@ -20,9 +20,14 @@ import java.io.DataOutput; import java.io.IOException; +/** + * Interface for writing index data. + */ public interface IndexWriter extends DataOutput, Closeable { /** + * Returns the current position in the output. * @return the current position in the output + * @throws IOException if an I/O error occurs */ long position() throws IOException; } diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/RandomAccessReader.java b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/RandomAccessReader.java index a09081a28..09e751e1a 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/RandomAccessReader.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/RandomAccessReader.java @@ -32,32 +32,99 @@ * uses the ReaderSupplier API to create a RandomAccessReader per thread, as needed. */ public interface RandomAccessReader extends AutoCloseable { + /** + * Seeks to the specified offset. + * @param offset the offset to seek to + * @throws IOException if an I/O error occurs + */ void seek(long offset) throws IOException; + /** + * Returns the current position. + * @return the current position + * @throws IOException if an I/O error occurs + */ long getPosition() throws IOException; + /** + * Reads an integer. + * @return the integer value + * @throws IOException if an I/O error occurs + */ int readInt() throws IOException; + /** + * Reads a float. + * @return the float value + * @throws IOException if an I/O error occurs + */ float readFloat() throws IOException; + /** + * Reads a long. + * @return the long value + * @throws IOException if an I/O error occurs + */ long readLong() throws IOException; + /** + * Reads bytes into the array. + * @param bytes the byte array to read into + * @throws IOException if an I/O error occurs + */ void readFully(byte[] bytes) throws IOException; + /** + * Reads bytes into the buffer. + * @param buffer the ByteBuffer to read into + * @throws IOException if an I/O error occurs + */ void readFully(ByteBuffer buffer) throws IOException; + /** + * Reads floats into the array. + * @param floats the float array to read into + * @throws IOException if an I/O error occurs + */ default void readFully(float[] floats) throws IOException { read(floats, 0, floats.length); } + /** + * Reads longs into the array. + * @param vector the long array to read into + * @throws IOException if an I/O error occurs + */ void readFully(long[] vector) throws IOException; + /** + * Reads integers into the array. + * @param ints the int array to read into + * @param offset the offset in the array + * @param count the number of integers to read + * @throws IOException if an I/O error occurs + */ void read(int[] ints, int offset, int count) throws IOException; + /** + * Reads floats into the array. + * @param floats the float array to read into + * @param offset the offset in the array + * @param count the number of floats to read + * @throws IOException if an I/O error occurs + */ void read(float[] floats, int offset, int count) throws IOException; + /** + * Closes this reader. + * @throws IOException if an I/O error occurs + */ void close() throws IOException; - // Length of the reader slice + /** + * Returns the length of the reader slice. + * @return the length + * @throws IOException if an I/O error occurs + */ long length() throws IOException; } diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/RandomAccessWriter.java b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/RandomAccessWriter.java index ef7202894..f363fe5ff 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/RandomAccessWriter.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/RandomAccessWriter.java @@ -24,9 +24,25 @@ * A DataOutput that adds methods for random access writes */ public interface RandomAccessWriter extends IndexWriter { + /** + * Seeks to the specified position. + * @param position the position to seek to + * @throws IOException if an I/O error occurs + */ void seek(long position) throws IOException; + /** + * Flushes any buffered data. + * @throws IOException if an I/O error occurs + */ void flush() throws IOException; + /** + * Computes a checksum for the specified range. + * @param startOffset the start offset + * @param endOffset the end offset + * @return the checksum value + * @throws IOException if an I/O error occurs + */ long checksum(long startOffset, long endOffset) throws IOException; } diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ReaderSupplier.java b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ReaderSupplier.java index 8f8d2ae2c..30431d6ca 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ReaderSupplier.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ReaderSupplier.java @@ -23,8 +23,10 @@ */ public interface ReaderSupplier extends AutoCloseable { /** + * Creates a new reader. * @return a new reader. It is up to the caller to re-use these readers or close them, * the ReaderSupplier is not responsible for caching them. + * @throws IOException if an I/O error occurs */ RandomAccessReader get() throws IOException; diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ReaderSupplierFactory.java b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ReaderSupplierFactory.java index dd0a22659..6a623ce12 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ReaderSupplierFactory.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/ReaderSupplierFactory.java @@ -22,11 +22,26 @@ import java.util.logging.Level; import java.util.logging.Logger; +/** + * Factory for creating ReaderSupplier instances. + */ public class ReaderSupplierFactory { private static final Logger LOG = Logger.getLogger(ReaderSupplierFactory.class.getName()); private static final String MEMORY_SEGMENT_READER_CLASSNAME = "io.github.jbellis.jvector.disk.MemorySegmentReader$Supplier"; private static final String MMAP_READER_CLASSNAME = "io.github.jbellis.jvector.example.util.MMapReader$Supplier"; + /** + * Private constructor to prevent instantiation. + */ + private ReaderSupplierFactory() { + } + + /** + * Opens a ReaderSupplier for the given path. + * @param path the path to open + * @return a ReaderSupplier for the path + * @throws IOException if an I/O error occurs + */ public static ReaderSupplier open(Path path) throws IOException { try { // prefer MemorySegmentReader (available under JDK 20+) diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleMappedReader.java b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleMappedReader.java index f55688e94..251592d64 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleMappedReader.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleMappedReader.java @@ -55,10 +55,18 @@ public void close() { // Individual readers don't close anything } + /** + * Supplier for SimpleMappedReader instances. + */ public static class Supplier implements ReaderSupplier { private final MappedByteBuffer buffer; private static final Unsafe unsafe = getUnsafe(); + /** + * Creates a Supplier for the given path. + * @param path the path to read from + * @throws IOException if an I/O error occurs + */ public Supplier(Path path) throws IOException { try (var raf = new RandomAccessFile(path.toString(), "r")) { if (raf.length() > Integer.MAX_VALUE) { diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleReader.java b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleReader.java index 07d9488a1..659c44dc7 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleReader.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleReader.java @@ -23,12 +23,17 @@ import java.nio.ByteOrder; import java.nio.file.Path; -// TODO what are the low-hanging optimization options here? -// The requirement that we need to read from a file that is potentially changing in length -// limits our options. +/** + * Simple implementation of RandomAccessReader using RandomAccessFile. + */ public class SimpleReader implements RandomAccessReader { RandomAccessFile raf; + /** + * Creates a SimpleReader for the given path. + * @param path the path to read from + * @throws FileNotFoundException if the file cannot be found + */ public SimpleReader(Path path) throws FileNotFoundException { raf = new RandomAccessFile(path.toFile(), "r"); } @@ -105,9 +110,16 @@ public long length() throws IOException { return raf.length(); } + /** + * Supplier for SimpleReader instances. + */ public static class Supplier implements ReaderSupplier { private final Path path; + /** + * Creates a Supplier for the given path. + * @param path the path to read from + */ public Supplier(Path path) { this.path = path; } diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleWriter.java b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleWriter.java index e6462a373..899f18361 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleWriter.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/disk/SimpleWriter.java @@ -30,6 +30,11 @@ public class SimpleWriter implements IndexWriter { private final FileOutputStream fos; private final DataOutputStream dos; + /** + * Creates a SimpleWriter for the given path. + * @param path the path to write to + * @throws IOException if an I/O error occurs + */ public SimpleWriter(Path path) throws IOException { fos = new FileOutputStream(path.toFile()); dos = new DataOutputStream(fos); diff --git a/jvector-base/src/main/java/io/github/jbellis/jvector/exceptions/ThreadInterruptedException.java b/jvector-base/src/main/java/io/github/jbellis/jvector/exceptions/ThreadInterruptedException.java index 0445252a1..e24692e8c 100644 --- a/jvector-base/src/main/java/io/github/jbellis/jvector/exceptions/ThreadInterruptedException.java +++ b/jvector-base/src/main/java/io/github/jbellis/jvector/exceptions/ThreadInterruptedException.java @@ -24,7 +24,14 @@ package io.github.jbellis.jvector.exceptions; +/** + * RuntimeException wrapper for InterruptedException. + */ public final class ThreadInterruptedException extends RuntimeException { + /** + * Creates a ThreadInterruptedException wrapping the given InterruptedException. + * @param ie the InterruptedException to wrap + */ public ThreadInterruptedException(InterruptedException ie) { super(ie); }