net.openhft.chronicle.bytes

Class MappedFile

java.lang.Object

net.openhft.chronicle.core.io.AbstractReferenceCounted

net.openhft.chronicle.core.io.AbstractCloseableReferenceCounted

net.openhft.chronicle.bytes.MappedFile

All Implemented Interfaces:

Closeable, AutoCloseable, net.openhft.chronicle.core.io.ManagedCloseable, net.openhft.chronicle.core.io.QueryCloseable, net.openhft.chronicle.core.io.ReferenceCounted, net.openhft.chronicle.core.io.ReferenceCountedTracer, net.openhft.chronicle.core.io.ReferenceOwner, net.openhft.chronicle.core.io.SingleThreadedChecked

Direct Known Subclasses:

ChunkedMappedFile, SingleMappedFile

public abstract class MappedFile
extends net.openhft.chronicle.core.io.AbstractCloseableReferenceCounted

Represents a memory-mapped file that can be randomly accessed in chunks. The file is divided into chunks, and each chunk has an overlapping region with the next chunk to avoid wasting bytes at the end of each chunk. This class provides methods for locking regions of the file, acquiring bytes for read or write operations, and managing the reference counts of the underlying mapped byte stores.

The class is abstract, and specific implementations may differ in how they manage the chunks and underlying file storage.

Field Summary

Fields

Modifier and Type	Field and Description
static SyncMode	DEFAULT_SYNC_MODE The default disk synchronization mode for this mapped file.
protected NewChunkListener	newChunkListener Listener for the event when a new chunk is created.
protected static boolean	RETAIN Flag to indicate if the mapped file should be retained.

Fields inherited from class net.openhft.chronicle.core.io.AbstractReferenceCounted

referenceCounted, WARN_COUNT, WARN_NS

Fields inherited from interface net.openhft.chronicle.core.io.ReferenceOwner

INIT, TMP

Fields inherited from interface net.openhft.chronicle.core.io.SingleThreadedChecked

DISABLE_SINGLE_THREADED_CHECK

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MappedFile(@NotNull File file, boolean readOnly) Constructs a new MappedFile with the specified file and read-only flag.

Method Summary

Modifier and Type	Method and Description
@NotNull Bytes<?>	acquireBytesForRead(net.openhft.chronicle.core.io.ReferenceOwner owner, long position) Acquires bytes for read at the specified position, without the need to release the BytesStore.
void	acquireBytesForRead(net.openhft.chronicle.core.io.ReferenceOwner owner, long position, @NotNull VanillaBytes bytes) Acquires bytes for read at the specified position and stores them in the provided VanillaBytes object.
@NotNull Bytes<?>	acquireBytesForWrite(net.openhft.chronicle.core.io.ReferenceOwner owner, long position) Acquires bytes for write at the specified position.
void	acquireBytesForWrite(net.openhft.chronicle.core.io.ReferenceOwner owner, long position, @NotNull VanillaBytes bytes) Acquires bytes for write at the specified position and stores them in the provided VanillaBytes object.
@NotNull MappedBytesStore	acquireByteStore(net.openhft.chronicle.core.io.ReferenceOwner owner, long position) Acquires a byte store at the specified position.
@NotNull MappedBytesStore	acquireByteStore(net.openhft.chronicle.core.io.ReferenceOwner owner, long position, BytesStore oldByteStore) Acquires a byte store at the specified position with the ability to re-use an existing byte store.
abstract @NotNull MappedBytesStore	acquireByteStore(net.openhft.chronicle.core.io.ReferenceOwner owner, long position, BytesStore oldByteStore, @NotNull MappedBytesStoreFactory mappedBytesStoreFactory) Acquires a byte store at the specified position with the ability to re-use an existing byte store, and specify a custom byte store factory.
abstract long	actualSize() Returns the actual size of the mapped file in bytes, including any space reserved for metadata, headers, etc.
protected boolean	canReleaseInBackground() Indicates whether the release operation can be performed in the background.
abstract long	capacity() Returns the capacity of the mapped file in bytes.
abstract long	chunkCount() Returns the number of chunks in this mapped file.
abstract void	chunkCount(long[] chunkCount) Populates the provided array with detailed chunk count information.
abstract long	chunkSize() Returns the size of each chunk in the mapped file in bytes.
abstract MappedBytes	createBytesFor() Creates a MappedBytes object for this mapped file.
@NotNull File	file() Returns the File object associated with this MappedFile.
protected void	finalize() This finalize() is used to detect when a component is not released deterministically.
NewChunkListener	getNewChunkListener() Returns the listener that is notified when a new chunk is created.
protected String	internalizedToken() Returns an internalized String that represents a token based on the underlying file's canonical path and some other factors including a per JVM random string.
abstract FileLock	lock(long position, long size, boolean shared) Locks a specified region of this mapped file.
static @NotNull MappedFile	mappedFile(@NotNull File file, long chunkSize) Creates and returns a MappedFile instance for the specified file with the given chunk size.
static @NotNull MappedFile	mappedFile(@NotNull File file, long chunkSize, long overlapSize) Creates and returns a MappedFile instance for the specified file with the given chunk size and overlap size.
static @NotNull MappedFile	mappedFile(@NotNull File file, long chunkSize, long overlapSize, boolean readOnly) Creates and returns a MappedFile instance for the specified file with the given chunk size, overlap size, and read-only mode.
static @NotNull MappedFile	mappedFile(@NotNull File file, long capacity, long chunkSize, long overlapSize, boolean readOnly) Creates and returns a MappedFile instance with the specified file, capacity, chunk size, overlap size, and read-only mode.
static @NotNull MappedFile	mappedFile(@NotNull String filename, long chunkSize) Creates and returns a MappedFile instance for the specified file with the given chunk size.
static @NotNull MappedFile	mappedFile(@NotNull String filename, long chunkSize, long overlapSize) Creates and returns a MappedFile instance for the specified file with the given chunk size and overlap size.
static @NotNull MappedFile	of(@NotNull File file, long chunkSize, long overlapSize, boolean readOnly) Creates and returns a MappedFile instance with the specified file, chunk size, overlap size, and read-only mode.
static @NotNull MappedFile	ofSingle(@NotNull File file, long capacity, boolean readOnly) Creates and returns a MappedFile instance representing a single chunk of the specified file.
abstract long	overlapSize() Returns the size of the overlap between consecutive chunks in the mapped file in bytes.
abstract @NotNull RandomAccessFile	raf() Returns the RandomAccessFile associated with the mapped file.
boolean	readOnly() Checks if this MappedFile is read-only.
static @NotNull MappedFile	readOnly(@NotNull File file) Creates and returns a read-only MappedFile instance for the specified file.
abstract @NotNull String	referenceCounts() Returns a string representation of the reference counts for the underlying mapped byte stores.
void	setNewChunkListener(NewChunkListener listener) Sets the listener to be notified when a new chunk is created.
abstract void	syncMode(SyncMode syncMode) This mode determines whether an MS_ASYNC or MS_SYNC should be performed on a chunk release.
protected boolean	threadSafetyCheck(boolean isUsed) Performs a thread safety check on the component.
abstract FileLock	tryLock(long position, long size, boolean shared) Attempts to lock a specified region of this mapped file.
static void	warmup() Warms up the memory-mapped file by accessing its contents.

Methods inherited from class net.openhft.chronicle.core.io.AbstractCloseableReferenceCounted

backgroundPerformRelease, close, isClosed, release, releaseLast, reserve, reserveTransfer, setClosed, setClosing, throwExceptionIfClosed, throwExceptionIfClosedInSetter, tryReserve

Methods inherited from class net.openhft.chronicle.core.io.AbstractReferenceCounted

addReferenceChangeListener, assertReferencesReleased, clearUsedByThread, createdHere, disableReferenceTracing, enableReferenceTracing, performRelease, refCount, referenceCountedUnmonitored, referenceId, removeReferenceChangeListener, reservedBy, singleThreadedCheckDisabled, singleThreadedCheckReset, throwExceptionIfNotReleased, throwExceptionIfReleased, toString, unmonitor, warnAndReleaseIfNotReleased

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.openhft.chronicle.core.io.ManagedCloseable

createdHere, warnAndCloseIfNotClosed

Methods inherited from interface net.openhft.chronicle.core.io.Closeable

closeQuietly, closeQuietly

Methods inherited from interface net.openhft.chronicle.core.io.QueryCloseable

isClosing

Methods inherited from interface net.openhft.chronicle.core.io.ReferenceCountedTracer

onReleased

Methods inherited from interface net.openhft.chronicle.core.io.ReferenceCounted

releaseLast

Methods inherited from interface net.openhft.chronicle.core.io.ReferenceOwner

referenceName, temporary

Field Detail

DEFAULT_SYNC_MODE

public static final SyncMode DEFAULT_SYNC_MODE

The default disk synchronization mode for this mapped file.

RETAIN

protected static final boolean RETAIN

Flag to indicate if the mapped file should be retained.

newChunkListener

protected NewChunkListener newChunkListener

Listener for the event when a new chunk is created.

Constructor Detail

MappedFile

protected MappedFile(@NotNull
                     @NotNull File file,
                     boolean readOnly)
              throws net.openhft.chronicle.core.io.IORuntimeException

Constructs a new MappedFile with the specified file and read-only flag.

Parameters:

file - The file to be memory-mapped.

readOnly - True if the file should be read-only, false otherwise.

Throws:

net.openhft.chronicle.core.io.IORuntimeException - if an I/O error occurs.

Method Detail

of

@NotNull
public static @NotNull MappedFile of(@NotNull
                                              @NotNull File file,
                                              long chunkSize,
                                              long overlapSize,
                                              boolean readOnly)
                                       throws FileNotFoundException

Creates and returns a MappedFile instance with the specified file, chunk size, overlap size, and read-only mode.

Parameters:

file - The file to be memory-mapped.

chunkSize - The size of each chunk in bytes.

overlapSize - The size of the overlapping regions between chunks in bytes.

readOnly - If true, the file is opened in read-only mode; if false, it is opened for read-write.

Returns:

A new MappedFile instance.

Throws:

FileNotFoundException - If the specified file does not exist.

ofSingle

@NotNull
public static @NotNull MappedFile ofSingle(@NotNull
                                                    @NotNull File file,
                                                    long capacity,
                                                    boolean readOnly)
                                             throws FileNotFoundException

Creates and returns a MappedFile instance representing a single chunk of the specified file.

Parameters:

file - The file to be memory-mapped.

capacity - The capacity of the memory-mapped file in bytes.

readOnly - If true, the file is opened in read-only mode; if false, it is opened for read-write.

Returns:

A new MappedFile instance.

Throws:

FileNotFoundException - If the specified file does not exist.

mappedFile

@NotNull
public static @NotNull MappedFile mappedFile(@NotNull
                                                      @NotNull File file,
                                                      long chunkSize)
                                               throws FileNotFoundException

Creates and returns a MappedFile instance for the specified file with the given chunk size. The overlap size is set to the default page size of the operating system.

Parameters:

file - The file to be memory-mapped.

chunkSize - The size of each chunk in bytes.

Returns:

A new MappedFile instance.

Throws:

FileNotFoundException - If the specified file does not exist.

mappedFile

@NotNull
public static @NotNull MappedFile mappedFile(@NotNull
                                                      @NotNull String filename,
                                                      long chunkSize)
                                               throws FileNotFoundException

Creates and returns a MappedFile instance for the specified file with the given chunk size. The overlap size is set to the default page size of the operating system.

Parameters:

filename - The name of the file to be memory-mapped.

chunkSize - The size of each chunk in bytes.

Returns:

A new MappedFile instance.

Throws:

FileNotFoundException - If the specified file does not exist.

mappedFile

@NotNull
public static @NotNull MappedFile mappedFile(@NotNull
                                                      @NotNull String filename,
                                                      long chunkSize,
                                                      long overlapSize)
                                               throws FileNotFoundException

Creates and returns a MappedFile instance for the specified file with the given chunk size and overlap size.

Parameters:

filename - The name of the file to be memory-mapped.

chunkSize - The size of each chunk in bytes.

overlapSize - The size of the overlapping regions between chunks in bytes.

Returns:

A new MappedFile instance.

Throws:

FileNotFoundException - If the specified file does not exist.

mappedFile

@NotNull
public static @NotNull MappedFile mappedFile(@NotNull
                                                      @NotNull File file,
                                                      long chunkSize,
                                                      long overlapSize)
                                               throws FileNotFoundException

Creates and returns a MappedFile instance for the specified file with the given chunk size and overlap size.

Parameters:

file - The file to be memory-mapped.

chunkSize - The size of each chunk in bytes.

overlapSize - The size of the overlapping regions between chunks in bytes.

Returns:

A new MappedFile instance.

Throws:

FileNotFoundException - If the specified file does not exist.

mappedFile

@NotNull
public static @NotNull MappedFile mappedFile(@NotNull
                                                      @NotNull File file,
                                                      long chunkSize,
                                                      long overlapSize,
                                                      boolean readOnly)
                                               throws FileNotFoundException

Creates and returns a MappedFile instance for the specified file with the given chunk size, overlap size, and read-only mode.

Parameters:

file - The file to be memory-mapped.

chunkSize - The size of each chunk in bytes.

overlapSize - The size of the overlapping regions between chunks in bytes.

readOnly - If true, the file is opened in read-only mode; if false, it is opened for read-write.

Returns:

A new MappedFile instance.

Throws:

FileNotFoundException - If the specified file does not exist.

readOnly

@NotNull
public static @NotNull MappedFile readOnly(@NotNull
                                                    @NotNull File file)
                                             throws FileNotFoundException

Creates and returns a read-only MappedFile instance for the specified file. The chunk size is set to the length of the file and overlap size is set to 0. On Windows, chunks of 4 GB or larger are not supported, so the chunk size is capped at 2^31 bytes and the overlap size is set to the default page size of the operating system.

Parameters:

file - The file to be memory-mapped.

Returns:

A new read-only MappedFile instance.

Throws:

FileNotFoundException - If the specified file does not exist.

mappedFile

@NotNull
public static @NotNull MappedFile mappedFile(@NotNull
                                                      @NotNull File file,
                                                      long capacity,
                                                      long chunkSize,
                                                      long overlapSize,
                                                      boolean readOnly)
                                               throws IOException

Creates and returns a MappedFile instance with the specified file, capacity, chunk size, overlap size, and read-only mode.

Parameters:

file - The file to be memory-mapped.

capacity - The total size that the file should take up, in bytes.

chunkSize - The size of each chunk in bytes.

overlapSize - The size of the overlapping regions between chunks in bytes.

readOnly - If true, the file is opened in read-only mode; if false, it is opened for read-write.

Returns:

A new MappedFile instance.

Throws:

IOException - If an I/O error occurs.

warmup

public static void warmup()

Warms up the memory-mapped file by accessing its contents.

file

@NotNull
public @NotNull File file()

Returns the File object associated with this MappedFile.

Returns:

The File object.

readOnly

public boolean readOnly()

Checks if this MappedFile is read-only.

Returns:

True if this MappedFile is read-only, false otherwise.

acquireByteStore

@NotNull
public @NotNull MappedBytesStore acquireByteStore(net.openhft.chronicle.core.io.ReferenceOwner owner,
                                                           long position)
                                                    throws IOException,
                                                           IllegalArgumentException,
                                                           IllegalStateException

Acquires a byte store at the specified position.

Parameters:

owner - The owner of the byte store.

position - The position at which the byte store should be acquired.

Returns:

A MappedBytesStore object.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If the position is negative.

IllegalStateException - If the MappedFile is closed.

acquireByteStore

@NotNull
public @NotNull MappedBytesStore acquireByteStore(net.openhft.chronicle.core.io.ReferenceOwner owner,
                                                           long position,
                                                           BytesStore oldByteStore)
                                                    throws IOException,
                                                           IllegalStateException

Acquires a byte store at the specified position with the ability to re-use an existing byte store.

Parameters:

owner - The owner of the byte store.

position - The position at which the byte store should be acquired.

oldByteStore - The old byte store that can be re-used, or null if not available.

Returns:

A MappedBytesStore object.

Throws:

IOException - If an I/O error occurs.

IllegalStateException - If the MappedFile is closed.

acquireByteStore

@NotNull
public abstract @NotNull MappedBytesStore acquireByteStore(net.openhft.chronicle.core.io.ReferenceOwner owner,
                                                                    long position,
                                                                    BytesStore oldByteStore,
                                                                    @NotNull
                                                                    @NotNull MappedBytesStoreFactory mappedBytesStoreFactory)
                                                             throws IOException,
                                                                    IllegalArgumentException,
                                                                    IllegalStateException

Acquires a byte store at the specified position with the ability to re-use an existing byte store, and specify a custom byte store factory.

Parameters:

owner - The owner of the byte store.

position - The position at which the byte store should be acquired.

oldByteStore - The old byte store that can be re-used, or null if not available.

mappedBytesStoreFactory - The factory to use for creating the MappedBytesStore.

Returns:

A MappedBytesStore object.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If an illegal argument is provided.

IllegalStateException - If the MappedFile is closed.

acquireBytesForRead

@NotNull
public @NotNull Bytes<?> acquireBytesForRead(net.openhft.chronicle.core.io.ReferenceOwner owner,
                                                      long position)
                                               throws IOException,
                                                      IllegalStateException,
                                                      BufferUnderflowException

Acquires bytes for read at the specified position, without the need to release the BytesStore.

Parameters:

owner - The owner of the bytes.

position - The position at which the bytes should be acquired.

Returns:

A Bytes object ready for read.

Throws:

IOException - If an I/O error occurs.

IllegalStateException - If the MappedFile is closed.

BufferUnderflowException - If the position is beyond the limit.

acquireBytesForRead

public void acquireBytesForRead(net.openhft.chronicle.core.io.ReferenceOwner owner,
                                long position,
                                @NotNull
                                @NotNull VanillaBytes bytes)
                         throws IOException,
                                IllegalStateException,
                                IllegalArgumentException,
                                BufferUnderflowException,
                                BufferOverflowException

Acquires bytes for read at the specified position and stores them in the provided VanillaBytes object.

Parameters:

owner - The owner of the bytes.

position - The position at which the bytes should be acquired.

bytes - The VanillaBytes object to store the acquired bytes.

Throws:

IOException - If an I/O error occurs.

IllegalStateException - If the MappedFile is closed.

IllegalArgumentException - If an illegal argument is provided.

BufferUnderflowException - If there is not enough data available.

BufferOverflowException - If there is too much data.

acquireBytesForWrite

@NotNull
public @NotNull Bytes<?> acquireBytesForWrite(net.openhft.chronicle.core.io.ReferenceOwner owner,
                                                       long position)
                                                throws IOException,
                                                       IllegalStateException,
                                                       IllegalArgumentException,
                                                       BufferOverflowException

Acquires bytes for write at the specified position.

Parameters:

owner - The owner of the bytes.

position - The position at which the bytes should be acquired for write.

Returns:

A Bytes object ready for write.

Throws:

IOException - If an I/O error occurs.

IllegalStateException - If the MappedFile is closed.

IllegalArgumentException - If an illegal argument is provided.

BufferOverflowException - If there is too much data.

acquireBytesForWrite

public void acquireBytesForWrite(net.openhft.chronicle.core.io.ReferenceOwner owner,
                                 long position,
                                 @NotNull
                                 @NotNull VanillaBytes bytes)
                          throws IOException,
                                 IllegalStateException,
                                 IllegalArgumentException,
                                 BufferUnderflowException,
                                 BufferOverflowException

Acquires bytes for write at the specified position and stores them in the provided VanillaBytes object.

Parameters:

owner - The owner of the bytes.

position - The position at which the bytes should be acquired for write.

bytes - The VanillaBytes object to store the acquired bytes.

Throws:

IOException - If an I/O error occurs.

IllegalStateException - If the MappedFile is closed.

IllegalArgumentException - If an illegal argument is provided.

BufferUnderflowException - If there is not enough data available.

BufferOverflowException - If there is too much data.

canReleaseInBackground

protected boolean canReleaseInBackground()

Indicates whether the release operation can be performed in the background.

Overrides:

canReleaseInBackground in class net.openhft.chronicle.core.io.AbstractReferenceCounted

Returns:

True if release operation can be performed in the background; otherwise False.

referenceCounts

@NotNull
public abstract @NotNull String referenceCounts()

Returns a string representation of the reference counts for the underlying mapped byte stores.

Returns:

A string representing the reference counts.

capacity

public abstract long capacity()

Returns the capacity of the mapped file in bytes.

Returns:

The capacity in bytes.

chunkSize

public abstract long chunkSize()

Returns the size of each chunk in the mapped file in bytes.

Returns:

The chunk size in bytes.

overlapSize

public abstract long overlapSize()

Returns the size of the overlap between consecutive chunks in the mapped file in bytes.

Returns:

The overlap size in bytes.

getNewChunkListener

public NewChunkListener getNewChunkListener()

Returns the listener that is notified when a new chunk is created.

Returns:

The listener for new chunks.

setNewChunkListener

public void setNewChunkListener(NewChunkListener listener)

Sets the listener to be notified when a new chunk is created.

Parameters:

listener - The listener to be set.

actualSize

public abstract long actualSize()

Returns the actual size of the mapped file in bytes, including any space reserved for metadata, headers, etc.

Returns:

The actual size in bytes.

raf

@NotNull
public abstract @NotNull RandomAccessFile raf()

Returns the RandomAccessFile associated with the mapped file. This can be used for lower-level operations that are not directly supported by the MappedFile API.

Returns:

The RandomAccessFile associated with the mapped file.

finalize

protected void finalize()
                 throws Throwable

This finalize() is used to detect when a component is not released deterministically. It is not required to be run, but provides a warning

Overrides:

finalize in class Object

Throws:

Throwable

threadSafetyCheck

protected boolean threadSafetyCheck(boolean isUsed)

Performs a thread safety check on the component.

Overrides:

threadSafetyCheck in class net.openhft.chronicle.core.io.AbstractReferenceCounted

Parameters:

isUsed - Flag to indicate whether the component is used.

Returns:

Always returns true as the component is thread-safe.

internalizedToken

protected String internalizedToken()

Returns an internalized String that represents a token based on the underlying file's canonical path and some other factors including a per JVM random string.

The canonical path is pre-pended with static and random data to reduce the probability of unrelated synchronization on internalized Strings.

Returns:

internalized token.

lock

public abstract FileLock lock(long position,
                              long size,
                              boolean shared)
                       throws IOException

Locks a specified region of this mapped file.

Parameters:

position - The byte position at which the locked region begins.

size - The size of the region to lock, in bytes.

shared - If true, the lock will be shared. Otherwise, it will be exclusive.

Returns:

A FileLock object representing the lock on the specified region.

Throws:

IOException - If an I/O error occurs.

tryLock

public abstract FileLock tryLock(long position,
                                 long size,
                                 boolean shared)
                          throws IOException

Attempts to lock a specified region of this mapped file.

Parameters:

position - The byte position at which the locked region begins.

size - The size of the region to lock, in bytes.

shared - If true, the lock will be shared. Otherwise, it will be exclusive.

Returns:

A FileLock object representing the lock on the specified region, or null if the lock could not be acquired.

Throws:

IOException - If an I/O error occurs.

chunkCount

public abstract long chunkCount()

Returns the number of chunks in this mapped file.

Returns:

The number of chunks.

chunkCount

public abstract void chunkCount(long[] chunkCount)

Populates the provided array with detailed chunk count information. This may include, for example, counts of specific types of chunks.

Parameters:

chunkCount - The array to be populated with detailed chunk count information.

createBytesFor

public abstract MappedBytes createBytesFor()

Creates a MappedBytes object for this mapped file. The MappedBytes object can be used for reading from and writing to the mapped file.

Returns:

A new MappedBytes object associated with this mapped file.

syncMode

public abstract void syncMode(SyncMode syncMode)

This mode determines whether an MS_ASYNC or MS_SYNC should be performed on a chunk release.

Performs this sync on any open store as well

Parameters:

syncMode - of sync to perform.