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

Class MappedMemorySegments

java.lang.Object
jdk.incubator.foreign.MappedMemorySegments
public final class MappedMemorySegments extends Object
This class provides capabilities to manipulate mapped memory segments, such as force(MemorySegment), and load(MemorySegment). The methods in these class are suitable replacements for some of the functionality in the MappedByteBuffer class. Note that, while it is possible to map a segment into a byte buffer (see MemorySegment.asByteBuffer()), and call e.g. MappedByteBuffer.force() that way, this can only be done when the source segment is small enough, due to the size limitation inherent to the ByteBuffer API.

Clients requiring sophisticated, low-level control over mapped memory segments, should consider writing custom mapped memory segment factories; using JNI, e.g. on Linux, it is possible to call mmap with the desired parameters; the returned address can be easily wrapped into a memory segment, using MemoryAddress.ofLong(long) and MemoryAddress.asSegmentRestricted(long, Runnable, Object).

Unless otherwise specified, passing a null argument, or an array argument containing one or more null elements to a method in this class causes a NullPointerException to be thrown.

Implementation Note:
The behavior of some the methods in this class (see load(MemorySegment), unload(MemorySegment) and isLoaded(MemorySegment)) is highly platform-dependent; as a result, calling these methods might be a no-op on certain platforms.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    force​(MemorySegment segment)
    Forces any changes made to the contents of the given segment to be written to the storage device described by the mapped segment's file descriptor.
    static boolean
    isLoaded​(MemorySegment segment)
    Tells whether or not the contents of the given segment is resident in physical memory.
    static void
    load​(MemorySegment segment)
    Loads the contents of the given segment into physical memory.
    static void
    unload​(MemorySegment segment)
    Unloads the contents of the given segment from physical memory.

    Methods declared in class java.lang.Object

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

  • Method Details

    • isLoaded

      public static boolean isLoaded​(MemorySegment segment)
      Tells whether or not the contents of the given segment is resident in physical memory.

      A return value of true implies that it is highly likely that all of the data in the given 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.

      Parameters:
      segment - the segment whose contents are to be tested.
      Returns:
      true if it is likely that the contents of the given segment is resident in physical memory
      Throws:
      IllegalStateException - if the given segment is not alive, or if the given segment is confined and this method is called from a thread other than the segment's owner thread.
      UnsupportedOperationException - if the given segment is not a mapped memory segment, e.g. if segment.isMapped() == false.

    • load

      public static void load​(MemorySegment segment)
      Loads the contents of the given segment into physical memory.

      This method makes a best effort to ensure that, when it returns, this contents of the given segment is resident in physical memory. Invoking this method may cause some number of page faults and I/O operations to occur.

      Parameters:
      segment - the segment whose contents are to be loaded.
      Throws:
      IllegalStateException - if the given segment is not alive, or if the given segment is confined and this method is called from a thread other than the segment's owner thread.
      UnsupportedOperationException - if the given segment is not a mapped memory segment, e.g. if segment.isMapped() == false.

    • unload

      public static void unload​(MemorySegment segment)
      Unloads the contents of the given segment from physical memory.

      This method makes a best effort to ensure that the contents of the given segment 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).

      Parameters:
      segment - the segment whose contents are to be unloaded.
      Throws:
      IllegalStateException - if the given segment is not alive, or if the given segment is confined and this method is called from a thread other than the segment's owner thread.
      UnsupportedOperationException - if the given segment is not a mapped memory segment, e.g. if segment.isMapped() == false.

    • force

      public static void force​(MemorySegment segment)
      Forces any changes made to the contents of the given segment to be written to the storage device described by the mapped segment's file descriptor.

      If this mapping's file descriptor 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 this mapping's file descriptor does not reside on a local device then no such guarantee is made.

      If the given 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.

      Parameters:
      segment - the segment whose contents are to be written to the storage device described by the segment's file descriptor.
      Throws:
      IllegalStateException - if the given segment is not alive, or if the given segment is confined and this method is called from a thread other than the segment's owner thread.
      UnsupportedOperationException - if the given segment is not a mapped memory segment, e.g. if segment.isMapped() == false.