archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8308276: Change layout API to work with bytes, not bits

Browse source 
Reviewed-by: psandoz, pminborg
This commit is contained in:
Maurizio Cimadamore 2023-05-22 14:57:00 +00:00
parent 91aeb5de58
commit 5fc9b5787d
93 changed files with 527 additions and 721 deletions
Download patch file Download diff file Expand all files Collapse all files

4
src/java.base/share/classes/java/lang/foreign/AddressLayout.java
View file

@ -38,7 +38,7 @@ import java.util.Optional;
/**
* A value layout used to model the address of some region of memory. The carrier associated with an address layout is
* {@code 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).
* (e.g. on a 64-bit platform, the size and alignment of an address layout are set to 8 bytes).
* <p>
* An address layout may optionally feature a {@linkplain #targetLayout() target layout}. An address layout with
* target layout {@code T} can be used to model the address of a region of memory whose layout is {@code T}.
@ -74,7 +74,7 @@ public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.O
* {@inheritDoc}
*/
@Override
AddressLayout withBitAlignment(long bitAlignment);
AddressLayout withByteAlignment(long byteAlignment);
/**
* {@inheritDoc}

4
src/java.base/share/classes/java/lang/foreign/GroupLayout.java
View file

@ -68,9 +68,9 @@ public sealed interface GroupLayout extends MemoryLayout permits StructLayout, U
/**
* {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
* @throws IllegalArgumentException if {@code bitAlignment} is less than {@code M}, where {@code M} is the maximum alignment
* @throws IllegalArgumentException if {@code byteAlignment} is less than {@code M}, where {@code M} is the maximum alignment
* constraint in any of the member layouts associated with this group layout.
*/
@Override
GroupLayout withBitAlignment(long bitAlignment);
GroupLayout withByteAlignment(long byteAlignment);
}

150
src/java.base/share/classes/java/lang/foreign/MemoryLayout.java
View file

@ -75,7 +75,7 @@ import jdk.internal.javac.PreviewFeature;
* SequenceLayout taggedValues = MemoryLayout.sequenceLayout(5,
* MemoryLayout.structLayout(
* ValueLayout.JAVA_BYTE.withName("kind"),
* MemoryLayout.paddingLayout(24),
* MemoryLayout.paddingLayout(3),
* ValueLayout.JAVA_INT.withName("value")
* )
* ).withName("TaggedValues");
@ -84,7 +84,7 @@ import jdk.internal.javac.PreviewFeature;
* <h2 id="layout-align">Size, alignment and byte order</h2>
*
* All layouts have a size; layout size for value and padding layouts is always explicitly denoted; this means that a layout description
* always has the same size in bits, regardless of the platform in which it is used. For derived layouts, the size is computed
* always has the same size in bytes, regardless of the platform in which it is used. For derived layouts, the size is computed
* as follows:
* <ul>
* <li>for a sequence layout <em>S</em> whose element layout is <em>E</em> and size is <em>L</em>,
@ -104,7 +104,7 @@ import jdk.internal.javac.PreviewFeature;
* <li>for a group layout <em>G</em> with member layouts <em>M1</em>, <em>M2</em>, ... <em>Mn</em> whose alignments are
* <em>A1</em>, <em>A2</em>, ... <em>An</em>, respectively, the natural alignment of <em>G</em> is <em>max(A1, A2 ... An)</em></li>
* </ul>
* A layout's natural alignment can be overridden if needed (see {@link MemoryLayout#withBitAlignment(long)}), which can be useful to describe
* A layout's natural alignment can be overridden if needed (see {@link MemoryLayout#withByteAlignment(long)}), which can be useful to describe
* hyper-aligned layouts.
* <p>
* All value layouts have an <em>explicit</em> byte order (see {@link java.nio.ByteOrder}) which is set when the layout is created.
@ -115,17 +115,17 @@ import jdk.internal.javac.PreviewFeature;
* at a layout nested within the root layout - this is the layout <em>selected</em> by the layout path.
* Layout paths are typically expressed as a sequence of one or more {@link PathElement} instances.
* <p>
* Layout paths are for example useful in order to obtain {@linkplain MemoryLayout#bitOffset(PathElement...) offsets} of
* Layout paths are for example useful in order to obtain {@linkplain MemoryLayout#byteOffset(PathElement...) offsets} of
* arbitrarily nested layouts inside another layout, to quickly obtain a {@linkplain #varHandle(PathElement...) memory access handle}
* corresponding to the selected layout, or to {@linkplain #select(PathElement...) select} an arbitrarily nested layout inside
* another layout.
* <p>
* Such <em>layout paths</em> can be constructed programmatically using the methods in this class.
* For instance, given the {@code taggedValues} layout instance constructed as above, we can obtain the offset,
* in bits, of the member layout named <code>value</code> in the <em>first</em> sequence element, as follows:
* in bytes, of the member layout named <code>value</code> in the <em>first</em> sequence element, as follows:
* {@snippet lang=java :
* long valueOffset = taggedValues.bitOffset(PathElement.sequenceElement(0),
* PathElement.groupElement("value")); // yields 32
* long valueOffset = taggedValues.byteOffset(PathElement.sequenceElement(0),
* PathElement.groupElement("value")); // yields 4
* }
*
* Similarly, we can select the member layout named {@code value}, as follows:
@ -151,7 +151,7 @@ import jdk.internal.javac.PreviewFeature;
* access coordinate.
*
* <p>A layout path with free dimensions can also be used to create an offset-computing method handle, using the
* {@link #bitOffset(PathElement...)} or {@link #byteOffsetHandle(PathElement...)} method. Again, free dimensions are
* {@link #byteOffset(PathElement...)} or {@link #byteOffsetHandle(PathElement...)} method. Again, free dimensions are
* translated into {@code long} parameters of the created method handle. The method handle can be used to compute the
* offsets of elements of a sequence at different indices, by supplying these indices when invoking the method handle.
* For instance:
@ -172,14 +172,8 @@ import jdk.internal.javac.PreviewFeature;
@PreviewFeature(feature=PreviewFeature.Feature.FOREIGN)
public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, PaddingLayout, ValueLayout {
/**
* {@return the layout size, in bits}
*/
long bitSize();
/**
* {@return the layout size, in bytes}
* @throws UnsupportedOperationException if {@code bitSize()} is not a multiple of 8.
*/
long byteSize();
@ -210,24 +204,6 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
*/
MemoryLayout withoutName();
/**
* Returns the alignment constraint associated with this layout, expressed in bits. Layout alignment defines a power
* of two {@code A} which is the bit-wise alignment of the layout. If {@code A <= 8} then {@code A/8} is the number of
* bytes that must be aligned for any pointer that correctly points to this layout. Thus:
*
* <ul>
* <li>{@code A=8} means unaligned (in the usual sense), which is common in packets.</li>
* <li>{@code A=64} means word aligned (on LP64), {@code A=32} int aligned, {@code A=16} short aligned, etc.</li>
* <li>{@code A=512} is the most strict alignment required by the x86/SV ABI (for AVX-512 data).</li>
* </ul>
*
* If no explicit alignment constraint was set on this layout (see {@link #withBitAlignment(long)}),
* then this method returns the <a href="#layout-align">natural alignment</a> constraint (in bits) associated with this layout.
*
* @return the layout alignment constraint, in bits.
*/
long bitAlignment();
/**
* Returns the alignment constraint associated with this layout, expressed in bytes. Layout alignment defines a power
* of two {@code A} which is the byte-wise alignment of the layout, where {@code A} is the number of bytes that must be aligned
@ -239,76 +215,24 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* <li>{@code A=64} is the most strict alignment required by the x86/SV ABI (for AVX-512 data).</li>
* </ul>
*
* If no explicit alignment constraint was set on this layout (see {@link #withBitAlignment(long)}),
* If no explicit alignment constraint was set on this layout (see {@link #withByteAlignment(long)}),
* then this method returns the <a href="#layout-align">natural alignment</a> constraint (in bytes) associated with this layout.
*
* @return the layout alignment constraint, in bytes.
* @throws UnsupportedOperationException if {@code bitAlignment()} is not a multiple of 8.
*/
long byteAlignment();
/**
* 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).
* but with the specified alignment constraint (in bytes).
*
* @param bitAlignment the layout alignment constraint, expressed in bits.
* @param byteAlignment the layout alignment constraint, expressed in bytes.
* @return a memory layout with the given alignment constraint.
* @throws IllegalArgumentException if {@code bitAlignment} is not a power of two, or if it's less than 8.
* @throws IllegalArgumentException if {@code byteAlignment} is not a power of two, or if it's less than 1.
*/
MemoryLayout withBitAlignment(long bitAlignment);
MemoryLayout withByteAlignment(long byteAlignment);
/**
* Computes the offset, in bits, of the layout selected by the given layout path, where the path is considered rooted in this
* layout.
*
* @param elements the layout path elements.
* @return The offset, in bits, of the layout selected by the layout path in {@code elements}.
* @throws IllegalArgumentException if the layout path does not select any layout nested in this layout, or if the
* layout path contains one or more path elements that select multiple sequence element indices
* (see {@link PathElement#sequenceElement()} and {@link PathElement#sequenceElement(long, long)}).
* @throws IllegalArgumentException if the layout path contains one or more dereference path elements
* (see {@link PathElement#dereferenceElement()}).
* @throws NullPointerException if either {@code elements == null}, or if any of the elements
* in {@code elements} is {@code null}.
*/
default long bitOffset(PathElement... elements) {
return computePathOp(LayoutPath.rootPath(this), LayoutPath::offset,
EnumSet.of(PathKind.SEQUENCE_ELEMENT, PathKind.SEQUENCE_RANGE, PathKind.DEREF_ELEMENT), elements);
}
/**
* Creates a method handle that can be used to compute the offset, in bits, of the layout selected
* by the given layout path, where the path is considered rooted in this layout.
*
* <p>The returned method handle has a return type of {@code long}, and features as many {@code long}
* parameter types as there are free dimensions in the provided layout path (see {@link PathElement#sequenceElement()}),
* where the order of the parameters corresponds to the order of the path elements.
* The returned method handle can be used to compute a layout offset similar to {@link #bitOffset(PathElement...)},
* but where some sequence indices are specified only when invoking the method handle.
*
* <p>The final offset returned by the method handle is computed as follows:
*
* <blockquote><pre>{@code
* offset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
* }</pre></blockquote>
*
* where {@code x_1}, {@code x_2}, ... {@code x_n} are <em>dynamic</em> values provided as {@code long}
* arguments, whereas {@code c_1}, {@code c_2}, ... {@code c_m} are <em>static</em> offset constants
* and {@code s_0}, {@code s_1}, ... {@code s_n} are <em>static</em> stride constants which are derived from
* the layout path.
*
* @param elements the layout path elements.
* @return a method handle that can be used to compute the bit offset of the layout element
* specified by the given layout path elements, when supplied with the missing sequence element indices.
* @throws IllegalArgumentException if the layout path contains one or more path elements that select
* multiple sequence element indices (see {@link PathElement#sequenceElement(long, long)}).
* @throws IllegalArgumentException if the layout path contains one or more dereference path elements
* (see {@link PathElement#dereferenceElement()}).
*/
default MethodHandle bitOffsetHandle(PathElement... elements) {
return computePathOp(LayoutPath.rootPath(this), LayoutPath::offsetHandle,
EnumSet.of(PathKind.SEQUENCE_RANGE, PathKind.DEREF_ELEMENT), elements);
}
/**
* Computes the offset, in bytes, of the layout selected by the given layout path, where the path is considered rooted in this
@ -321,12 +245,12 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* (see {@link PathElement#sequenceElement()} and {@link PathElement#sequenceElement(long, long)}).
* @throws IllegalArgumentException if the layout path contains one or more dereference path elements
* (see {@link PathElement#dereferenceElement()}).
* @throws UnsupportedOperationException if {@code bitOffset(elements)} is not a multiple of 8.
* @throws NullPointerException if either {@code elements == null}, or if any of the elements
* in {@code elements} is {@code null}.
*/
default long byteOffset(PathElement... elements) {
return Utils.bitsToBytes(bitOffset(elements));
return computePathOp(LayoutPath.rootPath(this), LayoutPath::offset,
EnumSet.of(PathKind.SEQUENCE_ELEMENT, PathKind.SEQUENCE_RANGE, PathKind.DEREF_ELEMENT), elements);
}
/**
@ -342,8 +266,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* <p>The final offset returned by the method handle is computed as follows:
*
* <blockquote><pre>{@code
* bitOffset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
* offset = bitOffset / 8
* byteOffset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
* }</pre></blockquote>
*
* where {@code x_1}, {@code x_2}, ... {@code x_n} are <em>dynamic</em> values provided as {@code long}
@ -351,9 +274,6 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* and {@code s_0}, {@code s_1}, ... {@code s_n} are <em>static</em> stride constants which are derived from
* the layout path.
*
* <p>The method handle will throw an {@link UnsupportedOperationException} if the computed
* offset in bits is not a multiple of 8.
*
* @param elements the layout path elements.
* @return a method handle that can be used to compute the byte offset of the layout element
* specified by the given layout path elements, when supplied with the missing sequence element indices.
@ -363,9 +283,8 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* (see {@link PathElement#dereferenceElement()}).
*/
default MethodHandle byteOffsetHandle(PathElement... elements) {
MethodHandle mh = bitOffsetHandle(elements);
mh = MethodHandles.filterReturnValue(mh, Utils.BITS_TO_BYTES);
return mh;
return computePathOp(LayoutPath.rootPath(this), LayoutPath::offsetHandle,
EnumSet.of(PathKind.SEQUENCE_RANGE, PathKind.DEREF_ELEMENT), elements);
}
/**
@ -448,8 +367,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* <p>The offset of the returned segment is computed as follows:
*
* <blockquote><pre>{@code
* bitOffset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
* offset = bitOffset / 8
* byteOffset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
* }</pre></blockquote>
*
* where {@code x_1}, {@code x_2}, ... {@code x_n} are <em>dynamic</em> values provided as {@code long}
@ -465,12 +383,8 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* where {@code segment} is the segment to be sliced, and where {@code layout} is the layout selected by the given
* layout path, as per {@link MemoryLayout#select(PathElement...)}.
*
* <p>The method handle will throw an {@link UnsupportedOperationException} if the computed
* offset in bits is not a multiple of 8.
*
* @param elements the layout path elements.
* @return a method handle which can be used to create a slice of the selected layout element, given a segment.
* @throws UnsupportedOperationException if the size of the selected layout in bits is not a multiple of 8.
* @throws IllegalArgumentException if the layout path contains one or more dereference path elements
* (see {@link PathElement#dereferenceElement()}).
*/
@ -687,14 +601,14 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
String toString();
/**
* Creates a padding layout with the given bitSize and a bit-alignment of eight.
* Creates a padding layout with the given byte size and a byte-alignment of one.
*
* @param bitSize the padding size in bits.
* @param byteSize the padding size (expressed in bytes).
* @return the new selector layout.
* @throws IllegalArgumentException if {@code bitSize <= 0} or {@code bitSize % 8 != 0}
* @throws IllegalArgumentException if {@code byteSize <= 0}.
*/
static PaddingLayout paddingLayout(long bitSize) {
return PaddingLayoutImpl.of(MemoryLayoutUtil.requireBitSizeValid(bitSize, false));
static PaddingLayout paddingLayout(long byteSize) {
return PaddingLayoutImpl.of(MemoryLayoutUtil.requireByteSizeValid(byteSize, false));
}
/**
@ -704,7 +618,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* @param elementLayout the sequence element layout.
* @return the new sequence layout with the given element layout and size.
* @throws IllegalArgumentException if {@code elementCount } is negative.
* @throws IllegalArgumentException if {@code elementLayout.bitSize() % elementLayout.bitAlignment() != 0}.
* @throws IllegalArgumentException if {@code elementLayout.byteSize() % elementLayout.byteAlignment() != 0}.
*/
static SequenceLayout sequenceLayout(long elementCount, MemoryLayout elementLayout) {
MemoryLayoutUtil.requireNonNegative(elementCount);
@ -720,16 +634,16 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
*
* This is equivalent to the following code:
* {@snippet lang = java:
* sequenceLayout(Long.MAX_VALUE / elementLayout.bitSize(), elementLayout);
* sequenceLayout(Long.MAX_VALUE / elementLayout.byteSize(), elementLayout);
* }
*
* @param elementLayout the sequence element layout.
* @return a new sequence layout with the given element layout and maximum element count.
* @throws IllegalArgumentException if {@code elementLayout.bitSize() % elementLayout.bitAlignment() != 0}.
* @throws IllegalArgumentException if {@code elementLayout.byteSize() % elementLayout.byteAlignment() != 0}.
*/
static SequenceLayout sequenceLayout(MemoryLayout elementLayout) {
Objects.requireNonNull(elementLayout);
return sequenceLayout(Long.MAX_VALUE / elementLayout.bitSize(), elementLayout);
return sequenceLayout(Long.MAX_VALUE / elementLayout.byteSize(), elementLayout);
}
/**
@ -737,7 +651,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
*
* @param elements The member layouts of the struct layout.
* @return a struct layout with the given member layouts.
* @throws IllegalArgumentException if the sum of the {@linkplain #bitSize() bit sizes} of the member layouts
* @throws IllegalArgumentException if the sum of the {@linkplain #byteSize() byte sizes} of the member layouts
* overflows.
* @throws IllegalArgumentException if a member layout in {@code elements} occurs at an offset (relative to the start
* of the struct layout) which is not compatible with its alignment constraint.
@ -752,14 +666,14 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* To avoid the exception, clients can either insert additional padding layout elements:
*
* {@snippet lang = java:
* structLayout(JAVA_SHORT, MemoryLayout.ofPadding(16), JAVA_INT)
* structLayout(JAVA_SHORT, MemoryLayout.ofPadding(2), JAVA_INT)
* }
*
* Or, alternatively, they can use a member layout which features a smaller alignment constraint. This will result
* in a <em>packed</em> struct layout:
*
* {@snippet lang = java:
* structLayout(JAVA_SHORT, JAVA_INT.withBitAlignment(16))
* structLayout(JAVA_SHORT, JAVA_INT.withByteAlignment(2))
* }
*/
static StructLayout structLayout(MemoryLayout... elements) {

6
src/java.base/share/classes/java/lang/foreign/MemorySegment.java
View file

@ -379,7 +379,7 @@ import jdk.internal.vm.annotation.ForceInline;
* to read a pointer from some memory segment. This can be done via the
* {@linkplain MemorySegment#get(AddressLayout, long)} access method. This method accepts an
* {@linkplain AddressLayout address layout} (e.g. {@link ValueLayout#ADDRESS}), the layout of the pointer
* to be read. For instance on a 64-bit platform, the size of an address layout is 64 bits. The access operation
* to be read. For instance on a 64-bit platform, the size of an address layout is 8 bytes. The access operation
* also accepts an offset, expressed in bytes, which indicates the position (relative to the start of the memory segment)
* at which the pointer is stored. The access operation returns a zero-length native memory segment, backed by a region
* of memory whose starting address is the 64-bit value read at the specified offset.
@ -470,7 +470,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* @return the element spliterator for this segment
* @throws IllegalArgumentException if {@code elementLayout.byteSize() == 0}.
* @throws IllegalArgumentException if {@code byteSize() % elementLayout.byteSize() != 0}.
* @throws IllegalArgumentException if {@code elementLayout.bitSize() % elementLayout.bitAlignment() != 0}.
* @throws IllegalArgumentException if {@code elementLayout.byteSize() % elementLayout.byteAlignment() != 0}.
* @throws IllegalArgumentException if this segment is <a href="MemorySegment.html#segment-alignment">incompatible
* with the alignment constraint</a> in the provided layout.
*/
@ -487,7 +487,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* @return a sequential {@code Stream} over disjoint slices in this segment.
* @throws IllegalArgumentException if {@code elementLayout.byteSize() == 0}.
* @throws IllegalArgumentException if {@code byteSize() % elementLayout.byteSize() != 0}.
* @throws IllegalArgumentException if {@code elementLayout.bitSize() % elementLayout.bitAlignment() != 0}.
* @throws IllegalArgumentException if {@code elementLayout.byteSize() % elementLayout.byteAlignment() != 0}.
* @throws IllegalArgumentException if this segment is <a href="MemorySegment.html#segment-alignment">incompatible
* with the alignment constraint</a> in the provided layout.
*/

3
src/java.base/share/classes/java/lang/foreign/PaddingLayout.java
View file

@ -56,6 +56,5 @@ public sealed interface PaddingLayout extends MemoryLayout permits PaddingLayout
* {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
PaddingLayout withBitAlignment(long bitAlignment);
PaddingLayout withByteAlignment(long byteAlignment);
}

4
src/java.base/share/classes/java/lang/foreign/SequenceLayout.java
View file

@ -143,7 +143,7 @@ public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayo
/**
* {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
* @throws IllegalArgumentException if {@code bitAlignment < elementLayout().bitAlignment()}.
* @throws IllegalArgumentException if {@code byteAlignment < elementLayout().byteAlignment()}.
*/
SequenceLayout withBitAlignment(long bitAlignment);
SequenceLayout withByteAlignment(long byteAlignment);
}

2
src/java.base/share/classes/java/lang/foreign/StructLayout.java
View file

@ -56,5 +56,5 @@ public sealed interface StructLayout extends GroupLayout permits StructLayoutImp
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
StructLayout withBitAlignment(long bitAlignment);
StructLayout withByteAlignment(long byteAlignment);
}

2
src/java.base/share/classes/java/lang/foreign/UnionLayout.java
View file

@ -56,5 +56,5 @@ public sealed interface UnionLayout extends GroupLayout permits UnionLayoutImpl
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
UnionLayout withBitAlignment(long bitAlignment);
UnionLayout withByteAlignment(long byteAlignment);
}

68
src/java.base/share/classes/java/lang/foreign/ValueLayout.java
View file

@ -37,7 +37,7 @@ import jdk.internal.javac.PreviewFeature;
* <em>integral</em> values (either signed or unsigned), <em>floating-point</em> values and
* <em>address</em> values.
* <p>
* Each value layout has a size, an alignment (in bits),
* Each value layout has a size, an alignment (both expressed in bytes),
* a {@linkplain ByteOrder byte order}, and a <em>carrier</em>, that is, the Java type that should be used when
* {@linkplain MemorySegment#get(OfInt, long) accessing} a region of memory using the value layout.
* <p>
@ -129,7 +129,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* featuring {@code shape.length + 1}
* {@code long} coordinates.
* @throws IllegalArgumentException if {@code shape[i] < 0}, for at least one index {@code i}.
* @throws UnsupportedOperationException if {@code bitAlignment() > bitSize()}.
* @throws UnsupportedOperationException if {@code byteAlignment() > byteSize()}.
* @see MethodHandles#memorySegmentViewVarHandle
* @see MemoryLayout#varHandle(PathElement...)
* @see SequenceLayout
@ -152,7 +152,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
ValueLayout withBitAlignment(long bitAlignment);
ValueLayout withByteAlignment(long byteAlignment);
/**
* A value layout whose carrier is {@code boolean.class}.
@ -180,7 +180,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
OfBoolean withBitAlignment(long bitAlignment);
OfBoolean withByteAlignment(long byteAlignment);
/**
* {@inheritDoc}
@ -216,7 +216,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
OfByte withBitAlignment(long bitAlignment);
OfByte withByteAlignment(long byteAlignment);
/**
* {@inheritDoc}
@ -253,7 +253,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
OfChar withBitAlignment(long bitAlignment);
OfChar withByteAlignment(long byteAlignment);
/**
* {@inheritDoc}
@ -290,7 +290,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
OfShort withBitAlignment(long bitAlignment);
OfShort withByteAlignment(long byteAlignment);
/**
* {@inheritDoc}
@ -327,7 +327,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
OfInt withBitAlignment(long bitAlignment);
OfInt withByteAlignment(long byteAlignment);
/**
* {@inheritDoc}
@ -363,7 +363,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* {@inheritDoc}
*/
@Override
OfFloat withBitAlignment(long bitAlignment);
OfFloat withByteAlignment(long byteAlignment);
/**
* {@inheritDoc}
@ -400,7 +400,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
OfLong withBitAlignment(long bitAlignment);
OfLong withByteAlignment(long byteAlignment);
/**
* {@inheritDoc}
@ -437,7 +437,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
OfDouble withBitAlignment(long bitAlignment);
OfDouble withByteAlignment(long byteAlignment);
/**
* {@inheritDoc}
@ -449,56 +449,56 @@ public sealed interface ValueLayout extends MemoryLayout permits
/**
* A value layout constant whose size is the same as that of a machine address ({@code size_t}),
* bit alignment set to {@code sizeof(size_t) * 8}, byte order set to {@link ByteOrder#nativeOrder()}.
* byte alignment set to {@code sizeof(size_t)}, byte order set to {@link ByteOrder#nativeOrder()}.
*/
AddressLayout ADDRESS = ValueLayouts.OfAddressImpl.of(ByteOrder.nativeOrder());
/**
* A value layout constant whose size is the same as that of a Java {@code byte},
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* byte alignment set to 1, and byte order set to {@link ByteOrder#nativeOrder()}.
*/
OfByte JAVA_BYTE = ValueLayouts.OfByteImpl.of(ByteOrder.nativeOrder());
/**
* A value layout constant whose size is the same as that of a Java {@code boolean},
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* byte alignment set to 1, and byte order set to {@link ByteOrder#nativeOrder()}.
*/
OfBoolean JAVA_BOOLEAN = ValueLayouts.OfBooleanImpl.of(ByteOrder.nativeOrder());
/**
* A value layout constant whose size is the same as that of a Java {@code char},
* bit alignment set to 16, and byte order set to {@link ByteOrder#nativeOrder()}.
* byte alignment set to 2, and byte order set to {@link ByteOrder#nativeOrder()}.
*/
OfChar JAVA_CHAR = ValueLayouts.OfCharImpl.of(ByteOrder.nativeOrder());
/**
* A value layout constant whose size is the same as that of a Java {@code short},
* bit alignment set to 16, and byte order set to {@link ByteOrder#nativeOrder()}.
* byte alignment set to 2, and byte order set to {@link ByteOrder#nativeOrder()}.
*/
OfShort JAVA_SHORT = ValueLayouts.OfShortImpl.of(ByteOrder.nativeOrder());
/**
* A value layout constant whose size is the same as that of a Java {@code int},
* bit alignment set to 32, and byte order set to {@link ByteOrder#nativeOrder()}.
* byte alignment set to 4, and byte order set to {@link ByteOrder#nativeOrder()}.
*/
OfInt JAVA_INT = ValueLayouts.OfIntImpl.of(ByteOrder.nativeOrder());
/**
* A value layout constant whose size is the same as that of a Java {@code long},
* (platform-dependent) bit alignment set to {@code ADDRESS.bitSize()},
* (platform-dependent) byte alignment set to {@code ADDRESS.byteSize()},
* and byte order set to {@link ByteOrder#nativeOrder()}.
*/
OfLong JAVA_LONG = ValueLayouts.OfLongImpl.of(ByteOrder.nativeOrder());
/**
* A value layout constant whose size is the same as that of a Java {@code float},
* bit alignment set to 32, and byte order set to {@link ByteOrder#nativeOrder()}.
* byte alignment set to 4, and byte order set to {@link ByteOrder#nativeOrder()}.
*/
OfFloat JAVA_FLOAT = ValueLayouts.OfFloatImpl.of(ByteOrder.nativeOrder());
/**
* A value layout constant whose size is the same as that of a Java {@code double},
* (platform-dependent) bit alignment set to {@code ADDRESS.bitSize()},
* (platform-dependent) byte alignment set to {@code ADDRESS.byteSize()},
* and byte order set to {@link ByteOrder#nativeOrder()}.
*/
OfDouble JAVA_DOUBLE = ValueLayouts.OfDoubleImpl.of(ByteOrder.nativeOrder());
@ -508,83 +508,83 @@ public sealed interface ValueLayout extends MemoryLayout permits
* and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* ADDRESS.withBitAlignment(8);
* ADDRESS.withByteAlignment(1);
* }
* @apiNote Care should be taken when using unaligned value layouts as they may induce
* performance and portability issues.
*/
AddressLayout ADDRESS_UNALIGNED = ADDRESS.withBitAlignment(8);
AddressLayout ADDRESS_UNALIGNED = ADDRESS.withByteAlignment(1);
/**
* An unaligned value layout constant whose size is the same as that of a Java {@code char}
* and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* JAVA_CHAR.withBitAlignment(8);
* JAVA_CHAR.withByteAlignment(1);
* }
* @apiNote Care should be taken when using unaligned value layouts as they may induce
* performance and portability issues.
*/
OfChar JAVA_CHAR_UNALIGNED = JAVA_CHAR.withBitAlignment(8);
OfChar JAVA_CHAR_UNALIGNED = JAVA_CHAR.withByteAlignment(1);
/**
* An unaligned value layout constant whose size is the same as that of a Java {@code short}
* and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* JAVA_SHORT.withBitAlignment(8);
* JAVA_SHORT.withByteAlignment(1);
* }
* @apiNote Care should be taken when using unaligned value layouts as they may induce
* performance and portability issues.
*/
OfShort JAVA_SHORT_UNALIGNED = JAVA_SHORT.withBitAlignment(8);
OfShort JAVA_SHORT_UNALIGNED = JAVA_SHORT.withByteAlignment(1);
/**
* An unaligned value layout constant whose size is the same as that of a Java {@code int}
* and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* JAVA_INT.withBitAlignment(8);
* JAVA_INT.withByteAlignment(1);
* }
* @apiNote Care should be taken when using unaligned value layouts as they may induce
* performance and portability issues.
*/
OfInt JAVA_INT_UNALIGNED = JAVA_INT.withBitAlignment(8);
OfInt JAVA_INT_UNALIGNED = JAVA_INT.withByteAlignment(1);
/**
* An unaligned value layout constant whose size is the same as that of a Java {@code long}
* and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* JAVA_LONG.withBitAlignment(8);
* JAVA_LONG.withByteAlignment(1);
* }
* @apiNote Care should be taken when using unaligned value layouts as they may induce
* performance and portability issues.
*/
OfLong JAVA_LONG_UNALIGNED = JAVA_LONG.withBitAlignment(8);
OfLong JAVA_LONG_UNALIGNED = JAVA_LONG.withByteAlignment(1);
/**
* An unaligned value layout constant whose size is the same as that of a Java {@code float}
* and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* JAVA_FLOAT.withBitAlignment(8);
* JAVA_FLOAT.withByteAlignment(1);
* }
* @apiNote Care should be taken when using unaligned value layouts as they may induce
* performance and portability issues.
*/
OfFloat JAVA_FLOAT_UNALIGNED = JAVA_FLOAT.withBitAlignment(8);
OfFloat JAVA_FLOAT_UNALIGNED = JAVA_FLOAT.withByteAlignment(1);
/**
* An unaligned value layout constant whose size is the same as that of a Java {@code double}
* and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* JAVA_DOUBLE.withBitAlignment(8);
* JAVA_DOUBLE.withByteAlignment(1);
* }
* @apiNote Care should be taken when using unaligned value layouts as they may induce
* performance and portability issues.
*/
OfDouble JAVA_DOUBLE_UNALIGNED = JAVA_DOUBLE.withBitAlignment(8);
OfDouble JAVA_DOUBLE_UNALIGNED = JAVA_DOUBLE.withByteAlignment(1);
}

2
src/java.base/share/classes/java/lang/invoke/MethodHandles.java
View file

@ -7964,7 +7964,7 @@ assertEquals("boojum", (String) catTrace.invokeExact("boo", "jum"));
* <p>As an example, consider the memory layout expressed by a {@link GroupLayout} instance constructed as follows:
* {@snippet lang="java" :
* GroupLayout seq = java.lang.foreign.MemoryLayout.structLayout(
* MemoryLayout.paddingLayout(32),
* MemoryLayout.paddingLayout(4),
* ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN).withName("value")
* );
* }