org.neo4j.io.pagecache

Interface PageCache

All Superinterfaces:

AutoCloseable

public interface PageCache
extends AutoCloseable

A page caching mechanism that allows caching multiple files and accessing their data in pages via a re-usable cursor.

This interface does not specify the cache eviction and allocation behavior, it may be backed by implementations that map entire files into RAM, or implementations with smart eviction strategies, trying to keep "hot" pages in RAM.

Method Summary

Modifier and Type	Method and Description
void	close() Close the page cache to prevent any future mapping of files.
void	flushAndForce() Flush all dirty pages
void	flushAndForce(IOLimiter limiter) Flush all dirty pages, but limit the rate of IO as advised by the given IOPSLimiter.
Optional<PagedFile>	getExistingMapping(File file) Ask for an already mapped paged file, backed by this page cache.
PagedFile	map(File file, int pageSize, OpenOption... openOptions) Ask for a handle to a paged file, backed by this page cache.
int	maxCachedPages() The max number of cached pages.
int	pageSize() The size in bytes of the pages managed by this cache.
Stream<FileHandle>	streamFilesRecursive(File directory) Return a stream of file handles for every file in the given directory, and its sub-directories.

Method Detail

map

PagedFile map(File file,
              int pageSize,
              OpenOption... openOptions)
       throws IOException

Ask for a handle to a paged file, backed by this page cache.

Note that this currently asks for the pageSize to use, which is an artifact or records being of varying size in the stores. This should be consolidated to use a standard page size for the whole cache, with records aligning on those page boundaries.

Parameters:

file - The file to map.

pageSize - The file page size to use for this mapping. If the file is already mapped with a different page size, an exception will be thrown.

openOptions - The set of open options to use for mapping this file. The StandardOpenOption.READ and StandardOpenOption.WRITE options always implicitly specified. The StandardOpenOption.CREATE open option will create the given file if it does not already exist, and the StandardOpenOption.TRUNCATE_EXISTING will truncate any existing file iff it has not already been mapped. The StandardOpenOption.DELETE_ON_CLOSE will cause the file to be deleted after the last unmapping. All other options are either silently ignored, or will cause an exception to be thrown.

Throws:

NoSuchFileException - if the given file does not exist, and the StandardOpenOption.CREATE option was not specified.

IOException - if the file could otherwise not be mapped. Causes include the file being locked.

getExistingMapping

Optional<PagedFile> getExistingMapping(File file)
                                throws IOException

Ask for an already mapped paged file, backed by this page cache.

If mapping exist, the returned Optional will report Optional.isPresent() true and Optional.get() will return the same PagedFile instance that was initially returned my map(File, int, OpenOption...). If no mapping exist for this file, then returned Optional will report Optional.isPresent() false.

NOTE! User is responsible for closing the returned paged file.

Parameters:

file - The file to try to get the mapped paged file for.

Returns:

Optional containing the PagedFile mapped by this PageCache for given file, or an empty Optional if no mapping exist.

Throws:

IOException - if page cache has been closed or page eviction problems occur.

flushAndForce

void flushAndForce()
            throws IOException

Flush all dirty pages

Throws:

IOException

flushAndForce

void flushAndForce(IOLimiter limiter)
            throws IOException

Flush all dirty pages, but limit the rate of IO as advised by the given IOPSLimiter.

Parameters:

limiter - The IOLimiter that determines if pauses or sleeps should be injected into the flushing process to keep the IO rate down.

Throws:

IOException

close

void close()
    throws IllegalStateException

Close the page cache to prevent any future mapping of files. This also releases any internal resources, including the PageSwapperFactory through its close method.

Specified by:

close in interface AutoCloseable

Throws:

IllegalStateException - if not all files have been unmapped, with PagedFile.close(), prior to closing the page cache. In this case, the page cache WILL NOT be considered to be successfully closed.

RuntimeException - if the PageSwapperFactory.close() method throws. In this case the page cache WILL BE considered to have been closed successfully.

pageSize

int pageSize()

The size in bytes of the pages managed by this cache.

maxCachedPages

int maxCachedPages()

The max number of cached pages.

streamFilesRecursive

Stream<FileHandle> streamFilesRecursive(File directory)
                                 throws IOException

Return a stream of file handles for every file in the given directory, and its sub-directories.

Alternatively, if the File given as an argument refers to a file instead of a directory, then a stream will be returned with a file handle for just that file.

The stream is based on a snapshot of the file tree, so changes made to the tree using the returned file handles will not be reflected in the stream.

No directories will be returned. Only files. If a file handle ends up leaving a directory empty through a rename or a delete, then the empty directory will automatically be deleted as well. Likewise, if a file is moved to a path where not all of the directories in the path exists, then those missing directories will be created prior to the file rename.

Parameters:

directory - The base directory to start streaming files from, or the specific individual file to stream.

Returns:

A stream of all files in the tree.

Throws:

NoSuchFileException - If the given base directory or file does not exists.

IOException - If an I/O error occurs, possibly with the canonicalisation of the paths.