MMapDirectory
File-based Directory implementation that uses mmap for reading, and [ ] for writing.
NOTE: memory mapping uses up a portion of the virtual memory address space in your process equal to the size of the file being mapped. Before using this class, be sure your have plenty of virtual address space, e.g. by using a 64 bit JRE, or a 32 bit JRE with indexes that are guaranteed to fit within the address space. On 32 bit platforms also consult .MMapDirectory if you have problems with mmap failing because of fragmented address space. If you get an IOException about mapping failed, it is recommended to reduce the chunk size, until it works.
This class supports preloading files into physical memory upon opening. This can help improve performance of searches on a cold page cache at the expense of slowing down opening an index. See .setPreload for more details.
This class supports grouping of files that are part of the same logical group. This is a hint that allows for better handling of resources. For example, individual files that are part of the same segment can be considered part of the same logical group. See .setGroupingFunction for more details.
This class will use the modern foreign.MemorySegment API available since Java 21 which allows to safely unmap previously mmapped files after closing the [ ]s. There is no need to enable the "preview feature" of your Java version; it works out of box with some compilation tricks. For more information about the foreign memory API read documentation of the foreign package.
On some platforms like Linux and MacOS X, this class will invoke the syscall madvise() to advise how OS kernel should handle paging after opening a file. For this to work, Java code must be able to call native code. If this is not allowed, a warning is logged. To enable native access for Lucene in a modularized application, pass --enable-native-access=org.apache.lucene.core to the Java command line. If Lucene is running in a classpath-based application, use --enable-native-access=ALL-UNNAMED.
NOTE: Accessing this class either directly or indirectly from a thread while it's interrupted can close the underlying channel immediately if at the same time the thread is blocked on IO. The channel will remain closed and subsequent access to MMapDirectory will throw a ClosedChannelException. If your application uses either Thread.interrupt or Future.cancel you should use the legacy RAFDirectory from the Lucene misc module in favor of MMapDirectory.
NOTE: If your application requires external synchronization, you should not synchronize on the MMapDirectory instance as this may cause deadlock; use your own (non-Lucene) objects instead.
See also
KMP note: On Kotlin Multiplatform targets this class provides an mmap-compatible API but uses a non-mmap implementation backed by regular file reads (okio + positional IO). This keeps Lucene API behavior (random-access IndexInput, clone/slice semantics, thread-safe positional reads, close semantics) without relying on JDK 21+ foreign memory APIs.
Constructors
Create a new MMapDirectory for the named location and FSLockFactory.getDefault. The directory is created at the named location if it does not yet exist.
Properties
Functions
Creates a new, empty file in the directory and returns an IndexOutput instance for appending data to this file.
Creates a new, empty, temporary file in the directory and returns an IndexOutput instance for appending data to this file.
Removes an existing file in the directory.
Try to delete any pending files that we had previously tried to delete but failed because we are on Windows and the files were still held open.
Ensures this directory is still open.
Returns the byte length of a file in the directory.
Returns names of all files stored in this directory. The output must be in sorted (UTF-16, java's String.compareTo) order.
Acquires and returns a Lock for a file with the given name.
Opens a checksum-computing stream for reading an existing file.
Creates an IndexInput for the file with the given name.
Configures a grouping function for files that are part of the same logical group. The gathering of files into a logical group is a hint that allows for better handling of resources.
Configure which files to preload in physical memory upon opening. The default implementation does not preload anything. The behavior is best effort and operating system-dependent.
Ensures that any writes to these files are moved to stable storage (made durable).
Ensures that directory metadata, such as recent file renames, are moved to stable storage.