Interface AddressLayout

All Superinterfaces:

MemoryLayout, ValueLayout

public sealed interface AddressLayout
extends ValueLayout

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_INT 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);
• When creating a downcall method handle, using Linker.downcallHandle(FunctionDescriptor, Option...)^RESTRICTED;
• When creating an upcall stub, using Linker.upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...)^RESTRICTED.

Implementation Requirements:

Implementations of this interface are immutable, thread-safe and value-based.

Since:

22

See Also:

• ValueLayout.ADDRESS
• ValueLayout.ADDRESS_UNALIGNED

Nested Class Summary

Nested classes/interfaces declared in interface MemoryLayout

MemoryLayout.PathElement

Modifier and Type	Interface	Description
static interface	MemoryLayout.PathElement	An element in a layout path.

Nested classes/interfaces declared in interface ValueLayout

ValueLayout.OfBoolean, ValueLayout.OfByte, ValueLayout.OfChar, ValueLayout.OfDouble, ValueLayout.OfFloat, ValueLayout.OfInt, ValueLayout.OfLong, ValueLayout.OfShort

Modifier and Type	Interface	Description
static interface	ValueLayout.OfBoolean	A value layout whose carrier is boolean.class.
static interface	ValueLayout.OfByte	A value layout whose carrier is byte.class.
static interface	ValueLayout.OfChar	A value layout whose carrier is char.class.
static interface	ValueLayout.OfDouble	A value layout whose carrier is double.class.
static interface	ValueLayout.OfFloat	A value layout whose carrier is float.class.
static interface	ValueLayout.OfInt	A value layout whose carrier is int.class.
static interface	ValueLayout.OfLong	A value layout whose carrier is long.class.
static interface	ValueLayout.OfShort	A value layout whose carrier is short.class.

Field Summary

Fields declared in interface ValueLayout

ADDRESS, 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

Modifier and Type	Field	Description
static final AddressLayout	ADDRESS	An address layout constant whose size is the same as that of a machine address (size_t), byte alignment set to sizeof(size_t), byte order set to ByteOrder.nativeOrder().
static final AddressLayout	ADDRESS_UNALIGNED	An unaligned address layout constant whose size is the same as that of a machine address (size_t), and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfBoolean	JAVA_BOOLEAN	A value layout constant whose size is the same as that of a Java boolean, byte alignment set to 1, and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfByte	JAVA_BYTE	A value layout constant whose size is the same as that of a Java byte, byte alignment set to 1, and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfChar	JAVA_CHAR	A value layout constant whose size is the same as that of a Java char, byte alignment set to 2, and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfChar	JAVA_CHAR_UNALIGNED	An unaligned value layout constant whose size is the same as that of a Java char and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfDouble	JAVA_DOUBLE	A value layout constant whose size is the same as that of a Java double, byte alignment set to 8, and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfDouble	JAVA_DOUBLE_UNALIGNED	An unaligned value layout constant whose size is the same as that of a Java double and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfFloat	JAVA_FLOAT	A value layout constant whose size is the same as that of a Java float, byte alignment set to 4, and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfFloat	JAVA_FLOAT_UNALIGNED	An unaligned value layout constant whose size is the same as that of a Java float and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfInt	JAVA_INT	A value layout constant whose size is the same as that of a Java int, byte alignment set to 4, and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfInt	JAVA_INT_UNALIGNED	An unaligned value layout constant whose size is the same as that of a Java int and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfLong	JAVA_LONG	A value layout constant whose size is the same as that of a Java long, byte alignment set to 8, and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfLong	JAVA_LONG_UNALIGNED	An unaligned value layout constant whose size is the same as that of a Java long and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfShort	JAVA_SHORT	A value layout constant whose size is the same as that of a Java short, byte alignment set to 2, and byte order set to ByteOrder.nativeOrder().
static final ValueLayout.OfShort	JAVA_SHORT_UNALIGNED	An unaligned value layout constant whose size is the same as that of a Java short and byte order set to ByteOrder.nativeOrder().

Method Summary

Modifier and Type	Method	Description
Optional<MemoryLayout>	targetLayout()	Returns the target layout associated with this address layout (if any).
AddressLayout	withByteAlignment(long byteAlignment)	Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).
AddressLayout	withName(String name)	Returns a memory layout with the same characteristics as this layout, but with the given name.
AddressLayout	withOrder(ByteOrder order)	Returns a value layout with the same characteristics as this layout, but with the given byte order.
AddressLayout	withoutName()	Returns a memory layout with the same characteristics as this layout, but with no name.
AddressLayout	withoutTargetLayout()	Returns an address layout with the same carrier, alignment constraint, name and order as this address layout, but with no target layout.
AddressLayout	withTargetLayout(MemoryLayout layout)	Restricted. 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 MemoryLayout

arrayElementVarHandle, byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, scale, scaleHandle, select, sliceHandle, toString, varHandle

Modifier and Type	Method	Description
VarHandle	arrayElementVarHandle(MemoryLayout.PathElement... elements)	Creates a var handle that accesses adjacent elements in a memory segment at offsets selected by the given layout path, where the accessed elements have this layout, and where the initial layout in the path is this layout.
long	byteAlignment()	Returns the alignment constraint associated with this layout, expressed in bytes.
long	byteOffset(MemoryLayout.PathElement... elements)	Computes the offset, in bytes, of the layout selected by the given layout path, where the initial layout in the path is this layout.
MethodHandle	byteOffsetHandle(MemoryLayout.PathElement... elements)	Creates a method handle that computes the offset, in bytes, of the layout selected by the given layout path, where the initial layout in the path is this layout.
long	byteSize()	Returns the layout size, in bytes.
boolean	equals(Object other)	Compares the specified object with this layout for equality.
int	hashCode()	Returns the hash code value for this layout.
Optional<String>	name()	Returns the name (if any) associated with this layout.
long	scale(long offset, long index)	Returns offset + (byteSize() * index).
MethodHandle	scaleHandle()	Returns a method handle that can be used to invoke MemoryLayout.scale(long, long) on this layout.
MemoryLayout	select(MemoryLayout.PathElement... elements)	Returns the layout selected from the provided path, where the initial layout in the path is this layout.
MethodHandle	sliceHandle(MemoryLayout.PathElement... elements)	Creates a method handle which, given a memory segment, returns a slice corresponding to the layout selected by the given layout path, where the initial layout in the path is this layout.
String	toString()	Returns the string representation of this layout.
VarHandle	varHandle(MemoryLayout.PathElement... elements)	Creates a var handle that accesses a memory segment at the offset selected by the given layout path, where the initial layout in the path is this layout.

Methods declared in interface ValueLayout

carrier, order, varHandle

Modifier and Type	Method	Description
Class<?>	carrier()	Returns the carrier associated with this value layout.
ByteOrder	order()	Returns the value's byte order.
VarHandle	varHandle()	Returns a var handle which can be used to access values described by this value layout, in a given memory segment.

Method Details

withName

AddressLayout withName(String name)

Returns a memory layout with the same characteristics as this layout, but with the given name.

Specified by:

withName in interface MemoryLayout

Specified by:

withName in interface ValueLayout

Parameters:

name - the layout name

Returns:

a memory layout with the same characteristics as this layout, but with the given name

See Also:

• MemoryLayout.name()

withoutName

AddressLayout withoutName()

Returns a memory layout with the same characteristics as this layout, but with no name.

Specified by:

withoutName in interface MemoryLayout

Specified by:

withoutName in interface ValueLayout

Returns:

a memory layout with the same characteristics as this layout, but with no name

See Also:

• MemoryLayout.name()

withByteAlignment

AddressLayout withByteAlignment(long byteAlignment)

Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).

Specified by:

withByteAlignment in interface MemoryLayout

Specified by:

withByteAlignment in interface ValueLayout

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)

withOrder

AddressLayout withOrder(ByteOrder order)

Returns a value layout with the same characteristics as this layout, but with the given byte order.

Specified by:

withOrder in interface ValueLayout

Parameters:

order - the desired byte order

Returns:

a value layout with the same characteristics as this layout, but with the given byte order

withTargetLayout

AddressLayout withTargetLayout(MemoryLayout layout)

withTargetLayout is a restricted method of the Java platform.

Programs can only use withTargetLayout when access to restricted methods is enabled.

Restricted methods are unsafe, and, if used incorrectly, might crash the JVM or result in memory corruption.

Returns 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 segments 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(Long.MAX_VALUE, ValueLayout.JAVA_BYTE));

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:

• targetLayout()

withoutTargetLayout

AddressLayout 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:

• targetLayout()

targetLayout

Optional<MemoryLayout> targetLayout()

Returns the target layout associated with this address layout (if any).

Returns:

the target layout associated with this address layout (if any)