Package dev.vortex.io

Interface NativeReadable

All Superinterfaces:
AutoCloseable, Closeable
public interface NativeReadable extends Closeable
A random-access byte source supplied by the caller and read from native code.

Implementations bridge external I/O abstractions — for example Iceberg's FileIO input streams — into the Vortex native reader. The native side invokes readFully(long, ByteBuffer) from its own worker threads, potentially many calls concurrently, so implementations must be safe for concurrent positional reads (typically by opening one underlying stream per concurrent call, or delegating to a positional-read API).

Lifecycle: the creator owns this object. Native code never calls Closeable.close(); close it only after every data source or scan built on top of it has been closed.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    length()
    Total length of the source in bytes.
    String
    name()
    Unique name of this source, typically its original location (URI or file path).
    void
    readFully(long position, ByteBuffer buffer)
    Read exactly buffer.remaining() bytes starting at absolute position into buffer.

    Methods inherited from interface java.io.Closeable

    close

  • Method Details

    • name

      String name()
      Unique name of this source, typically its original location (URI or file path). Used to key per-session caches and in native error messages, so it must be stable and unique across sources; it must not contain glob characters (*?[).

    • length

      long length()
      Total length of the source in bytes. Must be cheap; called once when the source is registered.

    • readFully

      void readFully(long position, ByteBuffer buffer) throws IOException
      Read exactly buffer.remaining() bytes starting at absolute position into buffer.

      Unlike InputStream.read(), short reads are not permitted: implementations must either fill the buffer completely (buffer.remaining() == 0 on return) or throw.

      buffer is a direct ByteBuffer wrapping native memory owned by the caller, so bytes written to it land in the native reader without an extra copy. It is valid only for the duration of this call: implementations must not retain a reference to it after returning. Implementations backed by byte[] APIs can bulk-put into it.

      Throws:
      EOFException - if the range extends past the end of the source
      IOException - if the underlying storage fails