public interface MappedMemorySegment extends MemorySegment
Mapped memory segments are created via the
MemorySegment.mapFromPath(Path, long, long, FileChannel.MapMode).
Mapped memory segments behave like ordinary segments, but provide additional capabilities to manipulate memory-mapped
memory regions, such as
All implementations of this interface must be value-based;
use of identity-sensitive operations (including reference equality (
==), identity hash code, or synchronization) on
MemoryLayout may have unpredictable results and should be avoided. The
equals method should
be used for comparisons.
Non-platform classes should not implement MappedMemorySegment directly.
The content of a mapped memory segment can change at any time, for example if the content of the corresponding region of the mapped file is changed by this (or another) program. Whether or not such changes occur, and when they occur, is operating-system dependent and therefore unspecified. All or part of a mapped memory segment may become inaccessible at any time, for example if the backing mapped file is truncated. An attempt to access an inaccessible region of a mapped memory segment will not change the segment's content and will cause an unspecified exception to be thrown either at the time of the access or at some later time. It is therefore strongly recommended that appropriate precautions be taken to avoid the manipulation of a mapped file by this (or another) program, except to read or write the file's content.
- API Note:
- In the future, if the Java language permits,
MemorySegmentmay become a
sealedinterface, which would prohibit subclassing except by explicitly permitted subtypes.
Modifier and Type Method Description
(long offset, long newSize)Obtains a new memory segment view whose base address is the same as the base address of this segment plus a given offset, and whose new size is specified by the given argument.
()Forces any changes made to this segment's content to be written to the storage device containing the mapped file.
()Tells whether or not this segment's content is resident in physical memory.
()Loads this segment's content into physical memory.
()Unloads this segment's content from physical memory.
(int accessModes)Obtains a segment view with specific access modes.
withAccessModesMappedMemorySegment withAccessModes(int accessModes)Description copied from interface:
MemorySegmentObtains a segment view with specific access modes. Supported access modes are
MemorySegment.HANDOFF. It is generally not possible to go from a segment with stricter access modes to one with less strict access modes. For instance, attempting to add
MemorySegment.WRITEaccess mode to a read-only segment will be met with an exception.
asSliceMappedMemorySegment asSlice(long offset, long newSize)Description copied from interface:
MemorySegmentObtains a new memory segment view whose base address is the same as the base address of this segment plus a given offset, and whose new size is specified by the given argument.
forcevoid force()Forces any changes made to this segment's content to be written to the storage device containing the mapped file.
If the file mapped into this segment resides on a local storage device then when this method returns it is guaranteed that all changes made to the segment since it was created, or since this method was last invoked, will have been written to that device.
If the file does not reside on a local device then no such guarantee is made.
If this segment was not mapped in read/write mode (
FileChannel.MapMode.READ_WRITE) then invoking this method may have no effect. In particular, the method has no effect for segments mapped in read-only or private mapping modes. This method may or may not have an effect for implementation-specific mapping modes.
loadvoid load()Loads this segment's content into physical memory.
This method makes a best effort to ensure that, when it returns, this segment's contents is resident in physical memory. Invoking this method may cause some number of page faults and I/O operations to occur.
unloadvoid unload()Unloads this segment's content from physical memory.
This method makes a best effort to ensure that this segment's contents are are no longer resident in physical memory. Accessing this segment's contents after invoking this method may cause some number of page faults and I/O operations to occur (as this segment's contents might need to be paged back in).
isLoadedboolean isLoaded()Tells whether or not this segment's content is resident in physical memory.
A return value of
trueimplies that it is highly likely that all of the data in this segment is resident in physical memory and may therefore be accessed without incurring any virtual-memory page faults or I/O operations. A return value of
falsedoes not necessarily imply that the segment's content is not resident in physical memory.
The returned value is a hint, rather than a guarantee, because the underlying operating system may have paged out some of the segment's data by the time that an invocation of this method returns.
trueif it is likely that this segment's content is resident in physical memory