org.neo4j.io.pagecache

Interface IOLimiter

public interface IOLimiter

IOLimiter instances can be passed to the PageCache.flushAndForce(IOLimiter) and PagedFile.flushAndForce(IOLimiter) methods, which will invoke the maybeLimitIO(long, int, Flushable) method on regular intervals.

This allows the limiter to measure the rate of IO, and inject sleeps, pauses or flushes into the process. The flushes are in this case referring to the underlying hardware.

Normally, flushing a channel will just copy the dirty buffers into the OS page cache, but flushing is in this case implying that the OS pages are cleared as well. In other words, the IOPSLimiter can make sure that the operating system does not pile up too much IO work in its page cache, by flushing those caches as well on regular intervals.

Field Summary

Fields

Modifier and Type	Field and Description
static long	INITIAL_STAMP The value of the initial stamp; that is, what should be passed as the previousStamp to maybeLimitIO(long, int, Flushable) on the first call in a flush.

Method Summary

Modifier and Type	Method and Description
default void	disableLimit() Temporarily disable the IOLimiter, to allow IO to proceed at full speed.
default void	enableLimit() Re-enable the IOLimiter, after having disabled it with disableLimit().
long	maybeLimitIO(long previousStamp, int recentlyCompletedIOs, Flushable flushable) Invoked at regular intervals during flushing of the PageCache or PagedFiles.
static IOLimiter	unlimited() An IOPSLimiter implementation that does not restrict the rate of IO.

Field Detail

INITIAL_STAMP

static final long INITIAL_STAMP

The value of the initial stamp; that is, what should be passed as the previousStamp to maybeLimitIO(long, int, Flushable) on the first call in a flush.

See Also:

Constant Field Values

Method Detail

maybeLimitIO

long maybeLimitIO(long previousStamp,
                  int recentlyCompletedIOs,
                  Flushable flushable)
           throws IOException

Invoked at regular intervals during flushing of the PageCache or PagedFiles.

For the first call in a flush, the previousStamp should have the INITIAL_STAMP value. The return value of this method should then be used as the stamp of the next call. This allows implementations to be stateless, yet still keep some context around about a given flush, provided they can encode it as a long.

The meaning of this long value is totally opaque to the caller, and can be anything the IOPSLimiter implementation desires.

The implementation is allowed to force changes to the storage device using the given Flushable, or to perform sleeps, as it desires. It is not allowed to throw InterruptedException, however. Those should be dealt with by catching them and re-interrupting the current thread, or by wrapping them in IOExceptions.

Parameters:

previousStamp - The stamp from the previous call to this method, or INITIAL_STAMP if this is the first call to this method for the given flush.

recentlyCompletedIOs - The number of IOs completed since the last call to this method.

flushable - A Flushable instance that can flush any relevant dirty system buffers, to help smooth out the IO load on the storage device.

Returns:

A new stamp to pass into the next call to this method.

Throws:

IOException

disableLimit

default void disableLimit()

Temporarily disable the IOLimiter, to allow IO to proceed at full speed. This call MUST be paired with a subsequent enableLimit() call. This method is thread-safe and reentrant. Multiple concurrent calls will "stack", and IO limitations will be enabled again once the last overlapping limit-disabling period ends with the "last" call to enableLimit(). This is conceptually similar to how a reentrant read-lock works. Thus, the typical usage pattern is with a try-finally clause, like this:

     limiter.disableLimit();
     try
     {
         // ... do work that needs maximum IO performance ...
     }
     finally
     {
         limiter.enableLimit();
     }
 

enableLimit

default void enableLimit()

Re-enable the IOLimiter, after having disabled it with disableLimit().

See Also:

for how to use this method.

unlimited

static IOLimiter unlimited()

An IOPSLimiter implementation that does not restrict the rate of IO. Use this implementation if you want the flush to go as fast as possible.