stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8280592: Small javadoc tweaks to foreign API

Browse Source 
Reviewed-by: psandoz
This commit is contained in:
Maurizio Cimadamore 2022-01-26 01:12:37 +00:00
parent ead9feccae
commit ef08e2c63b
12 changed files with 49 additions and 91 deletions

3
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/Addressable.java

@ -40,8 +40,7 @@ package jdk.incubator.foreign;
public sealed interface Addressable permits MemorySegment, MemoryAddress, NativeSymbol, VaList {
/**
* Returns the memory address associated with this addressable.
* @return The memory address associated with this addressable.
* {@return the {@linkplain MemoryAddress memory address} associated with this addressable}
*/
MemoryAddress address();
}

12
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/FunctionDescriptor.java

@ -54,16 +54,14 @@ public sealed class FunctionDescriptor implements Constable permits FunctionDesc
}
/**
* Returns the return layout associated with this function.
* @return the return layout.
* {@return the return layout (if any) associated with this function descriptor}
*/
public Optional<MemoryLayout> returnLayout() {
return Optional.ofNullable(resLayout);
}
/**
* Returns the argument layouts associated with this function.
* @return the argument layouts.
* {@return the argument layouts associated with this function descriptor}.
*/
public List<MemoryLayout> argumentLayouts() {
return argLayouts;
@ -166,8 +164,7 @@ public sealed class FunctionDescriptor implements Constable permits FunctionDesc
}
/**
* Returns a string representation of this function descriptor.
* @return a string representation of this function descriptor.
* {@return the string representation of this function descriptor}
*/
@Override
public String toString() {
@ -201,8 +198,7 @@ public sealed class FunctionDescriptor implements Constable permits FunctionDesc
}
/**
* Returns the hash code value for this function descriptor.
* @return the hash code value for this function descriptor.
* {@return the hash code value for this function descriptor}
*/
@Override
public int hashCode() {

8
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java

@ -133,18 +133,14 @@ public final class GroupLayout extends AbstractLayout implements MemoryLayout {
}
/**
* Is this group layout a <em>struct</em>?
*
* @return true, if this group layout is a <em>struct</em>.
* {@return {@code true}, if this group layout is a <em>struct</em>}
*/
public boolean isStruct() {
return kind == Kind.STRUCT;
}
/**
* Is this group layout a <em>union</em>?
*
* @return true, if this group layout is a <em>union</em>.
* {@return {@code true}, if this group layout is a <em>union</em>}
*/
public boolean isUnion() {
return kind == Kind.UNION;

6
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java

@ -78,8 +78,7 @@ import java.nio.ByteOrder;
public sealed interface MemoryAddress extends Addressable permits MemoryAddressImpl {
/**
* Returns the raw long value associated with this memory address.
* @return The raw long value associated with this memory address.
* {@return the raw long value associated with this memory address}
*/
long toRawLongValue();
@ -141,8 +140,7 @@ public sealed interface MemoryAddress extends Addressable permits MemoryAddressI
boolean equals(Object that);
/**
* Returns the hash code value for this address.
* @return the hash code value for this address.
* {@return the hash code value for this address}
*/
@Override
int hashCode();

32
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java

@ -195,18 +195,15 @@ import java.util.stream.Stream;
public sealed interface MemoryLayout extends Constable permits AbstractLayout, SequenceLayout, GroupLayout, PaddingLayout, ValueLayout {
/**
* Returns an {@link Optional} containing the nominal descriptor for this
* {@return an {@link Optional} containing the nominal descriptor for this
* layout, if one can be constructed, or an empty {@link Optional}
* if one cannot be constructed.
*
* @return An {@link Optional} containing the resulting nominal descriptor,
* or an empty {@link Optional} if one cannot be constructed.
* if one cannot be constructed}
*/
@Override
Optional<? extends DynamicConstantDesc<? extends MemoryLayout>> describeConstable();
/**
* Does this layout have a specified size? A layout does not have a specified size if it is (or contains) a sequence layout whose
* Returns {@code true} if this layout has a specified size. A layout does not have a specified size if it is (or contains) a sequence layout whose
* size is unspecified (see {@link SequenceLayout#elementCount()}).
*
* Value layouts (see {@link ValueLayout}) and padding layouts (see {@link MemoryLayout#paddingLayout(long)})
@ -217,26 +214,20 @@ public sealed interface MemoryLayout extends Constable permits AbstractLayout, S
boolean hasSize();
/**
* Computes the layout size, in bits.
*
* @return the layout size, in bits.
* {@return the layout size, in bits}
* @throws UnsupportedOperationException if the layout is, or contains, a sequence layout with unspecified size (see {@link SequenceLayout}).
*/
long bitSize();
/**
* Computes the layout size, in bytes.
*
* @return the layout size, in bytes.
* {@return the layout size, in bytes}
* @throws UnsupportedOperationException if the layout is, or contains, a sequence layout with unspecified size (see {@link SequenceLayout}),
* or if {@code bitSize()} is not a multiple of 8.
*/
long byteSize();
/**
* Return the <em>name</em> (if any) associated with this layout.
*
* @return the layout <em>name</em> (if any).
* {@return the <em>name</em> (if any) associated with this layout}
* @see MemoryLayout#withName(String)
*/
Optional<String> name();
@ -534,8 +525,7 @@ public sealed interface MemoryLayout extends Constable permits AbstractLayout, S
}
/**
* Is this a {@linkplain #paddingLayout(long) padding layout} ?
* @return true, if this layout is a padding layout.
* {@return true, if this layout is a padding layout}
*/
boolean isPadding();
@ -651,16 +641,12 @@ public sealed interface MemoryLayout extends Constable permits AbstractLayout, S
boolean equals(Object that);
/**
* Returns the hash code value for this layout.
*
* @return the hash code value for this layout.
* {@return the hash code value for this layout}
*/
int hashCode();
/**
* Returns a string representation of this layout.
*
* @return a string representation of this layout.
* {@return the string representation of this layout}
*/
@Override
String toString();

18
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java

@ -250,11 +250,10 @@ boolean isAligned(MemorySegment segment, long offset, MemoryLayout layout) {
public sealed interface MemorySegment extends Addressable permits AbstractMemorySegmentImpl {
/**
* The base memory address associated with this native memory segment.
* {@return the base memory address associated with this native memory segment}
* @throws UnsupportedOperationException if this segment is not a {@linkplain #isNative() native} segment.
* @throws IllegalStateException if the scope associated with this segment has been closed, or if access occurs from
* a thread other than the thread owning that scope.
* @return The base memory address.
*/
@Override
MemoryAddress address();
@ -299,14 +298,12 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
Stream<MemorySegment> elements(MemoryLayout elementLayout);
/**
* Returns the resource scope associated with this memory segment.
* @return the resource scope associated with this memory segment.
* {@return the resource scope associated with this memory segment}
*/
ResourceScope scope();
/**
* The size (in bytes) of this memory segment.
* @return The size (in bytes) of this memory segment.
* {@return the size (in bytes) of this memory segment}
*/
long byteSize();
@ -343,8 +340,7 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
}
/**
* Is this segment read-only?
* @return {@code true}, if this segment is read-only.
* {@return {@code true}, if this segment is read-only}
* @see #asReadOnly()
*/
boolean isReadOnly();
@ -358,7 +354,7 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
MemorySegment asReadOnly();
/**
* Is this a native segment? Returns true if this segment is a native memory segment,
* Returns {@code true} if this segment is a native segment. A native memory segment is
* created using the {@link #allocateNative(long, ResourceScope)} (and related) factory, or a buffer segment
* derived from a direct {@link java.nio.ByteBuffer} using the {@link #ofByteBuffer(ByteBuffer)} factory,
* or if this is a {@linkplain #isMapped() mapped} segment.
@ -367,7 +363,7 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
boolean isNative();
/**
* Is this a mapped segment? Returns true if this segment is a mapped memory segment,
* Returns {@code true} if this segment is a mapped segment. A mapped memory segment is
* created using the {@link #mapFile(Path, long, long, FileChannel.MapMode, ResourceScope)} factory, or a buffer segment
* derived from a {@link java.nio.MappedByteBuffer} using the {@link #ofByteBuffer(ByteBuffer)} factory.
* @return {@code true} if this segment is a mapped segment.
@ -484,7 +480,7 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
long mismatch(MemorySegment other);
/**
* Tells whether the contents of this mapped segment is resident in physical
* Determines whether the contents of this mapped segment is resident in physical
* memory.
*
* <p> A return value of {@code true} implies that it is highly likely

9
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/NativeSymbol.java

@ -43,22 +43,19 @@ import java.util.Objects;
sealed public interface NativeSymbol extends Addressable permits NativeSymbolImpl {
/**
* Returns the name of this symbol.
* @return the name of this symbol.
* {@return the name of this symbol}
*/
String name();
/**
* Returns the resource scope associated with this symbol.
* @return the resource scope associated with this symbol.
* {@return the resource scope associated with this symbol}
*/
ResourceScope scope();
/**
* Returns the memory address associated with this symbol.
* {@return the memory address associated with this symbol}
* @throws IllegalStateException if the scope associated with this symbol has been closed, or if access occurs from
* a thread other than the thread owning that scope.
* @return The memory address associated with this symbol.
*/
@Override
MemoryAddress address();

3
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ResourceScope.java

@ -147,8 +147,7 @@ import java.util.Spliterator;
*/
public sealed interface ResourceScope extends AutoCloseable permits ResourceScopeImpl {
/**
* Is this resource scope alive?
* @return true, if this resource scope is alive.
* {@return {@code true}, if this resource scope is alive}
* @see ResourceScope#close()
*/
boolean isAlive();

8
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java

@ -82,18 +82,14 @@ public final class SequenceLayout extends AbstractLayout implements MemoryLayout
}
/**
* Returns the element layout associated with this sequence layout.
*
* @return The element layout associated with this sequence layout.
* {@return the element layout associated with this sequence layout}
*/
public MemoryLayout elementLayout() {
return elementLayout;
}
/**
* Returns the element count of this sequence layout (if any).
*
* @return the element count of this sequence layout (if any).
* {@return the element count of this sequence layout (if any)}
*/
public OptionalLong elementCount() {
return elemCount;

6
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/VaList.java

@ -132,8 +132,7 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
void skip(MemoryLayout... layouts);
/**
* Returns the resource scope associated with this variable argument list.
* @return the resource scope associated with this variable argument list.
* {@return the resource scope associated with this variable argument list}
*/
ResourceScope scope();
@ -153,10 +152,9 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
VaList copy();
/**
* Returns the memory address associated with this variable argument list.
* {@return the {@linkplain MemoryAddress memory address} associated with this variable argument list}
* @throws IllegalStateException if the scope associated with this variable argument list has been closed, or if access occurs from
* a thread other than the thread owning that scope.
* @return The memory address associated with this variable argument list.
*/
@Override
MemoryAddress address();

33
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java

@ -41,9 +41,9 @@ import java.util.OptionalLong;
/**
* A value layout. A value layout is used to model the memory layout associated with values of basic data types, such as <em>integral</em> types
* (either signed or unsigned) and <em>floating-point</em> types. Each value layout has a size, an alignment, a {@linkplain ByteOrder byte order})
* and a <em>carrier</em>, that is, the Java type that should be used when {@linkplain MemorySegment#get(OfInt, long) accessing}
* a memory region using the value layout.
* (either signed or unsigned) and <em>floating-point</em> types. Each value layout has a size, an alignment (in bits),
* a {@linkplain ByteOrder byte order}, and a <em>carrier</em>, that is, the Java type that should be used when
* {@linkplain MemorySegment#get(OfInt, long) accessing} a memory region using the value layout.
* <p>
* This class defines useful value layout constants for Java primitive types and addresses.
* The layout constants in this class make implicit alignment and byte-ordering assumption: all layout
@ -82,9 +82,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
}
/**
* Returns the value's byte order.
*
* @return the value's byte order.
* {@return the value's byte order}
*/
public ByteOrder order() {
return order;
@ -125,8 +123,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
}
/**
* Returns the carrier associated with this value layout.
* @return the carrier associated with this value layout.
* {@return the carrier associated with this value layout}
*/
public Class<?> carrier() {
return carrier;
@ -513,8 +510,8 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
}
/**
* A value layout constant whose size is the same as that of a machine address (e.g. {@code size_t}),
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* A value layout constant whose size is the same as that of a machine address ({@code size_t}),
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(MemoryAddress.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@ -524,7 +521,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code byte},
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(byte.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@ -534,7 +531,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code boolean},
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(boolean.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@ -544,7 +541,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code char},
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(char.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@ -554,7 +551,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code short},
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(short.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@ -564,7 +561,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code int},
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(int.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@ -574,7 +571,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code long},
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(long.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@ -585,7 +582,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code float},
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(float.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@ -595,7 +592,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code double},
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(double.class, ByteOrder.nativeOrder()).withBitAlignment(8);

2
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java

@ -30,7 +30,7 @@
* <h2>Foreign memory access</h2>
*
* <p>
* The main abstractions introduced to support foreign memory access is {@link jdk.incubator.foreign.MemorySegment}, which
* The main abstraction introduced to support foreign memory access is {@link jdk.incubator.foreign.MemorySegment}, which
* models a contiguous memory region, which can reside either inside or outside the Java heap.
* A memory segment represents the main access coordinate of a memory access var handle, which can be obtained
* using the combinator methods defined in the {@link jdk.incubator.foreign.MemoryHandles} class; a set of