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_EXCLUSIVE_LOCK Pin the pages with an exclusive lock.
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_LOCK Pin the pages with a shared lock.
static int	PF_TRANSIENT Do not update page access statistics.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Release a handle to a paged file.
void	flushAndForce() Flush all dirty pages into the file channel, and force the file channel to disk.
void	force() Force all changes to this file handle down to disk.
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.
int	pageSize() Get the size of the file-pages, in bytes.

Field Detail

PF_SHARED_LOCK

static final int PF_SHARED_LOCK

Pin the pages with a shared lock. This implies PF_NO_GROW, since pages under shared 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_EXCLUSIVE_LOCK.

See Also:

Constant Field Values

PF_EXCLUSIVE_LOCK

static final int PF_EXCLUSIVE_LOCK

Pin the pages with an exclusive lock. This will mark the pages as dirty, and caused them to be flushed, if they are evicted. This cannot be combined with PF_SHARED_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_EXCLUSIVE_LOCK or PF_SHARED_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_EXCLUSIVE_LOCK | PF_NO_GROW – note how the flags are combined with a bitwise-OR operator.

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.

flushAndForce

void flushAndForce()
                   throws IOException

Flush all dirty pages into the file channel, and force the file channel to disk. Note: Flushing has to take locks on pages, so you cannot call flush while you have pages pinned.

Throws:

IOException

force

void force()
           throws IOException

Force all changes to this file handle down to disk. Does not flush dirty pages.

Throws:

IOException

getLastPageId

long getLastPageId()
                   throws IOException

Get the file-page-id of the last page in the file. This will return -1 if the file is completely empty.

Throws:

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.

Specified by:

close in interface AutoCloseable

Throws:

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

See Also:

AutoCloseable.close()