DirectIODirectory (Lucene 10.5.0 misc API)
Description: declaration: package: org.apache.lucene.misc.store, class: DirectIODirectory

Package org.apache.lucene.misc.store

# Class DirectIODirectory

java.lang.Object
org.apache.lucene.store.Directory
org.apache.lucene.store.FilterDirectory
org.apache.lucene.misc.store.DirectIODirectory

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public class DirectIODirectory extends FilterDirectory
A `Directory` implementation for all Unixes and Windows that uses DIRECT I/O to bypass OS level IO caching during merging. For all other cases (searching, writing) we delegate to the provided Directory instance.

See Overview for more details.

WARNING: this code is very new and quite easily could contain horrible bugs.

This directory passes Solr and Lucene tests on Linux, OS X, and Windows; other systems should work but have not been tested! Use at your own risk.

@throws UnsupportedOperationException if the operating system, file system or JDK does not support Direct I/O or a sufficient equivalent.

WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_MERGE_BUFFER_SIZE`
  Default buffer size before writing to disk (256 KB); larger means less IO load but more RAM and direct buffer storage space consumed during merging.
  `static final long`
  `DEFAULT_MIN_BYTES_DIRECT`
  Default min expected merge size before direct IO is used (10 MB):

  ### Fields inherited from class org.apache.lucene.store.FilterDirectory

  `in`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DirectIODirectory(FSDirectory delegate)`
  Create a new DirectIODirectory for the named location.
  `DirectIODirectory(FSDirectory delegate, int mergeBufferSize, long minBytesDirect)`
  Create a new DirectIODirectory for the named location.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  `IndexOutput`
  `createOutput(String name, IOContext context)`
  `protected void`
  `ensureOpen()`
  `Path`
  `getDirectory()`
  `IndexInput`
  `openInput(String name, IOContext context)`
  `protected boolean`
  `useDirectIO(String name, IOContext context, OptionalLong fileLength)`
  Determines if direct IO should be used for a file.

  ### Methods inherited from class org.apache.lucene.store.FilterDirectory

  `createTempOutput, deleteFile, fileLength, getDelegate, getPendingDeletions, listAll, obtainLock, rename, sync, syncMetaData, toString, unwrap`

  ### Methods inherited from class org.apache.lucene.store.Directory

  `copyFrom, getTempFileName, openChecksumInput`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### DEFAULT_MERGE_BUFFER_SIZE

    public static final int DEFAULT_MERGE_BUFFER_SIZE
    Default buffer size before writing to disk (256 KB); larger means less IO load but more RAM and direct buffer storage space consumed during merging.
    See Also:
      - Constant Field Values

  - ### DEFAULT_MIN_BYTES_DIRECT

    public static final long DEFAULT_MIN_BYTES_DIRECT
    Default min expected merge size before direct IO is used (10 MB):
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### DirectIODirectory

    public DirectIODirectory(FSDirectory delegate, int mergeBufferSize, long minBytesDirect) throws IOException
    Create a new DirectIODirectory for the named location.
    Parameters:
      `delegate` - Directory for non-merges, also used as reference to file system path.
      `mergeBufferSize` - Size of buffer to use for merging.
      `minBytesDirect` - Merges, or files to be opened for reading, smaller than this will not use direct IO. See `DEFAULT_MIN_BYTES_DIRECT` and `useDirectIO(java.lang.String, org.apache.lucene.store.IOContext, java.util.OptionalLong)`.
    Throws:
      `IOException` - If there is a low-level I/O error

  - ### DirectIODirectory

    public DirectIODirectory(FSDirectory delegate) throws IOException
    Create a new DirectIODirectory for the named location.
    Parameters:
      `delegate` - Directory for non-merges, also used as reference to file system path.
    Throws:
      `IOException` - If there is a low-level I/O error

- ## Method Details

  - ### getDirectory

    public Path getDirectory()
    Returns:
      the underlying file system directory

  - ### ensureOpen

    protected void ensureOpen() throws AlreadyClosedException
    Overrides:
      `ensureOpen` in class `FilterDirectory`
    Throws:
      `AlreadyClosedException`

  - ### useDirectIO

    protected boolean useDirectIO(String name, IOContext context, OptionalLong fileLength)
    Determines if direct IO should be used for a file. By default this tests if it is a merge context and if the merge or file length extends the minimum size (see `DEFAULT_MIN_BYTES_DIRECT`). Subclasses may override method to enforce direct IO for specific file types.
    Parameters:
      `name` - file name (unused by default implementation)
      `context` - information about merge size
      `fileLength` - if available, gives the file length. Will be empty when requesting an `IndexOutput`.
    Returns:
      `true` if direct IO should be used; `false` if input/output should be requested from delegate directory.

  - ### openInput

    public IndexInput openInput(String name, IOContext context) throws IOException
    Overrides:
      `openInput` in class `FilterDirectory`
    Throws:
      `IOException`

  - ### createOutput

    public IndexOutput createOutput(String name, IOContext context) throws IOException
    Overrides:
      `createOutput` in class `FilterDirectory`
    Throws:
      `IOException`

  - ### close

    public void close() throws IOException
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Overrides:
      `close` in class `FilterDirectory`
    Throws:
      `IOException`