org.neo4j.io.pagecache

Interface PagedFile

All Superinterfaces:

AutoCloseable

public interface PagedFile
extends AutoCloseable

The representation of a file that has been mapped into the associated page cache.

Field Summary

Fields

Modifier and Type	Field and Description
static int	PF_NO_FAULT Do not load in the page if it is not loaded already.
static int	PF_NO_GROW Disallow pinning and navigating to pages outside the range of the underlying file.
static int	PF_READ_AHEAD Read-ahead hint for sequential forward scanning.
static int	PF_SHARED_READ_LOCK Pin the pages with a shared lock.
static int	PF_SHARED_WRITE_LOCK Pin the pages with a shared write lock.
static int	PF_TRANSIENT Do not update page access statistics.

Method Summary

Modifier and Type	Method and Description
void	close() Release a handle to a paged file.
long	fileSize() Size of file, in bytes.
void	flushAndForce() Flush all dirty pages into the file channel, and force the file channel to disk.
void	flushAndForce(IOLimiter limiter) Flush all dirty pages into the file channel, and force the file channel to disk, but limit the rate of IO as advised by the given IOPSLimiter.
long	getLastPageId() Get the file-page-id of the last page in the file.
PageCursor	io(long pageId, int pf_flags) Initiate an IO interaction with the contents of the paged file.
ReadableByteChannel	openReadableByteChannel() Open a ReadableByteChannel view of this PagedFile.
WritableByteChannel	openWritableByteChannel() Open a WritableByteChannel view of this PagedFile.
int	pageSize() Get the size of the file-pages, in bytes.

Field Detail

PF_SHARED_READ_LOCK

static final int PF_SHARED_READ_LOCK

Pin the pages with a shared lock.

This implies PF_NO_GROW, since pages under read locks cannot be safely written to anyway, so there's no point in trying to go beyond the end of the file.

This cannot be combined with PF_SHARED_WRITE_LOCK.

See Also:

Constant Field Values

PF_SHARED_WRITE_LOCK

static final int PF_SHARED_WRITE_LOCK

Pin the pages with a shared write lock.

This will mark the pages as dirty, and caused them to be flushed, if they are evicted.

Note that write locks are not exclusive. You must use other means to coordinate access to the data on the pages. The write lock only means that the page will not be concurrently evicted.

This cannot be combined with PF_SHARED_READ_LOCK.

See Also:

Constant Field Values

PF_NO_GROW

static final int PF_NO_GROW

Disallow pinning and navigating to pages outside the range of the underlying file.

See Also:

Constant Field Values

PF_READ_AHEAD

static final int PF_READ_AHEAD

Read-ahead hint for sequential forward scanning.

See Also:

Constant Field Values

PF_NO_FAULT

static final int PF_NO_FAULT

Do not load in the page if it is not loaded already. Only useful with exclusive locking when you want to overwrite the whole page anyway.

See Also:

Constant Field Values

PF_TRANSIENT

static final int PF_TRANSIENT

Do not update page access statistics.

See Also:

Constant Field Values

Method Detail

io

PageCursor io(long pageId,
              int pf_flags)
       throws IOException

Initiate an IO interaction with the contents of the paged file.

The basic structure of an interaction looks like this:

     try ( PageCursor cursor = pagedFile.io( startingPageId, intentFlags ) )
     {
         if ( cursor.next() )
         {
             do
             {
                 // perform read or write operations on the page
             }
             while ( cursor.shouldRetry() );
         }
     }
 

PageCursors are AutoCloseable, so interacting with them using try-with-resources is recommended.

The returned PageCursor is initially not bound, so next must be called on it before it can be used.

The first next call will advance the cursor to the initial page, as given by the pageId parameter. Until then, the cursor won't be bound to any page, the PageCursor.getCurrentPageId() method will return the PageCursor.UNBOUND_PAGE_ID constant, and attempts at reading from or writing to the cursor will throw a NullPointerException.

After the next call, if it returns true, the cursor will be bound to a page, and the get and put methods will access that page.

After a call to PageCursor.rewind(), the cursor will return to its initial state.

The pf_flags argument expresses the intent of the IO operation. It is a bitmap that combines various PF_* constants. You must always specify your desired locking behaviour, with either PF_SHARED_WRITE_LOCK or PF_SHARED_READ_LOCK.

The two locking modes cannot be combined, but other intents can be combined with them. For instance, if you want to write to a page, but also make sure that you don't write beyond the end of the file, then you can express your intent with PF_SHARED_WRITE_LOCK | PF_NO_GROW – note how the flags are combined with a bitwise-OR operator. Arithmetic addition can also be used, but might not make it as clear that we are dealing with a bit-set.

Parameters:

pageId - The initial file-page-id, that the cursor will be bound to after the first call to next.

pf_flags - A bitmap of PF_* constants composed with the bitwise-OR operator, that expresses the desired locking behaviour, and other hints.

Returns:

A PageCursor in its initial unbound state. Never null.

Throws:

IOException - if there was an error accessing the underlying file.

pageSize

int pageSize()

Get the size of the file-pages, in bytes.

fileSize

long fileSize()
       throws IOException

Size of file, in bytes.

Throws:

IOException

flushAndForce

void flushAndForce()
            throws IOException

Flush all dirty pages into the file channel, and force the file channel to disk.

Throws:

IOException

flushAndForce

void flushAndForce(IOLimiter limiter)
            throws IOException

Flush all dirty pages into the file channel, and force the file channel to disk, 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

getLastPageId

long getLastPageId()
            throws IOException

Get the file-page-id of the last page in the file.

This will return a negative number (not necessarily -1) if the file is completely empty.

Throws:

IllegalStateException - if this file has been unmapped

IOException

close

void close()
    throws IOException

Release a handle to a paged file.

If this is the last handle to the file, it will be flushed and closed.

Note that this operation assumes that there are no write page cursors open on the paged file. If there are, then their writes may be lost, as they might miss the last flush that can happen on their data.

Specified by:

close in interface AutoCloseable

Throws:

IOException - instead of the Exception superclass as defined in AutoCloseable, if .

See Also:

AutoCloseable.close()

openReadableByteChannel

ReadableByteChannel openReadableByteChannel()
                                     throws IOException

Open a ReadableByteChannel view of this PagedFile.

The channel will read the file sequentially from the beginning till the end. Seeking is not supported.

The channel is not thread-safe.

Returns:

A channel for reading the paged file.

Throws:

IOException

openWritableByteChannel

WritableByteChannel openWritableByteChannel()
                                     throws IOException

Open a WritableByteChannel view of this PagedFile.

The channel will write to the file sequentially from the beginning of the file, overwriting whatever is there already. If the amount of new data is less than the amount of existing data, then the old data will still be present at the far end of the file. Thus, this function works neither like opening a file for writing, nor like appending to a file.

If this is undesired, then the file can be mapped with StandardOpenOption.TRUNCATE_EXISTING to remove the existing data before writing to the file.

The channel is not thread-safe.

Returns:

A channel for writing to the paged file.

Throws:

IOException

See Also:

PageCache.map(File, int, OpenOption...)