Module java.base
Package java.lang.foreign

Interface AddressLayout

All Superinterfaces:
MemoryLayoutPREVIEW, ValueLayoutPREVIEW
public sealed interface AddressLayout extends ValueLayoutPREVIEW
AddressLayout is a preview API of the Java platform.
Programs can only use AddressLayout when preview features are enabled.
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 64 bits).

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:

Since:
19
See Also:

  • Method Details

    • withName

      AddressLayoutPREVIEW withName(String name)
      Returns a memory layout of the same type with the same size and alignment constraint as this layout, but with the specified name.
      Specified by:
      withName in interface MemoryLayoutPREVIEW
      Specified by:
      withName in interface ValueLayoutPREVIEW
      Parameters:
      name - the layout name.
      Returns:
      a memory layout with the given name.
      See Also:

    • withoutName

      AddressLayoutPREVIEW withoutName()
      Returns a memory layout of the same type with the same size and alignment constraint as this layout, but without a name.

      This can be useful to compare two layouts that have different names, but are otherwise equal.

      Specified by:
      withoutName in interface MemoryLayoutPREVIEW
      Specified by:
      withoutName in interface ValueLayoutPREVIEW
      Returns:
      a memory layout without a name.
      See Also:

    • withBitAlignment

      AddressLayoutPREVIEW withBitAlignment(long bitAlignment)
      Returns a memory layout of the same type with the same size and name as this layout, but with the specified alignment constraint (in bits).
      Specified by:
      withBitAlignment in interface MemoryLayoutPREVIEW
      Specified by:
      withBitAlignment in interface ValueLayoutPREVIEW
      Parameters:
      bitAlignment - the layout alignment constraint, expressed in bits.
      Returns:
      a memory layout with the given alignment constraint.

    • withOrder

      AddressLayoutPREVIEW withOrder(ByteOrder order)
      Returns a value layout with the same carrier, alignment constraint and name as this value layout, but with the specified byte order.
      Specified by:
      withOrder in interface ValueLayoutPREVIEW
      Parameters:
      order - the desired byte order.
      Returns:
      a value layout with the given byte order.

    • withTargetLayout

      AddressLayoutPREVIEW 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. 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:

    • withoutTargetLayout

      AddressLayoutPREVIEW withoutTargetLayout()
      Returns an address layout with the same carrier, alignment constraint, name and order as this address layout, but without any specified target layout.

      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

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