8319323: FFM: Harmonize the @throws tags in the javadocs

Reviewed-by: jvernee
This commit is contained in:
Per Minborg 2023-11-03 12:26:47 +00:00
parent ec79ab4b3c
commit be01caf30d
10 changed files with 454 additions and 451 deletions

@ -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

@ -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();

@ -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) {

@ -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);

@ -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) {

@ -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 <a href="#well-formedness">well-formed</a> for this layout.
* @throws IllegalArgumentException if the layout path contains one or more <a href=#open-path-elements>open path elements</a>.
* @throws IllegalArgumentException if the layout path contains one or more <a href=#deref-path-elements>dereference path elements</a>.
* @throws IllegalArgumentException if the layout path is not <a href="#well-formedness">well-formed</a> for this layout
* @throws IllegalArgumentException if the layout path contains one or more <a href=#open-path-elements>open path elements</a>
* @throws IllegalArgumentException if the layout path contains one or more <a href=#deref-path-elements>dereference path elements</a>
*/
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 <a href="#well-formedness">well-formed</a> for this layout.
* @throws IllegalArgumentException if the layout path contains one or more <a href=#deref-path-elements>dereference path elements</a>.
* @throws IllegalArgumentException if the layout path is not <a href="#well-formedness">well-formed</a> for this layout
* @throws IllegalArgumentException if the layout path contains one or more <a href=#deref-path-elements>dereference path elements</a>
*/
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 <a href="#well-formedness">well-formed</a> 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 <a href="#well-formedness">well-formed</a> 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 <a href="#well-formedness">well-formed</a> 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 <a href="#well-formedness">well-formed</a> 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 <a href="#well-formedness">well-formed</a> for this layout.
* @throws IllegalArgumentException if the layout path contains one or more <a href=#deref-path-elements>dereference path elements</a>.
* @throws IllegalArgumentException if the layout path is not <a href="#well-formedness">well-formed</a> for this layout
* @throws IllegalArgumentException if the layout path contains one or more <a href=#deref-path-elements>dereference path elements</a>
*/
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 <a href="#well-formedness">well-formed</a> for this layout.
* @throws IllegalArgumentException if the layout path contains one or more <a href=#deref-path-elements>dereference path elements</a>.
* @throws IllegalArgumentException if the layout path is not <a href="#well-formedness">well-formed</a> for this layout
* @throws IllegalArgumentException if the layout path contains one or more <a href=#deref-path-elements>dereference path elements</a>
* @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:

File diff suppressed because it is too large Load Diff

@ -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:
* <ul>
@ -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 <a href="MemorySegment.html#segment-alignment">incompatible with the alignment constraint</a>
* 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 <a href="MemorySegment.html#segment-alignment">incompatible with the alignment constraint</a>
* 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);

@ -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);
}

@ -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