Skip to content

Commit

Permalink
8319323: FFM: Harmonize the @throws tags in the javadocs
Browse files Browse the repository at this point in the history
Reviewed-by: jvernee
  • Loading branch information
minborg committed Nov 3, 2023
1 parent ec79ab4 commit be01caf
Show file tree
Hide file tree
Showing 10 changed files with 454 additions and 451 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 8 additions & 8 deletions src/java.base/share/classes/java/lang/foreign/Arena.java
Original file line number Diff line number Diff line change
Expand Up @@ -260,11 +260,11 @@ static Arena ofShared() {
* @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);
Expand All @@ -289,12 +289,12 @@ static Arena ofShared() {
*
* @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();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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);
Expand Down Expand Up @@ -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) {
Expand All @@ -124,7 +124,7 @@ static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argLayouts)
* 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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
26 changes: 13 additions & 13 deletions src/java.base/share/classes/java/lang/foreign/Linker.java
Original file line number Diff line number Diff line change
Expand Up @@ -525,10 +525,10 @@ static Linker nativeLinker() {
* @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
*/
Expand Down Expand Up @@ -575,9 +575,9 @@ static Linker nativeLinker() {
* @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
Expand Down Expand Up @@ -610,14 +610,14 @@ static Linker nativeLinker() {
* @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
Expand Down Expand Up @@ -726,7 +726,7 @@ static Option firstVariadicArg(int index) {
*
* @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) {
Expand Down

1 comment on commit be01caf

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.