OpenJDK 27 · java.lang.foreign.AddressLayout · APIdia, the JavaDoc alternative

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...);
When creating an upcall stub, using Linker#upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...).

Field Summary

Inherited from java.lang.foreign.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

Method Summary

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

Inherited from java.lang.foreign.ValueLayout:: carrier order varHandle

Method Detail

targetLayout	back to summary
public Optional<MemoryLayout> targetLayout() Returns the target layout associated with this address layout (if any). Returns:Optional<MemoryLayout> the target layout associated with this address layout (if any)

targetLayout

back to summary

public Optional<MemoryLayout> targetLayout()

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

Returns:Optional<MemoryLayout>: the target layout associated with this address layout (if any)

withByteAlignment	back to summary
public AddressLayout withByteAlignment(long byteAlignment) Redeclares java.lang.foreign.ValueLayout.withByteAlignment. Doc from java.lang.foreign.ValueLayout.withByteAlignment. Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes). Annotations @Override

withByteAlignment

back to summary

public AddressLayout withByteAlignment(long byteAlignment)

Redeclares java.lang.foreign.ValueLayout.withByteAlignment.

Doc from java.lang.foreign.ValueLayout.withByteAlignment.

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

Annotations

@Override

withName	back to summary
public AddressLayout withName(String name) Redeclares java.lang.foreign.ValueLayout.withName. Doc from java.lang.foreign.ValueLayout.withName. Returns a memory layout with the same characteristics as this layout, but with the given name. Annotations @Override

withName

back to summary

public AddressLayout withName(String name)

Redeclares java.lang.foreign.ValueLayout.withName.

Doc from java.lang.foreign.ValueLayout.withName.

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

Annotations

@Override

withOrder	back to summary
public AddressLayout withOrder(ByteOrder order) Redeclares java.lang.foreign.ValueLayout.withOrder. Doc from java.lang.foreign.ValueLayout.withOrder. Returns a value layout with the same characteristics as this layout, but with the given byte order. Annotations @Override

withOrder

back to summary

public AddressLayout withOrder(ByteOrder order)

Redeclares java.lang.foreign.ValueLayout.withOrder.

Doc from java.lang.foreign.ValueLayout.withOrder.

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

Annotations

@Override

withoutName	back to summary
public AddressLayout withoutName() Redeclares java.lang.foreign.ValueLayout.withoutName. Doc from java.lang.foreign.ValueLayout.withoutName. Returns a memory layout with the same characteristics as this layout, but with no name. Annotations @Override

withoutName

back to summary

public AddressLayout withoutName()

Redeclares java.lang.foreign.ValueLayout.withoutName.

Doc from java.lang.foreign.ValueLayout.withoutName.

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

Annotations

@Override

withoutTargetLayout back to summary

withoutTargetLayout	back to summary
public 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:AddressLayout an address layout with same characteristics as this layout, but with no target layout See Also `targetLayout()`

public 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:AddressLayout: an address layout with same characteristics as this layout, but with no target layout
See Also: targetLayout()

withTargetLayout back to summary

withTargetLayout	back to summary
public AddressLayout withTargetLayout(MemoryLayout 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. 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));` AddressLayout addressLayout = ... AddressLayout unboundedLayout = addressLayout.withTargetLayout( MemoryLayout.sequenceLayout(Long.MAX_VALUE, ValueLayout.JAVA_BYTE)); Parameters layout:MemoryLayout the target layout Returns:AddressLayout an address layout with same characteristics as this layout, but with the provided target layout Annotations @CallerSensitive @Restricted Exceptions IllegalCallerException: if the caller is in a module that does not have native access enabled See Also `targetLayout()`

public AddressLayout withTargetLayout(MemoryLayout 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. 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:MemoryLayout: the target layout

Returns:AddressLayout

an address layout with same characteristics as this layout, but with the provided target layout

Annotations

@CallerSensitive
@Restricted

Exceptions

IllegalCallerException:: if the caller is in a module that does not have native access enabled

See Also

targetLayout()

public sealed Interface AddressLayout

Field Summary

Method Summary

Method Detail