Module jdk.incubator.foreign
Package jdk.incubator.foreign

Interface MappedMemorySegment

All Superinterfaces:
AutoCloseable, MemorySegment
public interface MappedMemorySegment
extends MemorySegment
A mapped memory segment, that is, a memory segment backed by memory-mapped file.

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 force() and load().

All implementations of this interface must be value-based; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of 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, MemorySegment may become a sealed interface, which would prohibit subclassing except by explicitly permitted subtypes.

  • Method Details

    • withAccessModes

      MappedMemorySegment withAccessModes​(int accessModes)
      Description copied from interface: MemorySegment
      Obtains a segment view with specific access modes. Supported access modes are MemorySegment.READ, MemorySegment.WRITE, MemorySegment.CLOSE, MemorySegment.ACQUIRE and 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.WRITE access mode to a read-only segment will be met with an exception.
      Specified by:
      withAccessModes in interface MemorySegment
      Parameters:
      accessModes - an ORed mask of zero or more access modes.
      Returns:
      a segment view with specific access modes.

    • asSlice

      MappedMemorySegment asSlice​(long offset, long newSize)
      Description copied from interface: MemorySegment
      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.
      Specified by:
      asSlice in interface MemorySegment
      Parameters:
      offset - The new segment base offset (relative to the current segment base address), specified in bytes.
      newSize - The new segment size, specified in bytes.
      Returns:
      a new memory segment view with updated base/limit addresses.

    • force

      void 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.

    • load

      void 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.

    • unload

      void 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).

    • isLoaded

      boolean isLoaded()
      Tells whether or not this segment's content is resident in physical memory.

      A return value of true implies 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 false does 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.

      Returns:
      true if it is likely that this segment's content is resident in physical memory