- All Superinterfaces:
- MemoryLayoutPREVIEW,- ValueLayoutPREVIEW
AddressLayout is a preview API of the Java platform.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A value layout used to model the address of some region of memory. The carrier associated with an address layout is
 
MemorySegment.class. The size and alignment of an address layout are platform-dependent
 (e.g. on a 64-bit platform, the size and alignment of an address layout are set to 8 bytes).
 
 An address layout may optionally feature a target layout. An address layout with
 target layout T can be used to model the address of a region of memory whose layout is T.
 For instance, an address layout with target layout ValueLayout.JAVA_INTPREVIEW can be used to model the address
 of a region of memory that is 4 bytes long. Specifying a target layout can be useful in the following situations:
 
- When accessing a memory segment that has been obtained by reading an address from another
     memory segment, e.g. using MemorySegment.getAtIndex(AddressLayout, long)PREVIEW;
- When creating a downcall method handle, using Linker.downcallHandle(FunctionDescriptor, Option...)PREVIEW;
- When creating an upcall stub, using Linker.upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...)PREVIEW.
- Since:
- 19
- See Also:
- 
Nested Class SummaryNested classes/interfaces declared in interface java.lang.foreign.MemoryLayoutPREVIEWMemoryLayout.PathElementPREVIEWNested classes/interfaces declared in interface java.lang.foreign.ValueLayoutPREVIEWValueLayout.OfBooleanPREVIEW, ValueLayout.OfBytePREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfDoublePREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfShortPREVIEW
- 
Field SummaryFields declared in interface java.lang.foreign.ValueLayoutPREVIEWADDRESS, ADDRESS_UNALIGNED, JAVA_BOOLEAN, JAVA_BYTE, JAVA_CHAR, JAVA_CHAR_UNALIGNED, JAVA_DOUBLE, JAVA_DOUBLE_UNALIGNED, JAVA_FLOAT, JAVA_FLOAT_UNALIGNED, JAVA_INT, JAVA_INT_UNALIGNED, JAVA_LONG, JAVA_LONG_UNALIGNED, JAVA_SHORT, JAVA_SHORT_UNALIGNED
- 
Method SummaryModifier and TypeMethodDescriptionReturns the target layout associated with this address layout (if any).withByteAlignment(long byteAlignment) Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).Returns a memory layout with the same characteristics as this layout, but with the given name.Returns a value layout with the same characteristics as this layout, but with the given byte order.Returns a memory layout with the same characteristics as this layout, but with no name.Returns an address layout with the same carrier, alignment constraint, name and order as this address layout, but with no target layout.withTargetLayout(MemoryLayoutPREVIEW layout) Returns an address layout with the same carrier, alignment constraint, name and order as this address layout, but associated with the specified target layout.Methods declared in interface java.lang.foreign.MemoryLayoutPREVIEWbyteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, select, sliceHandle, toString, varHandleMethods declared in interface java.lang.foreign.ValueLayoutPREVIEWarrayElementVarHandle, carrier, order
- 
Method Details- 
withNameReturns a memory layout with the same characteristics as this layout, but with the given name.- Specified by:
- withNamein interface- MemoryLayoutPREVIEW
- Specified by:
- withNamein interface- ValueLayoutPREVIEW
- Parameters:
- name- the layout name.
- Returns:
- a memory layout with the same characteristics as this layout, but with the given name
- See Also:
 
- 
withoutNameAddressLayoutPREVIEW withoutName()Returns a memory layout with the same characteristics as this layout, but with no name.- Specified by:
- withoutNamein interface- MemoryLayoutPREVIEW
- Specified by:
- withoutNamein interface- ValueLayoutPREVIEW
- Returns:
- a memory layout with the same characteristics as this layout, but with no name
- See Also:
 
- 
withByteAlignmentReturns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).- Specified by:
- withByteAlignmentin interface- MemoryLayoutPREVIEW
- Specified by:
- withByteAlignmentin interface- ValueLayoutPREVIEW
- Parameters:
- byteAlignment- the layout alignment constraint, expressed in bytes.
- Returns:
- a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes)
 
- 
withOrderReturns a value layout with the same characteristics as this layout, but with the given byte order.- Specified by:
- withOrderin interface- ValueLayoutPREVIEW
- Parameters:
- order- the desired byte order.
- Returns:
- a value layout with the same characteristics as this layout, but with the given byte order
 
- 
withTargetLayoutReturns an address layout with the same carrier, alignment constraint, name and order as this address layout, but associated with the specified target layout. The returned address layout allows raw addresses to be accessed as memory segmentsPREVIEW whose size is set to the size of the specified layout. Moreover, if the accessed raw address is not compatible with the alignment constraint in the provided layout, IllegalArgumentException will be thrown.- API Note:
- This method can also be used to create an address layout which, when used, creates native memory
 segments with maximal size (e.g. Long.MAX_VALUE). This can be done by using a target sequence
 layout with unspecified size, as follows:
 
AddressLayout addressLayout = ... AddressLayout unboundedLayout = addressLayout.withTargetLayout( MemoryLayout.sequenceLayout(ValueLayout.JAVA_BYTE));This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible. 
- Parameters:
- layout- the target layout.
- Returns:
- an address layout with same characteristics as this layout, but with the provided target layout.
- Throws:
- IllegalCallerException- If the caller is in a module that does not have native access enabled.
- See Also:
 
- 
withoutTargetLayoutAddressLayoutPREVIEW withoutTargetLayout()Returns an address layout with the same carrier, alignment constraint, name and order as this address layout, but with no target layout.- API Note:
- This can be useful to compare two address layouts that have different target layouts, but are otherwise equal.
- Returns:
- an address layout with same characteristics as this layout, but with no target layout.
- See Also:
 
- 
targetLayoutOptional<MemoryLayoutPREVIEW> targetLayout()Returns the target layout associated with this address layout (if any)..- Returns:
- the target layout associated with this address layout (if any)
 
 
- 
AddressLayoutwhen preview features are enabled.