A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/MemoryLayout.html below:

MemoryLayout (Java SE 21 & JDK 21)

All Known Subinterfaces:
AddressLayoutPREVIEW, GroupLayoutPREVIEW, PaddingLayoutPREVIEW, SequenceLayoutPREVIEW, StructLayoutPREVIEW, UnionLayoutPREVIEW, ValueLayoutPREVIEW, ValueLayout.OfBooleanPREVIEW, ValueLayout.OfBytePREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfDoublePREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfShortPREVIEW
MemoryLayout is a preview API of the Java platform.

A memory layout describes the contents of a memory segment.

There are two leaves in the layout hierarchy, value layoutsPREVIEW, which are used to represent values of given size and kind (see and padding layoutsPREVIEW which are used, as the name suggests, to represent a portion of a memory segment whose contents should be ignored, and which are primarily present for alignment reasons. Some common value layout constants, such as ValueLayout.JAVA_INTPREVIEW and ValueLayout.JAVA_FLOAT_UNALIGNEDPREVIEW are defined in the ValueLayoutPREVIEW class. A special kind of value layout, namely an address layoutPREVIEW, is used to model values that denote the address of a region of memory.

More complex layouts can be derived from simpler ones: a sequence layoutPREVIEW denotes a homogeneous repetition of zero or more occurrences of an element layout; a group layoutPREVIEW denotes a heterogeneous aggregation of zero or more member layouts. Group layouts come in two flavors: struct layoutsPREVIEW, where member layouts are laid out one after the other, and union layoutsPREVIEW where member layouts are laid out at the same starting offset.

Layouts can be optionally associated with a name. A layout name can be referred to when constructing layout paths.

Consider the following struct declaration in C:

typedef struct {
    char kind;
    int value;
} TaggedValues[5];

The above declaration can be modelled using a layout object, as follows:

SequenceLayout taggedValues = MemoryLayout.sequenceLayout(5,
    MemoryLayout.structLayout(
        ValueLayout.JAVA_BYTE.withName("kind"),
        MemoryLayout.paddingLayout(3),
        ValueLayout.JAVA_INT.withName("value")
    )
).withName("TaggedValues");
Characteristics of memory layouts

All layouts have a

size

(expressed in bytes), which is defined as follows:

Furthermore, all layouts have a natural alignment (expressed in bytes) which is defined as follows:

A layout's alignment can be overridden if needed (see

withByteAlignment(long)

), which can be useful to describe layouts with weaker or stronger alignment constraints.

Layout paths

A

layout path

is used to unambiguously select a layout that is nested in some other layout. Layout paths are typically expressed as a sequence of one or more

path elementsPREVIEW

. (A more formal definition of layout paths is provided

below

).

Layout paths can be used to:

For instance, given the taggedValues sequence layout constructed above, we can obtain the offset, in bytes, of the member layout named value in the first sequence element, as follows:

long valueOffset = taggedValues.byteOffset(PathElement.sequenceElement(0),
                                          PathElement.groupElement("value")); // yields 4

Similarly, we can select the member layout named

value

, as follows:

MemoryLayout value = taggedValues.select(PathElement.sequenceElement(),
                                         PathElement.groupElement("value"));
Open path elements

Some layout path elements, said

open path elements

, can select multiple layouts at once. For instance, the open path elements

MemoryLayout.PathElement.sequenceElement()PREVIEW

,

MemoryLayout.PathElement.sequenceElement(long, long)PREVIEW

select an unspecified element in a sequence layout. A var handle derived from a layout path containing one or more open path element features additional coordinates of type

long

, which can be used by clients to

bind

the open elements in the path:

VarHandle valueHandle = taggedValues.varHandle(PathElement.sequenceElement(),
                                               PathElement.groupElement("value"));
MemorySegment valuesSegment = ...
int val = (int) valueHandle.get(valuesSegment, 2); // reads the "value" field of the third struct in the array

Open path elements also affects the creation of offset-computing method handles. Each open path element becomes an additional long parameter in the obtained method handle. This parameter can be used to specify the index of the sequence element whose offset is to be computed:

MethodHandle offsetHandle = taggedValues.byteOffsetHandle(PathElement.sequenceElement(),
                                                          PathElement.groupElement("kind"));
long offset1 = (long) offsetHandle.invokeExact(1L); // 8
long offset2 = (long) offsetHandle.invokeExact(2L); // 16
Dereference path elements

A special kind of path element, called

dereference path element

, allows var handles obtained from memory layouts to follow pointers. Consider the following layout:

StructLayout RECTANGLE = MemoryLayout.structLayout(
        ValueLayout.ADDRESS.withTargetLayout(
                MemoryLayout.sequenceLayout(4,
                        MemoryLayout.structLayout(
                                ValueLayout.JAVA_INT.withName("x"),
                                ValueLayout.JAVA_INT.withName("y")
                        ).withName("point")
                 )
         ).withName("points")
);

This layout is a struct layout which describe a rectangle. It contains a single field, namely

points

, an address layout whose

target layoutPREVIEW

is a sequence layout of four struct layouts. Each struct layout describes a two-dimensional point, and is defined as a pair or

ValueLayout.JAVA_INTPREVIEW

coordinates, with names

x

and

y

, respectively.

With dereference path elements, we can obtain a var handle which accesses the y coordinate of one of the point in the rectangle, as follows:

VarHandle rectPointYs = RECTANGLE.varHandle(
        PathElement.groupElement("points"),
        PathElement.dereferenceElement(),
        PathElement.sequenceElement(),
        PathElement.groupElement("y")
);

MemorySegment rect = ...
int rect_y_4 = (int) rectPointYs.get(rect, 2); // rect.points[2]->y
Layout path well-formedness

A layout path is applied to a layout

C_0

, also called the

initial layout

. Each path element in a layout path can be thought of as a function which updates the current layout

C_i-1

to some other layout

C_i

. That is, for each path element

E1, E2, ... En

, in a layout path

P

, we compute

C_i = f_i(C_i-1)

, where

f_i

is the selection function associated with the path element under consideration, denoted as

E_i

. The final layout

C_i

is also called the

selected layout

.

A layout path P is considered well-formed for an initial layout C_0 if all its path elements E1, E2, ... En are well-formed for their corresponding input layouts C_0, C_1, ... C_n-1. A path element E is considered well-formed for a layout L if any of the following is true:

Any attempt to provide a layout path

P

that is not well-formed for an initial layout

C_0

will result in an

IllegalArgumentException

.

Implementation Requirements:
Implementations of this interface are immutable, thread-safe and value-based.
Sealed Class Hierarchy Graph:
Since:
19

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4