From be01caf30de5a70684fab25b02f2c6ab346a60cb Mon Sep 17 00:00:00 2001 From: Per Minborg Date: Fri, 3 Nov 2023 12:26:47 +0000 Subject: [PATCH] 8319323: FFM: Harmonize the @throws tags in the javadocs Reviewed-by: jvernee --- .../java/lang/foreign/AddressLayout.java | 2 +- .../classes/java/lang/foreign/Arena.java | 16 +- .../java/lang/foreign/FunctionDescriptor.java | 14 +- .../java/lang/foreign/GroupLayout.java | 4 +- .../classes/java/lang/foreign/Linker.java | 26 +- .../java/lang/foreign/MemoryLayout.java | 52 +- .../java/lang/foreign/MemorySegment.java | 722 +++++++++--------- .../java/lang/foreign/SegmentAllocator.java | 45 +- .../java/lang/foreign/SequenceLayout.java | 12 +- .../java/lang/foreign/SymbolLookup.java | 12 +- 10 files changed, 454 insertions(+), 451 deletions(-) diff --git a/src/java.base/share/classes/java/lang/foreign/AddressLayout.java b/src/java.base/share/classes/java/lang/foreign/AddressLayout.java index 3e2e3dc2bc9..ded175571be 100644 --- a/src/java.base/share/classes/java/lang/foreign/AddressLayout.java +++ b/src/java.base/share/classes/java/lang/foreign/AddressLayout.java @@ -101,7 +101,7 @@ public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.O * * @param layout the target layout. * @return 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. + * @throws IllegalCallerException If the caller is in a module that does not have native access enabled * @see #targetLayout() */ @CallerSensitive diff --git a/src/java.base/share/classes/java/lang/foreign/Arena.java b/src/java.base/share/classes/java/lang/foreign/Arena.java index 45cb46d33d6..f25b54a6b29 100644 --- a/src/java.base/share/classes/java/lang/foreign/Arena.java +++ b/src/java.base/share/classes/java/lang/foreign/Arena.java @@ -260,11 +260,11 @@ public interface Arena extends SegmentAllocator, AutoCloseable { * @param byteSize the size (in bytes) of the off-heap region of memory backing the native memory segment. * @param byteAlignment the alignment constraint (in bytes) of the off-heap region of memory backing the native memory segment. * @return a new native memory segment. - * @throws IllegalArgumentException if {@code bytesSize < 0}, {@code byteAlignment <= 0}, or if {@code byteAlignment} - * is not a power of 2. - * @throws IllegalStateException if this arena has already been {@linkplain #close() closed}. + * @throws IllegalArgumentException if {@code bytesSize < 0}, {@code byteAlignment <= 0}, + * or if {@code byteAlignment} is not a power of 2 + * @throws IllegalStateException if this arena has already been {@linkplain #close() closed} * @throws WrongThreadException if this arena is confined, and this method is called from a thread - * other than the arena's owner thread. + * other than the arena's owner thread */ @Override MemorySegment allocate(long byteSize, long byteAlignment); @@ -289,12 +289,12 @@ public interface Arena extends SegmentAllocator, AutoCloseable { * * @see Scope#isAlive() * - * @throws IllegalStateException if the arena has already been closed. + * @throws IllegalStateException if the arena has already been closed * @throws IllegalStateException if a segment associated with this arena is being accessed concurrently, e.g. - * by a {@linkplain Linker#downcallHandle(FunctionDescriptor, Linker.Option...) downcall method handle}. + * by a {@linkplain Linker#downcallHandle(FunctionDescriptor, Linker.Option...) downcall method handle} * @throws WrongThreadException if this arena is confined, and this method is called from a thread - * other than the arena's owner thread. - * @throws UnsupportedOperationException if this arena cannot be closed explicitly. + * other than the arena's owner thread + * @throws UnsupportedOperationException if this arena cannot be closed explicitly */ @Override void close(); diff --git a/src/java.base/share/classes/java/lang/foreign/FunctionDescriptor.java b/src/java.base/share/classes/java/lang/foreign/FunctionDescriptor.java index f715e4b91bd..23c64164951 100644 --- a/src/java.base/share/classes/java/lang/foreign/FunctionDescriptor.java +++ b/src/java.base/share/classes/java/lang/foreign/FunctionDescriptor.java @@ -61,7 +61,7 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl { * Returns a function descriptor with the given argument layouts appended to the argument layouts * of this function descriptor. * @param addedLayouts the argument layouts to append. - * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout. + * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout * @return a new function descriptor, with the provided additional argument layouts. */ FunctionDescriptor appendArgumentLayouts(MemoryLayout... addedLayouts); @@ -72,15 +72,15 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl { * @param index the index at which to insert the arguments * @param addedLayouts the argument layouts to insert at given index. * @return a new function descriptor, with the provided additional argument layouts. - * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout. - * @throws IllegalArgumentException if {@code index < 0 || index > argumentLayouts().size()}. + * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout + * @throws IllegalArgumentException if {@code index < 0 || index > argumentLayouts().size()} */ FunctionDescriptor insertArgumentLayouts(int index, MemoryLayout... addedLayouts); /** * Returns a function descriptor with the provided return layout. * @param newReturn the new return layout. - * @throws IllegalArgumentException if {@code newReturn} is a padding layout. + * @throws IllegalArgumentException if {@code newReturn} is a padding layout * @return a new function descriptor, with the provided return layout. */ FunctionDescriptor changeReturnLayout(MemoryLayout newReturn); @@ -110,8 +110,8 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl { * Creates a function descriptor with the given return and argument layouts. * @param resLayout the return layout. * @param argLayouts the argument layouts. - * @throws IllegalArgumentException if {@code resLayout} is a padding layout. - * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout. + * @throws IllegalArgumentException if {@code resLayout} is a padding layout + * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout * @return a new function descriptor with the provided return and argument layouts. */ static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argLayouts) { @@ -124,7 +124,7 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl { * Creates a function descriptor with the given argument layouts and no return layout. This is useful to model functions * that return no values. * @param argLayouts the argument layouts. - * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout. + * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout * @return a new function descriptor with the provided argument layouts. */ static FunctionDescriptor ofVoid(MemoryLayout... argLayouts) { diff --git a/src/java.base/share/classes/java/lang/foreign/GroupLayout.java b/src/java.base/share/classes/java/lang/foreign/GroupLayout.java index e6654fcc8a5..8182b0da9bf 100644 --- a/src/java.base/share/classes/java/lang/foreign/GroupLayout.java +++ b/src/java.base/share/classes/java/lang/foreign/GroupLayout.java @@ -65,8 +65,8 @@ public sealed interface GroupLayout extends MemoryLayout permits StructLayout, U /** * {@inheritDoc} * @throws IllegalArgumentException {@inheritDoc} - * @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. + * @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 withByteAlignment(long byteAlignment); diff --git a/src/java.base/share/classes/java/lang/foreign/Linker.java b/src/java.base/share/classes/java/lang/foreign/Linker.java index 738ff19a517..1a39f9db3b3 100644 --- a/src/java.base/share/classes/java/lang/foreign/Linker.java +++ b/src/java.base/share/classes/java/lang/foreign/Linker.java @@ -525,10 +525,10 @@ public sealed interface Linker permits AbstractLinker { * @param function the function descriptor of the target foreign function. * @param options the linker options associated with this linkage request. * @return a downcall method handle. - * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker. - * @throws IllegalArgumentException if {@code !address.isNative()}, or if {@code address.equals(MemorySegment.NULL)}. - * @throws IllegalArgumentException if an invalid combination of linker options is given. - * @throws IllegalCallerException If the caller is in a module that does not have native access enabled. + * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker + * @throws IllegalArgumentException if {@code !address.isNative()}, or if {@code address.equals(MemorySegment.NULL)} + * @throws IllegalArgumentException if an invalid combination of linker options is given + * @throws IllegalCallerException If the caller is in a module that does not have native access enabled * * @see SymbolLookup */ @@ -575,9 +575,9 @@ public sealed interface Linker permits AbstractLinker { * @param function the function descriptor of the target foreign function. * @param options the linker options associated with this linkage request. * @return a downcall method handle. - * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker. - * @throws IllegalArgumentException if an invalid combination of linker options is given. - * @throws IllegalCallerException If the caller is in a module that does not have native access enabled. + * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker + * @throws IllegalArgumentException if an invalid combination of linker options is given + * @throws IllegalCallerException If the caller is in a module that does not have native access enabled */ @CallerSensitive @Restricted @@ -610,14 +610,14 @@ public sealed interface Linker permits AbstractLinker { * @param arena the arena associated with the returned upcall stub segment. * @param options the linker options associated with this linkage request. * @return a zero-length segment whose address is the address of the upcall stub. - * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker. + * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker * @throws IllegalArgumentException if the type of {@code target} is incompatible with the - * type {@linkplain FunctionDescriptor#toMethodType() derived} from {@code function}. - * @throws IllegalArgumentException if it is determined that the target method handle can throw an exception. + * type {@linkplain FunctionDescriptor#toMethodType() derived} from {@code function} + * @throws IllegalArgumentException if it is determined that the target method handle can throw an exception * @throws IllegalStateException if {@code arena.scope().isAlive() == false} * @throws WrongThreadException if {@code arena} is a confined arena, and this method is called from a - * thread {@code T}, other than the arena's owner thread. - * @throws IllegalCallerException If the caller is in a module that does not have native access enabled. + * thread {@code T}, other than the arena's owner thread + * @throws IllegalCallerException If the caller is in a module that does not have native access enabled */ @CallerSensitive @Restricted @@ -726,7 +726,7 @@ public sealed interface Linker permits AbstractLinker { * * @param capturedState the names of the values to save. * @throws IllegalArgumentException if at least one of the provided {@code capturedState} names - * is unsupported on the current platform. + * is unsupported on the current platform * @see #captureStateLayout() */ static Option captureCallState(String... capturedState) { diff --git a/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java b/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java index b3303ad75ac..6533849a920 100644 --- a/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java +++ b/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java @@ -446,7 +446,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * alignment constraint (in bytes)} * * @param byteAlignment the layout alignment constraint, expressed in bytes. - * @throws IllegalArgumentException if {@code byteAlignment} is not a power of two. + * @throws IllegalArgumentException if {@code byteAlignment} is not a power of two */ MemoryLayout withByteAlignment(long byteAlignment); @@ -471,9 +471,9 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * * @param elements the layout path elements. * @return The offset, in bytes, of the layout selected by the layout path in {@code elements}. - * @throws IllegalArgumentException if the layout path is not well-formed for this layout. - * @throws IllegalArgumentException if the layout path contains one or more open path elements. - * @throws IllegalArgumentException if the layout path contains one or more dereference path elements. + * @throws IllegalArgumentException if the layout path is not well-formed for this layout + * @throws IllegalArgumentException if the layout path contains one or more open path elements + * @throws IllegalArgumentException if the layout path contains one or more dereference path elements */ long byteOffset(PathElement... elements); @@ -507,8 +507,8 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * * @param elements the layout path elements. * @return a method handle that computes the offset, in bytes, of the layout selected by the given layout path. - * @throws IllegalArgumentException if the layout path is not well-formed for this layout. - * @throws IllegalArgumentException if the layout path contains one or more dereference path elements. + * @throws IllegalArgumentException if the layout path is not well-formed for this layout + * @throws IllegalArgumentException if the layout path contains one or more dereference path elements */ MethodHandle byteOffsetHandle(PathElement... elements); @@ -599,8 +599,8 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * * @param elements the layout path elements. * @return a var handle that accesses a memory segment at the offset selected by the given layout path. - * @throws IllegalArgumentException if the layout path is not well-formed for this layout. - * @throws IllegalArgumentException if the layout selected by the provided path is not a {@linkplain ValueLayout value layout}. + * @throws IllegalArgumentException if the layout path is not well-formed for this layout + * @throws IllegalArgumentException if the layout selected by the provided path is not a {@linkplain ValueLayout value layout} */ VarHandle varHandle(PathElement... elements); @@ -642,8 +642,8 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * * @param elements the layout path elements. * @return a var handle that accesses adjacent elements in a memory segment at offsets selected by the given layout path. - * @throws IllegalArgumentException if the layout path is not well-formed for this layout. - * @throws IllegalArgumentException if the layout selected by the provided path is not a {@linkplain ValueLayout value layout}. + * @throws IllegalArgumentException if the layout path is not well-formed for this layout + * @throws IllegalArgumentException if the layout selected by the provided path is not a {@linkplain ValueLayout value layout} */ VarHandle arrayElementVarHandle(PathElement... elements); @@ -681,8 +681,8 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * * @param elements the layout path elements. * @return a method handle which is used to slice a memory segment at the offset selected by the given layout path. - * @throws IllegalArgumentException if the layout path is not well-formed for this layout. - * @throws IllegalArgumentException if the layout path contains one or more dereference path elements. + * @throws IllegalArgumentException if the layout path is not well-formed for this layout + * @throws IllegalArgumentException if the layout path contains one or more dereference path elements */ MethodHandle sliceHandle(PathElement... elements); @@ -691,10 +691,10 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * * @param elements the layout path elements. * @return the layout selected by the layout path in {@code elements}. - * @throws IllegalArgumentException if the layout path is not well-formed for this layout. - * @throws IllegalArgumentException if the layout path contains one or more dereference path elements. + * @throws IllegalArgumentException if the layout path is not well-formed for this layout + * @throws IllegalArgumentException if the layout path contains one or more dereference path elements * @throws IllegalArgumentException if the layout path contains one or more path elements that select one or more - * sequence element indices, such as {@link PathElement#sequenceElement(long)} and {@link PathElement#sequenceElement(long, long)}). + * sequence element indices, such as {@link PathElement#sequenceElement(long)} and {@link PathElement#sequenceElement(long, long)}) */ MemoryLayout select(PathElement... elements); @@ -738,7 +738,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * * @param index the index of the member layout element to be selected. * @return a path element which selects the group member layout with the given index. - * @throws IllegalArgumentException if {@code index < 0}. + * @throws IllegalArgumentException if {@code index < 0} */ static PathElement groupElement(long index) { if (index < 0) { @@ -753,7 +753,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * * @param index the index of the sequence element to be selected. * @return a path element which selects the sequence element layout with the given index. - * @throws IllegalArgumentException if {@code index < 0}. + * @throws IllegalArgumentException if {@code index < 0} */ static PathElement sequenceElement(long index) { if (index < 0) { @@ -778,7 +778,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * @param start the index of the first sequence element to be selected. * @param step the step factor at which subsequence sequence elements are to be selected. * @return a path element which selects the sequence element layout with the given index. - * @throws IllegalArgumentException if {@code start < 0}, or {@code step == 0}. + * @throws IllegalArgumentException if {@code start < 0}, or {@code step == 0} */ static PathElement sequenceElement(long start, long step) { if (start < 0) { @@ -856,7 +856,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * * @param byteSize the padding size (expressed in bytes). * @return the new selector layout. - * @throws IllegalArgumentException if {@code byteSize <= 0}. + * @throws IllegalArgumentException if {@code byteSize <= 0} */ static PaddingLayout paddingLayout(long byteSize) { return PaddingLayoutImpl.of(MemoryLayoutUtil.requireByteSizeValid(byteSize, false)); @@ -868,9 +868,9 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin * @param elementCount the sequence element count. * @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.byteSize() * elementCount} overflows. - * @throws IllegalArgumentException if {@code elementLayout.byteSize() % elementLayout.byteAlignment() != 0}. + * @throws IllegalArgumentException if {@code elementCount} is negative + * @throws IllegalArgumentException if {@code elementLayout.byteSize() * elementCount} overflows + * @throws IllegalArgumentException if {@code elementLayout.byteSize() % elementLayout.byteAlignment() != 0} */ static SequenceLayout sequenceLayout(long elementCount, MemoryLayout elementLayout) { MemoryLayoutUtil.requireNonNegative(elementCount); @@ -885,10 +885,10 @@ 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 #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. + * @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 * * @apiNote This factory does not automatically align element layouts, by inserting additional {@linkplain PaddingLayout * padding layout} elements. As such, the following struct layout creation will fail with an exception: diff --git a/src/java.base/share/classes/java/lang/foreign/MemorySegment.java b/src/java.base/share/classes/java/lang/foreign/MemorySegment.java index 7f2a2e7f352..19e7c41781a 100644 --- a/src/java.base/share/classes/java/lang/foreign/MemorySegment.java +++ b/src/java.base/share/classes/java/lang/foreign/MemorySegment.java @@ -471,11 +471,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * * @param elementLayout the layout to be used for splitting. * @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.byteSize() % elementLayout.byteAlignment() != 0}. + * @throws IllegalArgumentException if {@code elementLayout.byteSize() == 0} + * @throws IllegalArgumentException if {@code byteSize() % elementLayout.byteSize() != 0} + * @throws IllegalArgumentException if {@code elementLayout.byteSize() % elementLayout.byteAlignment() != 0} * @throws IllegalArgumentException if this segment is incompatible - * with the alignment constraint in the provided layout. + * with the alignment constraint in the provided layout. */ Spliterator spliterator(MemoryLayout elementLayout); @@ -488,11 +488,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * * @param elementLayout the layout to be used for splitting. * @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.byteSize() % elementLayout.byteAlignment() != 0}. + * @throws IllegalArgumentException if {@code elementLayout.byteSize() == 0} + * @throws IllegalArgumentException if {@code byteSize() % elementLayout.byteSize() != 0} + * @throws IllegalArgumentException if {@code elementLayout.byteSize() % elementLayout.byteAlignment() != 0} * @throws IllegalArgumentException if this segment is incompatible - * with the alignment constraint in the provided layout. + * with the alignment constraint in the provided layout. */ Stream elements(MemoryLayout elementLayout); @@ -527,7 +527,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param newSize The new segment size, specified in bytes. * @return a slice of this memory segment. * @throws IndexOutOfBoundsException if {@code offset < 0}, {@code offset > byteSize()}, {@code newSize < 0}, - * or {@code newSize > byteSize() - offset} + * or {@code newSize > byteSize() - offset} */ MemorySegment asSlice(long offset, long newSize); @@ -540,10 +540,10 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param byteAlignment The alignment constraint (in bytes) of the returned slice. * @return a slice of this memory segment. * @throws IndexOutOfBoundsException if {@code offset < 0}, {@code offset > byteSize()}, {@code newSize < 0}, - * or {@code newSize > byteSize() - offset} + * or {@code newSize > byteSize() - offset} * @throws IllegalArgumentException if this segment cannot be accessed at {@code offset} under - * the provided alignment constraint. - * @throws IllegalArgumentException if {@code byteAlignment <= 0}, or if {@code byteAlignment} is not a power of 2. + * the provided alignment constraint + * @throws IllegalArgumentException if {@code byteAlignment <= 0}, or if {@code byteAlignment} is not a power of 2 */ MemorySegment asSlice(long offset, long newSize, long byteAlignment); @@ -561,9 +561,9 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset The new segment base offset (relative to the address of this segment), specified in bytes. * @param layout The layout of the segment slice. * @throws IndexOutOfBoundsException if {@code offset < 0}, {@code offset > byteSize()}, - * or {@code layout.byteSize() > byteSize() - offset} + * or {@code layout.byteSize() > byteSize() - offset} * @throws IllegalArgumentException if this segment cannot be accessed at {@code offset} under - * the alignment constraint specified by {@code layout}. + * the alignment constraint specified by {@code layout} * @return a slice of this memory segment. */ MemorySegment asSlice(long offset, MemoryLayout layout); @@ -581,7 +581,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * * @param offset The new segment base offset (relative to the address of this segment), specified in bytes. * @return a slice of this memory segment. - * @throws IndexOutOfBoundsException if {@code offset < 0}, or {@code offset > byteSize()}. + * @throws IndexOutOfBoundsException if {@code offset < 0}, or {@code offset > byteSize()} */ MemorySegment asSlice(long offset); @@ -591,9 +591,9 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param newSize the size of the returned segment. * @return a new memory segment that has the same address and scope as this segment, but the new * provided size. - * @throws IllegalArgumentException if {@code newSize < 0}. - * @throws UnsupportedOperationException if this segment is not a {@linkplain #isNative() native} segment. - * @throws IllegalCallerException If the caller is in a module that does not have native access enabled. + * @throws IllegalArgumentException if {@code newSize < 0} + * @throws UnsupportedOperationException if this segment is not a {@linkplain #isNative() native} segment + * @throws IllegalCallerException if the caller is in a module that does not have native access enabled */ @CallerSensitive @Restricted @@ -626,9 +626,9 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param arena the arena to be associated with the returned segment. * @param cleanup the cleanup action that should be executed when the provided arena is closed (can be {@code null}). * @return a new memory segment with unbounded size. - * @throws IllegalStateException if {@code arena.scope().isAlive() == false}. - * @throws UnsupportedOperationException if this segment is not a {@linkplain #isNative() native} segment. - * @throws IllegalCallerException If the caller is in a module that does not have native access enabled. + * @throws IllegalStateException if {@code arena.scope().isAlive() == false} + * @throws UnsupportedOperationException if this segment is not a {@linkplain #isNative() native} segment + * @throws IllegalCallerException if the caller is in a module that does not have native access enabled */ @CallerSensitive @Restricted @@ -663,10 +663,10 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param cleanup the cleanup action that should be executed when the provided arena is closed (can be {@code null}). * @return a new segment that has the same address as this segment, but with new size and its scope set to * that of the provided arena. - * @throws UnsupportedOperationException if this segment is not a {@linkplain #isNative() native} segment. - * @throws IllegalArgumentException if {@code newSize < 0}. - * @throws IllegalStateException if {@code arena.scope().isAlive() == false}. - * @throws IllegalCallerException If the caller is in a module that does not have native access enabled. + * @throws UnsupportedOperationException if this segment is not a {@linkplain #isNative() native} segment + * @throws IllegalArgumentException if {@code newSize < 0} + * @throws IllegalStateException if {@code arena.scope().isAlive() == false} + * @throws IllegalCallerException if the caller is in a module that does not have native access enabled */ @CallerSensitive @Restricted @@ -737,10 +737,10 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param value the value to write into this segment. * @return this memory segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * such that {@code isAccessibleBy(T) == false} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ MemorySegment fill(byte value); @@ -754,16 +754,16 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * MemorySegment.copy(src, 0, this, 0, src.byteSize()); * } * @param src the source segment. - * @throws IndexOutOfBoundsException if {@code src.byteSize() > this.byteSize()}. + * @throws IndexOutOfBoundsException if {@code src.byteSize() > this.byteSize()} * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code src} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code src.isAccessibleBy(T) == false}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * such that {@code src.isAccessibleBy(T) == false} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} * @return this segment. */ MemorySegment copyFrom(MemorySegment src); @@ -787,13 +787,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @return the relative offset, in bytes, of the first mismatch between this * and the given other segment, otherwise -1 if no mismatch. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code other} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code other.isAccessibleBy(T) == false}. + * such that {@code other.isAccessibleBy(T) == false} */ long mismatch(MemorySegment other); @@ -816,11 +816,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * is resident in physical memory * * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws UnsupportedOperationException if this segment is not a mapped memory segment, e.g. if - * {@code isMapped() == false}. + * {@code isMapped() == false}. */ boolean isLoaded(); @@ -833,11 +833,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * occur.

* * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws UnsupportedOperationException if this segment is not a mapped memory segment, e.g. if - * {@code isMapped() == false}. + * {@code isMapped() == false} */ void load(); @@ -850,11 +850,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * occur (as this segment's contents might need to be paged back in).

* * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws UnsupportedOperationException if this segment is not a mapped memory segment, e.g. if - * {@code isMapped() == false}. + * {@code isMapped() == false} */ void unload(); @@ -879,12 +879,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { *

* * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws UnsupportedOperationException if this segment is not a mapped memory segment, e.g. if - * {@code isMapped() == false}. - * @throws UncheckedIOException if there is an I/O error writing the contents of this segment to the associated storage device + * {@code isMapped() == false} + * @throws UncheckedIOException if there is an I/O error writing the contents of this segment to the + * associated storage device */ void force(); @@ -916,8 +917,8 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * * @return a {@link ByteBuffer} view of this memory segment. * @throws UnsupportedOperationException if this segment cannot be mapped onto a {@link ByteBuffer} instance, - * e.g. if it is a heap segment backed by an array other than {@code byte[]}), or if its size is greater - * than {@link Integer#MAX_VALUE}. + * e.g. if it is a heap segment backed by an array other than {@code byte[]}), or if its size is greater + * than {@link Integer#MAX_VALUE} */ ByteBuffer asByteBuffer(); @@ -927,11 +928,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * different from the {@linkplain ByteOrder#nativeOrder native order}, a byte swap operation will be performed on each array element. * @return a new byte array whose contents are copied from this memory segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalStateException if this segment's contents cannot be copied into a {@code byte[]} instance, - * e.g. its size is greater than {@link Integer#MAX_VALUE}. + * e.g. its size is greater than {@link Integer#MAX_VALUE} */ byte[] toArray(ValueLayout.OfByte elementLayout); @@ -941,11 +942,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * different from the {@linkplain ByteOrder#nativeOrder native order}, a byte swap operation will be performed on each array element. * @return a new short array whose contents are copied from this memory segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalStateException if this segment's contents cannot be copied into a {@code short[]} instance, - * e.g. because {@code byteSize() % 2 != 0}, or {@code byteSize() / 2 > Integer.MAX_VALUE} + * e.g. because {@code byteSize() % 2 != 0}, or {@code byteSize() / 2 > Integer.MAX_VALUE} */ short[] toArray(ValueLayout.OfShort elementLayout); @@ -955,11 +956,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * different from the {@linkplain ByteOrder#nativeOrder native order}, a byte swap operation will be performed on each array element. * @return a new char array whose contents are copied from this memory segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalStateException if this segment's contents cannot be copied into a {@code char[]} instance, - * e.g. because {@code byteSize() % 2 != 0}, or {@code byteSize() / 2 > Integer.MAX_VALUE}. + * e.g. because {@code byteSize() % 2 != 0}, or {@code byteSize() / 2 > Integer.MAX_VALUE} */ char[] toArray(ValueLayout.OfChar elementLayout); @@ -969,11 +970,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * different from the {@linkplain ByteOrder#nativeOrder native order}, a byte swap operation will be performed on each array element. * @return a new int array whose contents are copied from this memory segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalStateException if this segment's contents cannot be copied into a {@code int[]} instance, - * e.g. because {@code byteSize() % 4 != 0}, or {@code byteSize() / 4 > Integer.MAX_VALUE}. + * e.g. because {@code byteSize() % 4 != 0}, or {@code byteSize() / 4 > Integer.MAX_VALUE} */ int[] toArray(ValueLayout.OfInt elementLayout); @@ -983,11 +984,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * different from the {@linkplain ByteOrder#nativeOrder native order}, a byte swap operation will be performed on each array element. * @return a new float array whose contents are copied from this memory segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalStateException if this segment's contents cannot be copied into a {@code float[]} instance, - * e.g. because {@code byteSize() % 4 != 0}, or {@code byteSize() / 4 > Integer.MAX_VALUE}. + * e.g. because {@code byteSize() % 4 != 0}, or {@code byteSize() / 4 > Integer.MAX_VALUE}. */ float[] toArray(ValueLayout.OfFloat elementLayout); @@ -997,11 +998,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * different from the {@linkplain ByteOrder#nativeOrder native order}, a byte swap operation will be performed on each array element. * @return a new long array whose contents are copied from this memory segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalStateException if this segment's contents cannot be copied into a {@code long[]} instance, - * e.g. because {@code byteSize() % 8 != 0}, or {@code byteSize() / 8 > Integer.MAX_VALUE}. + * e.g. because {@code byteSize() % 8 != 0}, or {@code byteSize() / 8 > Integer.MAX_VALUE} */ long[] toArray(ValueLayout.OfLong elementLayout); @@ -1011,11 +1012,11 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * different from the {@linkplain ByteOrder#nativeOrder native order}, a byte swap operation will be performed on each array element. * @return a new double array whose contents are copied from this memory segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false}. * @throws IllegalStateException if this segment's contents cannot be copied into a {@code double[]} instance, - * e.g. because {@code byteSize() % 8 != 0}, or {@code byteSize() / 8 > Integer.MAX_VALUE}. + * e.g. because {@code byteSize() % 8 != 0}, or {@code byteSize() / 8 > Integer.MAX_VALUE}. */ double[] toArray(ValueLayout.OfDouble elementLayout); @@ -1031,14 +1032,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return a Java string constructed from the bytes read from the given starting address up to (but not including) * the first {@code '\0'} terminator character (assuming one is found). - * @throws IllegalArgumentException if the size of the string is greater than the largest string supported by the platform. - * @throws IndexOutOfBoundsException if {@code offset < 0}. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + 1)}, where {@code B} is the size, - * in bytes, of the string encoded using UTF-8 charset {@code str.getBytes(StandardCharsets.UTF_8).length}). + * @throws IllegalArgumentException if the size of the string is greater than the largest string + * supported by the platform. + * @throws IndexOutOfBoundsException if {@code offset < 0} + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + 1)}, where {@code B} is the size, + * in bytes, of the string encoded using UTF-8 charset {@code str.getBytes(StandardCharsets.UTF_8).length}) * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} */ String getString(long offset); @@ -1054,20 +1056,21 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param charset the charset used to {@linkplain Charset#newDecoder() decode} the string bytes. * @return a Java string constructed from the bytes read from the given starting address up to (but not including) * the first {@code '\0'} terminator character (assuming one is found). - * @throws IllegalArgumentException if the size of the string is greater than the largest string supported by the platform. - * @throws IndexOutOfBoundsException if {@code offset < 0}. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + N)}, where: - *
    - *
  • {@code B} is the size, in bytes, of the string encoded using the provided charset - * (e.g. {@code str.getBytes(charset).length});
    • - *
  • {@code N} is the size (in bytes) of the terminator char according to the provided charset. For instance, - * this is 1 for {@link StandardCharsets#US_ASCII} and 2 for {@link StandardCharsets#UTF_16}.
    • - *
- * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. - * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. - * @throws IllegalArgumentException if {@code charset} is not a {@linkplain StandardCharsets standard charset}. + * @throws IllegalArgumentException if the size of the string is greater than the largest string + * supported by the platform + * @throws IndexOutOfBoundsException if {@code offset < 0} + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + N)}, where: + *
    + *
  • {@code B} is the size, in bytes, of the string encoded using the provided charset + * (e.g. {@code str.getBytes(charset).length});
    • + *
  • {@code N} is the size (in bytes) of the terminator char according to the provided charset. For instance, + * this is 1 for {@link StandardCharsets#US_ASCII} and 2 for {@link StandardCharsets#UTF_16}.
    • + *
+ * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not + * {@linkplain Scope#isAlive() alive} + * @throws WrongThreadException if this method is called from a thread {@code T}, + * such that {@code isAccessibleBy(T) == false} + * @throws IllegalArgumentException if {@code charset} is not a {@linkplain StandardCharsets standard charset} */ String getString(long offset, Charset charset); @@ -1082,13 +1085,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * the final address of this write operation can be expressed as {@code address() + offset}. * @param str the Java string to be written into this segment. - * @throws IndexOutOfBoundsException if {@code offset < 0}. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + 1)}, where {@code B} is the size, - * in bytes, of the string encoded using UTF-8 charset {@code str.getBytes(StandardCharsets.UTF_8).length}). + * @throws IndexOutOfBoundsException if {@code offset < 0} + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + 1)}, where {@code B} is the size, + * in bytes, of the string encoded using UTF-8 charset {@code str.getBytes(StandardCharsets.UTF_8).length}) * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false}. */ void setString(long offset, String str); @@ -1110,19 +1113,19 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * the final address of this write operation can be expressed as {@code address() + offset}. * @param str the Java string to be written into this segment. * @param charset the charset used to {@linkplain Charset#newEncoder() encode} the string bytes. - * @throws IndexOutOfBoundsException if {@code offset < 0}. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + N)}, where: - *
    - *
  • {@code B} is the size, in bytes, of the string encoded using the provided charset - * (e.g. {@code str.getBytes(charset).length});
    • - *
  • {@code N} is the size (in bytes) of the terminator char according to the provided charset. For instance, - * this is 1 for {@link StandardCharsets#US_ASCII} and 2 for {@link StandardCharsets#UTF_16}.
    • - *
- * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. - * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. - * @throws IllegalArgumentException if {@code charset} is not a {@linkplain StandardCharsets standard charset}. + * @throws IndexOutOfBoundsException if {@code offset < 0} + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + N)}, where: + *
    + *
  • {@code B} is the size, in bytes, of the string encoded using the provided charset + * (e.g. {@code str.getBytes(charset).length});
    • + *
  • {@code N} is the size (in bytes) of the terminator char according to the provided charset. For + * instance, this is 1 for {@link StandardCharsets#US_ASCII} and 2 for {@link StandardCharsets#UTF_16}.
    • + *
+ * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not + * {@linkplain Scope#isAlive() alive} + * @throws WrongThreadException if this method is called from a thread {@code T}, + * such that {@code isAccessibleBy(T) == false} + * @throws IllegalArgumentException if {@code charset} is not a {@linkplain StandardCharsets standard charset} */ void setString(long offset, String str, Charset charset); @@ -1142,10 +1145,9 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * * @param buffer the buffer instance to be turned into a new memory segment. * @return a memory segment, derived from the given buffer instance. - * @throws IllegalArgumentException if the provided {@code buffer} is a heap buffer but is not backed by an array. - * For example, buffers directly or indirectly obtained via - * ({@link CharBuffer#wrap(CharSequence)} or {@link CharBuffer#wrap(char[], int, int)} - * are not backed by an array. + * @throws IllegalArgumentException if the provided {@code buffer} is a heap buffer but is not backed by an array; + * For example, buffers directly or indirectly obtained via ({@link CharBuffer#wrap(CharSequence)} or + * {@link CharBuffer#wrap(char[], int, int)} are not backed by an array */ static MemorySegment ofBuffer(Buffer buffer) { return AbstractMemorySegmentImpl.ofBuffer(buffer); @@ -1279,18 +1281,18 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param dstOffset the starting offset, in bytes, of the destination segment. * @param bytes the number of bytes to be copied. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code srcSegment} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code srcSegment.isAccessibleBy(T) == false}. + * such that {@code srcSegment.isAccessibleBy(T) == false} * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code dstSegment} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code dstSegment.isAccessibleBy(T) == false}. - * @throws IndexOutOfBoundsException if {@code srcOffset > srcSegment.byteSize() - bytes}. - * @throws IndexOutOfBoundsException if {@code dstOffset > dstSegment.byteSize() - bytes}. + * such that {@code dstSegment.isAccessibleBy(T) == false} + * @throws IndexOutOfBoundsException if {@code srcOffset > srcSegment.byteSize() - bytes} + * @throws IndexOutOfBoundsException if {@code dstOffset > dstSegment.byteSize() - bytes} * @throws IndexOutOfBoundsException if either {@code srcOffset}, {@code dstOffset} - * or {@code bytes} are {@code < 0}. - * @throws UnsupportedOperationException if {@code dstSegment} is {@linkplain #isReadOnly() read-only}. + * or {@code bytes} are {@code < 0} + * @throws UnsupportedOperationException if {@code dstSegment} is {@linkplain #isReadOnly() read-only} */ @ForceInline static void copy(MemorySegment srcSegment, long srcOffset, @@ -1324,25 +1326,25 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param dstElementLayout the element layout associated with the destination segment. * @param dstOffset the starting offset, in bytes, of the destination segment. * @param elementCount the number of elements to be copied. - * @throws IllegalArgumentException if the element layouts have different sizes, if the source (resp. destination) segment/offset are - * incompatible with the alignment constraint in the source - * (resp. destination) element layout. - * @throws IllegalArgumentException if {@code srcElementLayout.byteAlignment() > srcElementLayout.byteSize()}. - * @throws IllegalArgumentException if {@code dstElementLayout.byteAlignment() > dstElementLayout.byteSize()}. + * @throws IllegalArgumentException if the element layouts have different sizes, if the source (resp. destination) + * segment/offset are incompatible with the + * alignment constraint in the source (resp. destination) element layout + * @throws IllegalArgumentException if {@code srcElementLayout.byteAlignment() > srcElementLayout.byteSize()} + * @throws IllegalArgumentException if {@code dstElementLayout.byteAlignment() > dstElementLayout.byteSize()} * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code srcSegment} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive}. * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code srcSegment.isAccessibleBy(T) == false}. + * such that {@code srcSegment.isAccessibleBy(T) == false} * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code dstSegment} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code dstSegment.isAccessibleBy(T) == false}. - * @throws UnsupportedOperationException if {@code dstSegment} is {@linkplain #isReadOnly() read-only}. - * @throws IndexOutOfBoundsException if {@code elementCount * srcLayout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code elementCount * dtsLayout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code srcOffset > srcSegment.byteSize() - (elementCount * srcLayout.byteSize())}. - * @throws IndexOutOfBoundsException if {@code dstOffset > dstSegment.byteSize() - (elementCount * dstLayout.byteSize())}. - * @throws IndexOutOfBoundsException if either {@code srcOffset}, {@code dstOffset} or {@code elementCount} are {@code < 0}. + * such that {@code dstSegment.isAccessibleBy(T) == false} + * @throws UnsupportedOperationException if {@code dstSegment} is {@linkplain #isReadOnly() read-only} + * @throws IndexOutOfBoundsException if {@code elementCount * srcLayout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code elementCount * dtsLayout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code srcOffset > srcSegment.byteSize() - (elementCount * srcLayout.byteSize())} + * @throws IndexOutOfBoundsException if {@code dstOffset > dstSegment.byteSize() - (elementCount * dstLayout.byteSize())} + * @throws IndexOutOfBoundsException if either {@code srcOffset}, {@code dstOffset} or {@code elementCount} are {@code < 0} */ @ForceInline static void copy(MemorySegment srcSegment, ValueLayout srcElementLayout, long srcOffset, @@ -1362,12 +1364,12 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return a byte value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive}. * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false}. * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} */ byte get(ValueLayout.OfByte layout, long offset); @@ -1378,13 +1380,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @param value the byte value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void set(ValueLayout.OfByte layout, long offset, byte value); @@ -1395,12 +1397,12 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return a boolean value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} */ boolean get(ValueLayout.OfBoolean layout, long offset); @@ -1415,9 +1417,9 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @throws WrongThreadException if this method is called from a thread {@code T}, * such that {@code isAccessibleBy(T) == false}. * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void set(ValueLayout.OfBoolean layout, long offset, boolean value); @@ -1428,12 +1430,12 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return a char value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} */ char get(ValueLayout.OfChar layout, long offset); @@ -1444,13 +1446,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @param value the char value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void set(ValueLayout.OfChar layout, long offset, char value); @@ -1461,12 +1463,12 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return a short value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} */ short get(ValueLayout.OfShort layout, long offset); @@ -1477,13 +1479,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @param value the short value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void set(ValueLayout.OfShort layout, long offset, short value); @@ -1494,12 +1496,12 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return an int value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} */ int get(ValueLayout.OfInt layout, long offset); @@ -1510,13 +1512,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @param value the int value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void set(ValueLayout.OfInt layout, long offset, int value); @@ -1527,12 +1529,12 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return a float value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} */ float get(ValueLayout.OfFloat layout, long offset); @@ -1543,13 +1545,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @param value the float value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void set(ValueLayout.OfFloat layout, long offset, float value); @@ -1560,12 +1562,12 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return a long value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} */ long get(ValueLayout.OfLong layout, long offset); @@ -1576,13 +1578,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @param value the long value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void set(ValueLayout.OfLong layout, long offset, long value); @@ -1593,12 +1595,12 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return a double value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} */ double get(ValueLayout.OfDouble layout, long offset); @@ -1609,13 +1611,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @param value the double value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void set(ValueLayout.OfDouble layout, long offset, double value); @@ -1629,15 +1631,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @return a native segment wrapping an address read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. + * incompatible with the alignment constraint in the provided layout * @throws IllegalArgumentException if provided address layout has a {@linkplain AddressLayout#targetLayout() target layout} - * {@code T}, and the address of the returned segment - * incompatible with the alignment constraint in {@code T}. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. + * {@code T}, and the address of the returned segment + * incompatible with the alignment constraint in {@code T} + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} */ MemorySegment get(AddressLayout layout, long offset); @@ -1648,14 +1650,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param offset offset in bytes (relative to this segment address) at which this access operation will occur. * @param value the address value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. - * @throws UnsupportedOperationException if {@code value} is not a {@linkplain #isNative() native} segment. + * incompatible with the alignment constraint in the provided layout. + * @throws IndexOutOfBoundsException if {@code offset > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} + * @throws UnsupportedOperationException if {@code value} is not a {@linkplain #isNative() native} segment */ void set(AddressLayout layout, long offset, MemorySegment value); @@ -1667,14 +1669,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @return a byte value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} */ byte getAtIndex(ValueLayout.OfByte layout, long index); @@ -1686,14 +1688,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @return a boolean value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} */ boolean getAtIndex(ValueLayout.OfBoolean layout, long index); @@ -1705,14 +1707,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @return a char value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} */ char getAtIndex(ValueLayout.OfChar layout, long index); @@ -1724,15 +1726,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @param value the char value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void setAtIndex(ValueLayout.OfChar layout, long index, char value); @@ -1744,14 +1746,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @return a short value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} */ short getAtIndex(ValueLayout.OfShort layout, long index); @@ -1763,15 +1765,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @param value the short value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void setAtIndex(ValueLayout.OfByte layout, long index, byte value); @@ -1783,15 +1785,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @param value the short value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void setAtIndex(ValueLayout.OfBoolean layout, long index, boolean value); @@ -1803,15 +1805,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @param value the short value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void setAtIndex(ValueLayout.OfShort layout, long index, short value); @@ -1823,14 +1825,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @return an int value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} */ int getAtIndex(ValueLayout.OfInt layout, long index); @@ -1842,15 +1844,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @param value the int value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void setAtIndex(ValueLayout.OfInt layout, long index, int value); @@ -1862,14 +1864,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @return a float value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} */ float getAtIndex(ValueLayout.OfFloat layout, long index); @@ -1881,15 +1883,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @param value the float value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void setAtIndex(ValueLayout.OfFloat layout, long index, float value); @@ -1901,14 +1903,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @return a long value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} */ long getAtIndex(ValueLayout.OfLong layout, long index); @@ -1920,15 +1922,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @param value the long value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void setAtIndex(ValueLayout.OfLong layout, long index, long value); @@ -1940,14 +1942,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @return a double value read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} */ double getAtIndex(ValueLayout.OfDouble layout, long index); @@ -1959,15 +1961,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @param value the double value to be written. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. - * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only}. + * incompatible with the alignment constraint in the provided layout + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} + * @throws UnsupportedOperationException if this segment is {@linkplain #isReadOnly() read-only} */ void setAtIndex(ValueLayout.OfDouble layout, long index, double value); @@ -1982,17 +1984,17 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * will occur can be expressed as {@code (index * layout.byteSize())}. * @return a native segment wrapping an address read from this segment. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code isAccessibleBy(T) == false}. + * such that {@code isAccessibleBy(T) == false} * @throws IllegalArgumentException if the access operation is - * incompatible with the alignment constraint in the provided layout. - * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()}. + * incompatible with the alignment constraint in the provided layout. + * @throws IllegalArgumentException if {@code layout.byteAlignment() > layout.byteSize()} * @throws IllegalArgumentException if provided address layout has a {@linkplain AddressLayout#targetLayout() target layout} - * {@code T}, and the address of the returned segment - * incompatible with the alignment constraint in {@code T}. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()}. + * {@code T}, and the address of the returned segment + * incompatible with the alignment constraint in {@code T} + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code index * layout.byteSize() > byteSize() - layout.byteSize()} */ MemorySegment getAtIndex(AddressLayout layout, long index); @@ -2061,18 +2063,18 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param dstIndex the starting index of the destination array. * @param elementCount the number of array elements to be copied. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code srcSegment} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code srcSegment.isAccessibleBy(T) == false}. - * @throws IllegalArgumentException if {@code dstArray} is not an array, or if it is an array but whose type is not supported. - * @throws IllegalArgumentException if the destination array component type does not match {@code srcLayout.carrier()}. + * such that {@code srcSegment.isAccessibleBy(T) == false} + * @throws IllegalArgumentException if {@code dstArray} is not an array, or if it is an array but whose type is not supported + * @throws IllegalArgumentException if the destination array component type does not match {@code srcLayout.carrier()} * @throws IllegalArgumentException if {@code offset} is incompatible - * with the alignment constraint in the source element layout. - * @throws IllegalArgumentException if {@code srcLayout.byteAlignment() > srcLayout.byteSize()}. - * @throws IndexOutOfBoundsException if {@code elementCount * srcLayout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code srcOffset > srcSegment.byteSize() - (elementCount * srcLayout.byteSize())}. - * @throws IndexOutOfBoundsException if {@code dstIndex > dstArray.length - elementCount}. - * @throws IndexOutOfBoundsException if either {@code srcOffset}, {@code dstIndex} or {@code elementCount} are {@code < 0}. + * with the alignment constraint in the source element layout + * @throws IllegalArgumentException if {@code srcLayout.byteAlignment() > srcLayout.byteSize()} + * @throws IndexOutOfBoundsException if {@code elementCount * srcLayout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code srcOffset > srcSegment.byteSize() - (elementCount * srcLayout.byteSize())} + * @throws IndexOutOfBoundsException if {@code dstIndex > dstArray.length - elementCount} + * @throws IndexOutOfBoundsException if either {@code srcOffset}, {@code dstIndex} or {@code elementCount} are {@code < 0} */ @ForceInline static void copy( @@ -2100,19 +2102,19 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @param dstOffset the starting offset, in bytes, of the destination segment. * @param elementCount the number of array elements to be copied. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code dstSegment} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code dstSegment.isAccessibleBy(T) == false}. - * @throws IllegalArgumentException if {@code srcArray} is not an array, or if it is an array but whose type is not supported. - * @throws IllegalArgumentException if the source array component type does not match {@code srcLayout.carrier()}. + * such that {@code dstSegment.isAccessibleBy(T) == false} + * @throws IllegalArgumentException if {@code srcArray} is not an array, or if it is an array but whose type is not supported + * @throws IllegalArgumentException if the source array component type does not match {@code srcLayout.carrier()} * @throws IllegalArgumentException if {@code offset} is incompatible - * with the alignment constraint in the source element layout. - * @throws IllegalArgumentException if {@code dstLayout.byteAlignment() > dstLayout.byteSize()}. - * @throws UnsupportedOperationException if {@code dstSegment} is {@linkplain #isReadOnly() read-only}. - * @throws IndexOutOfBoundsException if {@code elementCount * dstLayout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code dstOffset > dstSegment.byteSize() - (elementCount * dstLayout.byteSize())}. - * @throws IndexOutOfBoundsException if {@code srcIndex > srcArray.length - elementCount}. - * @throws IndexOutOfBoundsException if either {@code srcIndex}, {@code dstOffset} or {@code elementCount} are {@code < 0}. + * with the alignment constraint in the source element layout + * @throws IllegalArgumentException if {@code dstLayout.byteAlignment() > dstLayout.byteSize()} + * @throws UnsupportedOperationException if {@code dstSegment} is {@linkplain #isReadOnly() read-only} + * @throws IndexOutOfBoundsException if {@code elementCount * dstLayout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code dstOffset > dstSegment.byteSize() - (elementCount * dstLayout.byteSize())} + * @throws IndexOutOfBoundsException if {@code srcIndex > srcArray.length - elementCount} + * @throws IndexOutOfBoundsException if either {@code srcIndex}, {@code dstOffset} or {@code elementCount} are {@code < 0} */ @ForceInline static void copy( @@ -2148,17 +2150,17 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * @return the relative offset, in bytes, of the first mismatch between the source and destination segments, * otherwise -1 if no mismatch. * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code srcSegment} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code srcSegment.isAccessibleBy(T) == false}. + * such that {@code srcSegment.isAccessibleBy(T) == false} * @throws IllegalStateException if the {@linkplain #scope() scope} associated with {@code dstSegment} is not - * {@linkplain Scope#isAlive() alive}. + * {@linkplain Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code dstSegment.isAccessibleBy(T) == false}. + * such that {@code dstSegment.isAccessibleBy(T) == false} * @throws IndexOutOfBoundsException if {@code srcFromOffset < 0}, {@code srcToOffset < srcFromOffset} or - * {@code srcToOffset > srcSegment.byteSize()} + * {@code srcToOffset > srcSegment.byteSize()} * @throws IndexOutOfBoundsException if {@code dstFromOffset < 0}, {@code dstToOffset < dstFromOffset} or - * {@code dstToOffset > dstSegment.byteSize()} + * {@code dstToOffset > dstSegment.byteSize()} * * @see MemorySegment#mismatch(MemorySegment) * @see Arrays#mismatch(Object[], int, int, Object[], int, int) diff --git a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java index fc74c78436b..0c73f9b904c 100644 --- a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java +++ b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java @@ -109,7 +109,7 @@ public interface SegmentAllocator { * @param str the Java string to be converted into a C string. * @param charset the charset used to {@linkplain Charset#newEncoder() encode} the string bytes. * @return a new native segment containing the converted C string. - * @throws IllegalArgumentException if {@code charset} is not a {@linkplain StandardCharsets standard charset}. + * @throws IllegalArgumentException if {@code charset} is not a {@linkplain StandardCharsets standard charset} * @implSpec The default implementation for this method copies the contents of the provided Java string * into a new memory segment obtained by calling {@code this.allocate(B + N)}, where: *
    @@ -329,7 +329,7 @@ public interface SegmentAllocator { * * @param layout the layout of the block of memory to be allocated. * @param value the value to be set in the newly allocated memory segment. - * @throws UnsupportedOperationException if {@code value} is not a {@linkplain MemorySegment#isNative() native} segment. + * @throws UnsupportedOperationException if {@code value} is not a {@linkplain MemorySegment#isNative() native} segment */ default MemorySegment allocateFrom(AddressLayout layout, MemorySegment value) { Objects.requireNonNull(value); @@ -357,18 +357,19 @@ public interface SegmentAllocator { * @param sourceElementLayout the element layout of the source segment. * @param sourceOffset the starting offset, in bytes, of the source segment. * @param elementCount the number of elements in the source segment to be copied. - * @throws IllegalArgumentException if {@code elementLayout.byteSize() != sourceElementLayout.byteSize()}. - * @throws IllegalArgumentException if the source segment/offset are incompatible with the alignment constraint - * in the source element layout. - * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()}. - * @throws IllegalArgumentException if {@code sourceElementLayout.byteAlignment() > sourceElementLayout.byteSize()}. + * @throws IllegalArgumentException if {@code elementLayout.byteSize() != sourceElementLayout.byteSize()} + * @throws IllegalArgumentException if the source segment/offset + * are incompatible with the alignment constraint + * in the source element layout. + * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()} + * @throws IllegalArgumentException if {@code sourceElementLayout.byteAlignment() > sourceElementLayout.byteSize()} * @throws IllegalStateException if the {@linkplain MemorySegment#scope() scope} associated with {@code source} is not - * {@linkplain MemorySegment.Scope#isAlive() alive}. + * {@linkplain MemorySegment.Scope#isAlive() alive} * @throws WrongThreadException if this method is called from a thread {@code T}, - * such that {@code source.isAccessibleBy(T) == false}. - * @throws IndexOutOfBoundsException if {@code elementCount * sourceElementLayout.byteSize()} overflows. - * @throws IndexOutOfBoundsException if {@code sourceOffset > source.byteSize() - (elementCount * sourceElementLayout.byteSize())}. - * @throws IndexOutOfBoundsException if either {@code sourceOffset} or {@code elementCount} are {@code < 0}. + * such that {@code source.isAccessibleBy(T) == false} + * @throws IndexOutOfBoundsException if {@code elementCount * sourceElementLayout.byteSize()} overflows + * @throws IndexOutOfBoundsException if {@code sourceOffset > source.byteSize() - (elementCount * sourceElementLayout.byteSize())} + * @throws IndexOutOfBoundsException if either {@code sourceOffset} or {@code elementCount} are {@code < 0} */ @ForceInline default MemorySegment allocateFrom(ValueLayout elementLayout, MemorySegment source, @@ -395,7 +396,7 @@ public interface SegmentAllocator { *} * @param elementLayout the element layout of the array to be allocated. * @param elements the byte elements to be copied to the newly allocated memory block. - * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()}. + * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()} */ @ForceInline default MemorySegment allocateFrom(ValueLayout.OfByte elementLayout, byte... elements) { @@ -417,7 +418,7 @@ public interface SegmentAllocator { *} * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. - * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()}. + * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()} */ @ForceInline default MemorySegment allocateFrom(ValueLayout.OfShort elementLayout, short... elements) { @@ -439,7 +440,7 @@ public interface SegmentAllocator { *} * @param elementLayout the element layout of the array to be allocated. * @param elements the char elements to be copied to the newly allocated memory block. - * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()}. + * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()} */ @ForceInline default MemorySegment allocateFrom(ValueLayout.OfChar elementLayout, char... elements) { @@ -461,7 +462,7 @@ public interface SegmentAllocator { *} * @param elementLayout the element layout of the array to be allocated. * @param elements the int elements to be copied to the newly allocated memory block. - * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()}. + * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()} */ @ForceInline default MemorySegment allocateFrom(ValueLayout.OfInt elementLayout, int... elements) { @@ -483,7 +484,7 @@ public interface SegmentAllocator { *} * @param elementLayout the element layout of the array to be allocated. * @param elements the float elements to be copied to the newly allocated memory block. - * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()}. + * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()} */ @ForceInline default MemorySegment allocateFrom(ValueLayout.OfFloat elementLayout, float... elements) { @@ -505,7 +506,7 @@ public interface SegmentAllocator { *} * @param elementLayout the element layout of the array to be allocated. * @param elements the long elements to be copied to the newly allocated memory block. - * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()}. + * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()} */ @ForceInline default MemorySegment allocateFrom(ValueLayout.OfLong elementLayout, long... elements) { @@ -527,7 +528,7 @@ public interface SegmentAllocator { *} * @param elementLayout the element layout of the array to be allocated. * @param elements the double elements to be copied to the newly allocated memory block. - * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()}. + * @throws IllegalArgumentException if {@code elementLayout.byteAlignment() > elementLayout.byteSize()} */ @ForceInline default MemorySegment allocateFrom(ValueLayout.OfDouble elementLayout, double... elements) { @@ -556,8 +557,8 @@ public interface SegmentAllocator { * * @param elementLayout the array element layout. * @param count the array element count. - * @throws IllegalArgumentException if {@code elementLayout.byteSize() * count} overflows. - * @throws IllegalArgumentException if {@code count < 0}. + * @throws IllegalArgumentException if {@code elementLayout.byteSize() * count} overflows + * @throws IllegalArgumentException if {@code count < 0} */ default MemorySegment allocate(MemoryLayout elementLayout, long count) { Objects.requireNonNull(elementLayout); @@ -586,7 +587,7 @@ public interface SegmentAllocator { * @param byteSize the size (in bytes) of the block of memory to be allocated. * @param byteAlignment the alignment (in bytes) of the block of memory to be allocated. * @throws IllegalArgumentException if {@code byteSize < 0}, {@code byteAlignment <= 0}, - * or if {@code byteAlignment} is not a power of 2. + * or if {@code byteAlignment} is not a power of 2 */ MemorySegment allocate(long byteSize, long byteAlignment); diff --git a/src/java.base/share/classes/java/lang/foreign/SequenceLayout.java b/src/java.base/share/classes/java/lang/foreign/SequenceLayout.java index 16384f4ac6c..953d1cd0278 100644 --- a/src/java.base/share/classes/java/lang/foreign/SequenceLayout.java +++ b/src/java.base/share/classes/java/lang/foreign/SequenceLayout.java @@ -67,8 +67,8 @@ public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayo /** * {@return a sequence layout with the same characteristics of this layout, but with the given element count} * @param elementCount the new element count. - * @throws IllegalArgumentException if {@code elementCount} is negative. - * @throws IllegalArgumentException if {@code elementLayout.bitSize() * elementCount} overflows. + * @throws IllegalArgumentException if {@code elementCount} is negative + * @throws IllegalArgumentException if {@code elementLayout.bitSize() * elementCount} overflows */ SequenceLayout withElementCount(long elementCount); @@ -101,9 +101,9 @@ public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayo * @return a sequence layout where element layouts in the {@linkplain #flatten() flattened projection} of this * sequence layout (see {@link #flatten()}) are re-arranged into one or more nested sequence layouts. * @throws IllegalArgumentException if two or more element counts are set to {@code -1}, or if one - * or more element count is {@code <= 0} (but other than {@code -1}) or, if, after any required inference, - * multiplying the element counts does not yield the same element count as the flattened projection of this - * sequence layout. + * or more element count is {@code <= 0} (but other than {@code -1}) or, if, after any required inference, + * multiplying the element counts does not yield the same element count as the flattened projection of this + * sequence layout */ SequenceLayout reshape(long... elementCounts); @@ -149,7 +149,7 @@ public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayo /** * {@inheritDoc} * @throws IllegalArgumentException {@inheritDoc} - * @throws IllegalArgumentException if {@code byteAlignment < elementLayout().byteAlignment()}. + * @throws IllegalArgumentException if {@code byteAlignment < elementLayout().byteAlignment()} */ SequenceLayout withByteAlignment(long byteAlignment); } diff --git a/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java b/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java index efab47a40f2..96e78bb1d58 100644 --- a/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java +++ b/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java @@ -221,9 +221,9 @@ public interface SymbolLookup { * @return a new symbol lookup suitable to find symbols in a library with the given name. * @throws IllegalStateException if {@code arena.scope().isAlive() == false} * @throws WrongThreadException if {@code arena} is a confined arena, and this method is called from a - * thread {@code T}, other than the arena's owner thread. - * @throws IllegalArgumentException if {@code name} does not identify a valid library. - * @throws IllegalCallerException If the caller is in a module that does not have native access enabled. + * thread {@code T}, other than the arena's owner thread + * @throws IllegalArgumentException if {@code name} does not identify a valid library + * @throws IllegalCallerException If the caller is in a module that does not have native access enabled */ @CallerSensitive @Restricted @@ -249,9 +249,9 @@ public interface SymbolLookup { * @return a new symbol lookup suitable to find symbols in a library with the given path. * @throws IllegalStateException if {@code arena.scope().isAlive() == false} * @throws WrongThreadException if {@code arena} is a confined arena, and this method is called from a - * thread {@code T}, other than the arena's owner thread. - * @throws IllegalArgumentException if {@code path} does not point to a valid library. - * @throws IllegalCallerException If the caller is in a module that does not have native access enabled. + * thread {@code T}, other than the arena's owner thread + * @throws IllegalArgumentException if {@code path} does not point to a valid library + * @throws IllegalCallerException If the caller is in a module that does not have native access enabled */ @CallerSensitive @Restricted