public sealed Interface MemorySegment

There are two kinds of memory segments:

• A heap segment is backed by, and provides access to, a region of memory inside the Java heap (an "on-heap" region).
• A native segment is backed by, and provides access to, a region of memory outside the Java heap (an "off-heap" region).

Native segments can be obtained by calling one of the Arena#allocate(long, long) factory methods, which return a memory segment backed by a newly allocated off-heap region with the given size and aligned to the given alignment constraint. Alternatively, native segments can be obtained by mapping a file into a new off-heap region (in some systems, this operation is sometimes referred to as mmap). Segments obtained in this way are called mapped segments, and their contents can be persisted and loaded to and from the underlying memory-mapped file.

Both kinds of segments are read and written using the same methods, known as access operations. An access operation on a memory segment always and only provides access to the region for which the segment was obtained.

Characteristics of memory segments

• The address of a heap segment is not a physical address, but rather an offset within the region of memory which backs the segment. The region is inside the Java heap, so garbage collection might cause the region to be relocated in physical memory over time, but this is not exposed to clients of the MemorySegment API who see a stable virtualized address for a heap segment backed by the region. A heap segment obtained from one of the ofArray(int[]) factory methods has an address of zero.
• The address of a native segment (including mapped segments) denotes the physical address of the region of memory which backs the segment.

Every memory segment has a maximum byte alignment, expressed as a long value. The maximum alignment is always a power of two, derived from the segment address, and the segment type, as explained in more detail below.

Every memory segment has a size. The size of a heap segment is derived from the Java array from which it is obtained. This size is predictable across Java runtimes. The size of a native segment is either passed explicitly (as in Arena#allocate(long, long)) or derived from a MemoryLayout (as in Arena#allocate(MemoryLayout)). The size of a memory segment is typically a positive number but may be zero, but never negative.

The address and size of a memory segment jointly ensure that access operations on the segment cannot fall outside the boundaries of the region of memory that backs the segment. That is, a memory segment has spatial bounds.

Every memory segment is associated with a scope. This ensures that access operations on a memory segment cannot occur when the region of memory that backs the memory segment is no longer available (e.g., after the scope associated with the accessed memory segment is no longer alive). That is, a memory segment has temporal bounds.

Finally, access operations on a memory segment can be subject to additional thread-confinement checks. Heap segments can be accessed from any thread. Conversely, native segments can only be accessed compatibly with the confinement characteristics of the arena used to obtain them.

Accessing memory segments

MemorySegment segment = ...
int value = segment.get(ValueLayout.JAVA_INT, 0);

int value = segment.get(ValueLayout.JAVA_INT.withOrder(BIG_ENDIAN), 0);

VarHandle intAtOffsetHandle = ValueLayout.JAVA_INT.varHandle(); // (MemorySegment, long)
int value = (int) intAtOffsetHandle.get(segment, 10L);          // segment.get(ValueLayout.JAVA_INT, 10L)

VarHandle intAtOffsetAndIndexHandle =
        ValueLayout.JAVA_INT.arrayElementVarHandle();             // (MemorySegment, long, long)
int value = (int) intAtOffsetAndIndexHandle.get(segment, 2L, 3L); // segment.get(ValueLayout.JAVA_INT, 2L + (3L * 4L))

Clients can also drop the base offset parameter, in order to make the access expression simpler. This can be used to implement access operations such as getAtIndex(OfInt, long):

VarHandle intAtIndexHandle =
        MethodHandles.insertCoordinates(intAtOffsetAndIndexHandle, 1, 0L); // (MemorySegment, long)
int value = (int) intAtIndexHandle.get(segment, 3L);                       // segment.getAtIndex(ValueLayout.JAVA_INT, 3L);

Slicing memory segments

Arena arena = ...
MemorySegment segment = arena.allocate(100);
MemorySegment slice = segment.asSlice(50, 10);
slice.get(ValueLayout.JAVA_INT, 20); // Out of bounds!
arena.close();
slice.get(ValueLayout.JAVA_INT, 0); // Already closed!

A client might obtain a Stream from a segment, which can then be used to slice the segment (according to a given element layout) and even allow multiple threads to work in parallel on disjoint segment slices (to do this, the segment has to be accessible from multiple threads). The following code can be used to sum all int values in a memory segment in parallel:

try (Arena arena = Arena.ofShared()) {
    SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.sequenceLayout(1024, ValueLayout.JAVA_INT);
    MemorySegment segment = arena.allocate(SEQUENCE_LAYOUT);
    int sum = segment.elements(ValueLayout.JAVA_INT).parallel()
                     .mapToInt(s -> s.get(ValueLayout.JAVA_INT, 0))
                     .sum();
}

Alignment

If the segment being accessed is a native segment, then its address in physical memory can be combined with the offset to obtain the target address in physical memory. The pseudo-function below demonstrates this:

boolean isAligned(MemorySegment segment, long offset, MemoryLayout layout) {
  return ((segment.address() + offset) % layout.byteAlignment()) == 0;
}

• A native segment with address 1000 can be accessed at offsets 0, 8, 16, 24, etc under an 8-byte alignment constraint, because the target addresses (1000, 1008, 1016, 1024) are 8-byte aligned. Access at offsets 1-7 or 9-15 or 17-23 is disallowed because the target addresses would not be 8-byte aligned.
• A native segment with address 1000 can be accessed at offsets 0, 4, 8, 12, etc under a 4-byte alignment constraint, because the target addresses (1000, 1004, 1008, 1012) are 4-byte aligned. Access at offsets 1-3 or 5-7 or 9-11 is disallowed because the target addresses would not be 4-byte aligned.
• A native segment with address 1000 can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint, because the target addresses (1000, 1002, 1004, 1006) are 2-byte aligned. Access at offsets 1 or 3 or 5 is disallowed because the target addresses would not be 2-byte aligned.
• A native segment with address 1004 can be accessed at offsets 0, 4, 8, 12, etc under a 4-byte alignment constraint, and at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint. Under an 8-byte alignment constraint, it can be accessed at offsets 4, 12, 20, 28, etc.
• A native segment with address 1006 can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint. Under a 4-byte alignment constraint, it can be accessed at offsets 2, 6, 10, 14, etc. Under an 8-byte alignment constraint, it can be accessed at offsets 2, 10, 18, 26, etc.
• A native segment with address 1007 can be accessed at offsets 0, 1, 2, 3, etc under a 1-byte alignment constraint. Under a 2-byte alignment constraint, it can be accessed at offsets 1, 3, 5, 7, etc. Under a 4-byte alignment constraint, it can be accessed at offsets 1, 5, 9, 13, etc. Under an 8-byte alignment constraint, it can be accessed at offsets 1, 9, 17, 25, etc.

The alignment constraint used to access a segment is typically dictated by the shape of the data structure stored in the segment. For example, if the programmer wishes to store a sequence of 8-byte values in a native segment, then the segment should be allocated by specifying an 8-byte alignment constraint, either via Arena#allocate(long, long) or Arena#allocate(MemoryLayout). These factories ensure that the off-heap region of memory backing the returned segment has a starting address that is 8-byte aligned. Subsequently, the programmer can access the segment at the offsets of interest -- 0, 8, 16, 24, etc -- in the knowledge that every such access is aligned.

If the segment being accessed is a heap segment, then determining whether access is aligned is more complex. The address of the segment in physical memory is not known and is not even fixed (it may change when the segment is relocated during garbage collection). This means that the address cannot be combined with the specified offset to determine a target address in physical memory. Since the alignment constraint always refers to alignment of addresses in physical memory, it is not possible in principle to determine if any offset in a heap segment is aligned. For example, suppose the programmer chooses an 8-byte alignment constraint and tries to access offset 16 in a heap segment. If the heap segment's address 0 corresponds to physical address 1000, then the target address (1016) would be aligned, but if address 0 corresponds to physical address 1004, then the target address (1020) would not be aligned. It is undesirable to allow access to target addresses that are aligned according to the programmer's chosen alignment constraint, but might not be predictably aligned in physical memory (e.g. because of platform considerations and/or garbage collection behavior).

In practice, the Java runtime lays out arrays in memory so that each n-byte element occurs at an n-byte aligned physical address. The runtime preserves this invariant even if the array is relocated during garbage collection. Access operations rely on this invariant to determine if the specified offset in a heap segment refers to an aligned address in physical memory. For example:

• The starting physical address of a short[] array will be 2-byte aligned (e.g. 1006) so that successive short elements occur at 2-byte aligned addresses (e.g. 1006, 1008, 1010, 1012, etc). A heap segment backed by a short[] array can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint. The segment cannot be accessed at any offset under a 4-byte alignment constraint, because there is no guarantee that the target address would be 4-byte aligned, e.g., offset 0 would correspond to physical address 1006 while offset 1 would correspond to physical address 1007. Similarly, the segment cannot be accessed at any offset under an 8-byte alignment constraint, because there is no guarantee that the target address would be 8-byte aligned, e.g., offset 2 would correspond to physical address 1008 but offset 4 would correspond to physical address 1010.
• The starting physical address of a long[] array will be 8-byte aligned (e.g. 1000), so that successive long elements occur at 8-byte aligned addresses (e.g., 1000, 1008, 1016, 1024, etc.) A heap segment backed by a long[] array can be accessed at offsets 0, 8, 16, 24, etc under an 8-byte alignment constraint. In addition, the segment can be accessed at offsets 0, 4, 8, 12, etc under a 4-byte alignment constraint, because the target addresses (1000, 1004, 1008, 1012) are 4-byte aligned. And, the segment can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint, because the target addresses (e.g. 1000, 1002, 1004, 1006) are 2-byte aligned.

In other words, heap segments feature a maximum alignment which is derived from the size of the elements of the Java array backing the segment, as shown in the following table:

Maximum alignment of heap segments

Array type (of backing region)	Maximum supported alignment (in bytes)
boolean[]	ValueLayout.JAVA_BOOLEAN.byteAlignment()
byte[]	ValueLayout.JAVA_BYTE.byteAlignment()
char[]	ValueLayout.JAVA_CHAR.byteAlignment()
short[]	ValueLayout.JAVA_SHORT.byteAlignment()
int[]	ValueLayout.JAVA_INT.byteAlignment()
float[]	ValueLayout.JAVA_FLOAT.byteAlignment()
long[]	ValueLayout.JAVA_LONG.byteAlignment()
double[]	ValueLayout.JAVA_DOUBLE.byteAlignment()

MemorySegment byteSegment = MemorySegment.ofArray(new byte[10]);
byteSegment.get(ValueLayout.JAVA_INT, 0); // fails: ValueLayout.JAVA_INT.byteAlignment() > ValueLayout.JAVA_BYTE.byteAlignment()

MemorySegment longSegment = MemorySegment.ofArray(new long[10]);
longSegment.get(ValueLayout.JAVA_INT, 0); // ok: ValueLayout.JAVA_INT.byteAlignment() <= ValueLayout.JAVA_LONG.byteAlignment()

MemorySegment byteSegment = MemorySegment.ofArray(new byte[10]);
byteSegment.get(ValueLayout.JAVA_INT_UNALIGNED, 0); // ok: ValueLayout.JAVA_INT_UNALIGNED.byteAlignment() == ValueLayout.JAVA_BYTE.byteAlignment()

MemoryLayout layout = ...
MemorySegment segment = ...
boolean isAligned = segment.maxByteAlignment() >= layout.byteAlignment();

Zero-length memory segments

The MemorySegment API uses zero-length memory segments to represent:

• pointers returned from a foreign function;
• pointers passed by a foreign function to an upcall stub; and
• pointers read from a memory segment (more on that below).

• The size of the segment is zero. Any attempt to access these segments will fail with IndexOutOfBoundsException. This is a crucial safety feature: as these segments are associated with a region of memory whose size is not known, any access operations involving these segments cannot be validated. In effect, a zero-length memory segment wraps an address, and it cannot be used without explicit intent (see below);
• The segment is associated with the global scope. Thus, while zero-length memory segments cannot be accessed directly, they can be passed, opaquely, to other pointer-accepting foreign functions.

To demonstrate how clients can work with zero-length memory segments, consider the case of a client that wants to read a pointer from some memory segment. This can be done via the MemorySegment#get(AddressLayout, long) access method. This method accepts an address layout (e.g. ValueLayout#ADDRESS), the layout of the pointer to be read. For instance, on a 64-bit platform, the size of an address layout is 8 bytes. The access operation also accepts an offset, expressed in bytes, which indicates the position (relative to the start of the memory segment) at which the pointer is stored. The access operation returns a zero-length native memory segment, backed by a region of memory whose starting address is the 64-bit value read at the specified offset.

The returned zero-length memory segment cannot be accessed directly by the client: since the size of the segment is zero, any access operation would result in out-of-bounds access. Instead, the client must, unsafely, assign new spatial bounds to the zero-length memory segment. This can be done via the reinterpret(long) method, as follows:

MemorySegment z = segment.get(ValueLayout.ADDRESS, ...);   // size = 0
MemorySegment ptr = z.reinterpret(16);                     // size = 16
int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3);           // ok

In some cases, the client might additionally want to assign new temporal bounds to a zero-length memory segment. This can be done via the reinterpret(long, Arena, Consumer) method, which returns a new native segment with the desired size and the same temporal bounds as those of the provided arena:

MemorySegment ptr = null;
try (Arena arena = Arena.ofConfined()) {
      MemorySegment z = segment.get(ValueLayout.ADDRESS, ...);    // size = 0, scope = always alive
      ptr = z.reinterpret(16, arena, null);                       // size = 4, scope = arena.scope()
      int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3);            // ok
}
int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3);                  // throws IllegalStateException

AddressLayout intArrPtrLayout = ValueLayout.ADDRESS.withTargetLayout(
        MemoryLayout.sequenceLayout(4, ValueLayout.JAVA_INT)); // layout for int (*ptr)[4]
MemorySegment ptr = segment.get(intArrPtrLayout, ...);         // size = 16
int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3);               // ok

All the methods that can be used to manipulate zero-length memory segments (reinterpret(long), reinterpret(Arena, Consumer), reinterpret(long, Arena, Consumer) and AddressLayout#withTargetLayout(MemoryLayout)) are restricted methods, and should be used with caution: assigning a segment incorrect spatial and/or temporal bounds could result in a VM crash when attempting to access the memory segment.