MappedMemorySegment (Java SE 15 & JDK 15)
Description: declaration: module: jdk.incubator.foreign, package: jdk.incubator.foreign, interface: MappedMemorySegment
Keywords: jdk.incubator.foreign.MappedMemorySegment interface

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.

- ## Field Summary

  ### Fields declared in interface jdk.incubator.foreign.MemorySegment

  `ACQUIRE, ALL_ACCESS, CLOSE, HANDOFF, READ, WRITE`

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `MappedMemorySegment` | `asSlice​(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.
  `void` | `force()` | Forces any changes made to this segment's content to be written to the storage device containing the mapped file.
  `boolean` | `isLoaded()` | Tells whether or not this segment's content is resident in physical memory.
  `void` | `load()` | Loads this segment's content into physical memory.
  `void` | `unload()` | Unloads this segment's content from physical memory.
  `MappedMemorySegment` | `withAccessModes​(int accessModes)` | Obtains a segment view with specific access modes.

  ### Methods declared in interface jdk.incubator.foreign.MemorySegment

  `accessModes, asByteBuffer, baseAddress, byteSize, close, copyFrom, fill, hasAccessModes, isAlive, mismatch, ownerThread, toByteArray, withOwnerThread`

- ## 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