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.
boolean	fileSystemSupportsFileOperations() Check if the backing file system supports regular file operations or not.
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.
FileSystemAbstraction	getCachedFileSystem() Get the FileSystemAbstraction that represents the filesystem where the paged files reside.
Optional<PagedFile>	getExistingMapping(File file) Ask for an already mapped paged file, backed by this page cache.
List<PagedFile>	listExistingMappings() List a snapshot of the current file mappings.
PagedFile	map(File file, int pageSize, OpenOption... openOptions) Ask for a handle to a paged file, backed by this page cache.
long	maxCachedPages() The max number of cached pages.
int	pageSize() The size in bytes of the pages managed by this cache.

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: The calling code is responsible for closing the returned paged file, if any.

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.

listExistingMappings

List<PagedFile> listExistingMappings()
                              throws IOException

List a snapshot of the current file mappings.

The mappings can change as soon as this method returns. However, the returned PagedFiles will remain valid even if they are closed elsewhere.

NOTE: The calling code is responsible for closing all the returned paged files.

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

long maxCachedPages()

The max number of cached pages.

getCachedFileSystem

FileSystemAbstraction getCachedFileSystem()

Get the FileSystemAbstraction that represents the filesystem where the paged files reside.

Returns:

the filesystem that the page cache is using.

fileSystemSupportsFileOperations

boolean fileSystemSupportsFileOperations()

Check if the backing file system supports regular file operations or not.

E.g. the file system for block device will not work with generic open and read/write calls and all operations needs to be done through the page cache.

Returns:

true if the backing file system supports regular file operations.