org.neo4j.io.pagecache

Interface PageSwapperFactory

public interface PageSwapperFactory

Creates PageSwappers for the given files.

A PageSwapper is responsible for swapping file pages in and out of memory.

The PageSwapperFactory presumably knows about what file system to use.

Note that this API is only intended to be used by a PageCache implementation. It should never be used directly by user code.

Method Summary

Modifier and Type	Method and Description
void	close() Close and release any resources associated with this PageSwapperFactory, that it may have opened or acquired during its construction or use.
PageSwapper	createPageSwapper(File file, int filePageSize, PageEvictionCallback onEviction, boolean createIfNotExist) Create a PageSwapper for the given file.
int	getCachePageSizeHint() Get the most optimal cache page size (in bytes) for these PageSwapper implementations.
long	getRequiredBufferAlignment() Get the unit of alignment that the swappers require of the memory buffers.
String	implementationName() Get the name of this PageSwapperFactory implementation, for configuration purpose.
boolean	isCachePageSizeHintStrict() Gives true if the getCachePageSizeHint() is the only cache page size that is supported for these PageSwapper implementations, otherwise false.
void	setFileSystemAbstraction(FileSystemAbstraction fs) Configure the FileSystemAbstraction to use.
Stream<FileHandle>	streamFilesRecursive(File directory) Return a stream of file handles for every file in the given directory, and its sub-directories.
void	syncDevice() Forces all prior writes made through all non-closed PageSwappers that this factory has created, to all the relevant devices, such that the writes are durable when this call returns.

Method Detail

setFileSystemAbstraction

void setFileSystemAbstraction(FileSystemAbstraction fs)

Configure the FileSystemAbstraction to use.

This must be called before the first PageSwapper is created.

implementationName

String implementationName()

Get the name of this PageSwapperFactory implementation, for configuration purpose.

getCachePageSizeHint

int getCachePageSizeHint()

Get the most optimal cache page size (in bytes) for these PageSwapper implementations.

isCachePageSizeHintStrict

boolean isCachePageSizeHintStrict()

Gives true if the getCachePageSizeHint() is the only cache page size that is supported for these PageSwapper implementations, otherwise false.

getRequiredBufferAlignment

long getRequiredBufferAlignment()

Get the unit of alignment that the swappers require of the memory buffers. For instance, if page alignment is required for doing direct IO, then UnsafeUtil.pageSize() can be returned.

Returns:

The required buffer alignment byte multiple.

createPageSwapper

PageSwapper createPageSwapper(File file,
                              int filePageSize,
                              PageEvictionCallback onEviction,
                              boolean createIfNotExist)
                       throws IOException

Create a PageSwapper for the given file.

Parameters:

file - The file that the PageSwapper will move file pages in and out of.

filePageSize - The size of the pages in the file. Presumably a multiple of some record size.

onEviction - The PageSwapper will be told about evictions, and has the responsibility of informing the PagedFile via this callback.

createIfNotExist - When true, creates the given file if it does not exist, instead of throwing an exception.

Returns:

A working PageSwapper instance for the given file.

Throws:

IOException - If the PageSwapper could not be created, for instance if the underlying file could not be opened, or the given file does not exist and createIfNotExist is false.

syncDevice

void syncDevice()
         throws IOException

Forces all prior writes made through all non-closed PageSwappers that this factory has created, to all the relevant devices, such that the writes are durable when this call returns.

This method has no effect if the PageSwapper.force() method forces the writes for the individual file. The PageCache.flushAndForce() method will first call force on the PageSwappers for all mapped files, then call syncDevice on the PageSwapperFactory. This way, the writes are always made durable regardless of which method that does the forcing.

Throws:

IOException

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.

This method form the basis of the implementation of the PageCache.streamFilesRecursive(File) method. The key difference is that the stream and file handles are oblivious about which files are mapped or not. Thus, the returned file handles will never throw any FileIsMappedExceptions.

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.

close

void close()

Close and release any resources associated with this PageSwapperFactory, that it may have opened or acquired during its construction or use.

This method cannot be called before all of the opened PageSwappers have been closed, and it is guaranteed that no new page swappers will be created after this method has been called.