Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files
8278607: Misc issues in foreign API javadoc
Reviewed-by: sundar
  • Loading branch information
mcimadamore committed Dec 15, 2021
1 parent 918e339 commit d6b5544e74d46c1ca464a1994e73ddd323ef5c2b
Showing 7 changed files with 55 additions and 40 deletions.
@@ -55,7 +55,7 @@
* {@linkplain #downcallHandle(FunctionDescriptor) Linking a foreign function} is a process which requires a function descriptor,
* a set of memory layouts which, together, specify the signature of the foreign function to be linked, and returns,
* when complete, a downcall method handle, that is, a method handle that can be used to invoke the target native function.
* The Java {@link java.lang.invoke.MethodType method type} associated with the returned method handle is
* The Java {@linkplain java.lang.invoke.MethodType method type} associated with the returned method handle is
* {@linkplain #downcallType(FunctionDescriptor) derived} from the argument and return layouts in the function descriptor.
* More specifically, given each layout {@code L} in the function descriptor, a corresponding carrier {@code C} is inferred,
* as described below:
@@ -69,7 +69,8 @@
* <li>or, if {@code L} is a {@link GroupLayout}, then {@code C} is set to {@code MemorySegment.class}</li>
* </ul>
* <p>
* The downcall method handle type, derived as above, might be decorated by additional leading parameters:
* The downcall method handle type, derived as above, might be decorated by additional leading parameters,
* in the given order if both are present:
* <ul>
* <li>If the downcall method handle is created {@linkplain #downcallHandle(FunctionDescriptor) without specifying a native symbol},
* the downcall method handle type features a leading parameter of type {@link NativeSymbol}, from which the
@@ -91,7 +92,7 @@
* handle and a function descriptor; in this case, the set of memory layouts in the function descriptor
* specify the signature of the function pointer associated with the upcall stub.
* <p>
* The type of the provided method handle has to match the Java {@link java.lang.invoke.MethodType method type}
* The type of the provided method handle has to match the Java {@linkplain java.lang.invoke.MethodType method type}
* associated with the upcall stub, which is derived from the argument and return layouts in the function descriptor.
* More specifically, given each layout {@code L} in the function descriptor, a corresponding carrier {@code C} is inferred, as described below:
* <ul>
@@ -109,7 +110,7 @@
*
* <h2>System lookup</h2>
*
* This class implements the {@link SymbolLookup} interface; as such clients can {@linkplain #lookup(String) lookup} symbols
* This class implements the {@link SymbolLookup} interface; as such clients can {@linkplain #lookup(String) look up} symbols
* in the standard libraries associated with this linker. The set of symbols available for lookup is unspecified,
* as it depends on the platform and on the operating system.
*
@@ -163,7 +164,7 @@ static CLinker systemCLinker() {
}

/**
* Lookup a symbol in the standard libraries associated with this linker.
* Look up a symbol in the standard libraries associated with this linker.
* The set of symbols available for lookup is unspecified, as it depends on the platform and on the operating system.
* @return a symbol in the standard libraries associated with this linker.
*/
@@ -29,14 +29,16 @@
import jdk.internal.foreign.MemoryAddressImpl;
import jdk.internal.reflect.CallerSensitive;

import java.lang.invoke.MethodHandle;
import java.nio.ByteOrder;

/**
* A memory address models a reference into a memory location. Memory addresses are typically obtained in three ways:
* A memory address models a reference into a memory location. Memory addresses are typically obtained in one of the following ways:
* <ul>
* <li>By calling {@link Addressable#address()} on an instance of type {@link Addressable} (e.g. a memory segment);</li>
* <li>By invoking a {@linkplain CLinker#downcallHandle(FunctionDescriptor) downcall method handle} which returns a pointer;</li>
* <li>By reading an address from memory, e.g. via {@link MemorySegment#get(ValueLayout.OfAddress, long)}.</li>
* <li>By the invocation of an {@linkplain CLinker#upcallStub(MethodHandle, FunctionDescriptor, ResourceScope) upcall stub} which accepts a pointer.
* </ul>
* A memory address is backed by a raw machine pointer, expressed as a {@linkplain #toRawLongValue() long value}.
*
@@ -56,7 +56,7 @@
* A memory segment models a contiguous region of memory. A memory segment is associated with both spatial
* and temporal bounds (e.g. a {@link ResourceScope}). Spatial bounds ensure that memory access operations on a memory segment cannot affect a memory location
* which falls <em>outside</em> the boundaries of the memory segment being accessed. Temporal bounds ensure that memory access
* operations on a segment cannot occur after the resource scope associated with a memory segment has been closed (see {@link ResourceScope#close()}).
* operations on a segment cannot occur <em>after</em> the resource scope associated with a memory segment has been closed (see {@link ResourceScope#close()}).
* <p>
* All implementations of this interface must be <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>;
* programmers should treat instances that are {@linkplain Object#equals(Object) equal} as interchangeable and should not
@@ -157,7 +157,7 @@
* scope, it can only be accessed by the thread which owns the scope.
* <p>
* Heap and buffer segments are always associated with a <em>global</em>, shared scope. This scope cannot be closed,
* and can be considered as <em>always alive</em>.
* and segments associated with it can be considered as <em>always alive</em>.
*
* <h2>Memory segment views</h2>
*
@@ -217,11 +217,11 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
* The returned spliterator splits this segment according to the specified element layout; that is,
* if the supplied layout has size N, then calling {@link Spliterator#trySplit()} will result in a spliterator serving
* approximately {@code S/N/2} elements (depending on whether N is even or not), where {@code S} is the size of
* this segment. As such, splitting is possible as long as {@code S/N >= 2}. The spliterator returns segments that feature the same
* scope as this given segment.
* this segment. As such, splitting is possible as long as {@code S/N >= 2}. The spliterator returns segments that
* are associated with the same scope as this segment.
* <p>
* The returned spliterator effectively allows to slice this segment into disjoint sub-segments, which can then
* be processed in parallel by multiple threads.
* The returned spliterator effectively allows to slice this segment into disjoint {@linkplain #asSlice(long, long) slices},
* which can then be processed in parallel by multiple threads.
*
* @param elementLayout the layout to be used for splitting.
* @return the element spliterator for this segment
@@ -679,7 +679,7 @@ static MemorySegment ofByteBuffer(ByteBuffer bb) {

/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated byte array.
* The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
* The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
@@ -690,7 +690,7 @@ static MemorySegment ofArray(byte[] arr) {

/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated char array.
* The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
* The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
@@ -701,7 +701,7 @@ static MemorySegment ofArray(char[] arr) {

/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated short array.
* The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
* The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
@@ -712,7 +712,7 @@ static MemorySegment ofArray(short[] arr) {

/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated int array.
* The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
* The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
@@ -723,7 +723,7 @@ static MemorySegment ofArray(int[] arr) {

/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated float array.
* The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
* The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
@@ -734,7 +734,7 @@ static MemorySegment ofArray(float[] arr) {

/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated long array.
* The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
* The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
@@ -745,7 +745,7 @@ static MemorySegment ofArray(long[] arr) {

/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated double array.
* The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
* The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
@@ -456,7 +456,6 @@ static SegmentAllocator nativeAllocator(ResourceScope scope) {
* Returns a native allocator which allocates segments in independent {@linkplain ResourceScope#newImplicitScope() implicit scopes}.
* Equivalent to (but likely more efficient than) the following code:
* {@snippet lang=java :
* ResourceScope scope = ...
* SegmentAllocator implicitAllocator = (size, align) -> MemorySegment.allocateNative(size, align, ResourceScope.newImplicitScope());
* }
*
@@ -59,7 +59,8 @@
sealed public interface VaList extends Addressable permits WinVaList, SysVVaList, LinuxAArch64VaList, MacOsAArch64VaList, SharedUtils.EmptyVaList {

/**
* Reads the next value as an {@code int} and advances this variable argument list's position.
* Reads the next value as an {@code int} and advances this variable argument list's position. The behavior of this
* method is equivalent to the C {@code va_arg} function.
*
* @param layout the layout of the value to be read.
* @return the {@code int} value read from this variable argument list.
@@ -69,7 +70,8 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
int nextVarg(ValueLayout.OfInt layout);

/**
* Reads the next value as a {@code long} and advances this variable argument list's position.
* Reads the next value as a {@code long} and advances this variable argument list's position. The behavior of this
* method is equivalent to the C {@code va_arg} function.
*
* @param layout the layout of the value to be read.
* @return the {@code long} value read from this variable argument list.
@@ -79,7 +81,8 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
long nextVarg(ValueLayout.OfLong layout);

/**
* Reads the next value as a {@code double} and advances this variable argument list's position.
* Reads the next value as a {@code double} and advances this variable argument list's position. The behavior of this
* method is equivalent to the C {@code va_arg} function.
*
* @param layout the layout of the value
* @return the {@code double} value read from this variable argument list.
@@ -89,7 +92,8 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
double nextVarg(ValueLayout.OfDouble layout);

/**
* Reads the next value as a {@code MemoryAddress} and advances this variable argument list's position.
* Reads the next value as a {@code MemoryAddress} and advances this variable argument list's position. The behavior of this
* method is equivalent to the C {@code va_arg} function.
*
* @param layout the layout of the value to be read.
* @return the {@code MemoryAddress} value read from this variable argument list.
@@ -99,7 +103,13 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
MemoryAddress nextVarg(ValueLayout.OfAddress layout);

/**
* Reads the next value as a {@code MemorySegment}, and advances this variable argument list's position.
* Reads the next value as a {@code MemorySegment}, and advances this variable argument list's position. The behavior of this
* method is equivalent to the C {@code va_arg} function. The provided group layout must correspond to a C struct or union
* type.
* <p>
* How the value is read in the returned segment is ABI-dependent: calling this method on a group layout
* with member layouts {@code L_1, L_2, ... L_n} is not guaranteed to be semantically equivalent to perform distinct
* calls to {@code nextVarg} for each of the layouts in {@code L_1, L_2, ... L_n}.
* <p>
* The memory segment returned by this method will be allocated using the given {@link SegmentAllocator}.
*
@@ -129,9 +139,12 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList

/**
* Copies this variable argument list at its current position into a new variable argument list associated
* with the same scope as this variable argument list. Copying is useful to
* traverse the variable argument list elements, starting from the current position, without affecting the state
* of the original variable argument list, essentially allowing the elements to be traversed multiple times.
* with the same scope as this variable argument list. The behavior of this method is equivalent to the C
* {@code va_copy} function.
* <p>
* Copying is useful to traverse the variable argument list elements, starting from the current position,
* without affecting the state of the original variable argument list, essentially allowing the elements to be
* traversed multiple times.
*
* @return a copy of this variable argument list.
* @throws IllegalStateException if the scope associated with this variable argument list has been closed, or if access occurs from
@@ -187,8 +200,8 @@ static VaList ofAddress(MemoryAddress address, ResourceScope scope) {
* of the underlying variable argument list.
* @param scope scope the scope to be associated with the new variable arity list.
* @return a new variable argument list.
* @throws IllegalStateException if the scope associated with {@code allocator} has been already closed,
* or if access occurs from a thread other than the thread owning that scope.
* @throws IllegalStateException if {@code scope} has been already closed, or if access occurs from a thread other
* than the thread owning {@code scope}.
*/
static VaList make(Consumer<Builder> actions, ResourceScope scope) {
Objects.requireNonNull(actions);
@@ -41,7 +41,7 @@

/**
* 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, a {@linkplain ByteOrder byte order})
* (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.
* <p>

1 comment on commit d6b5544

@openjdk-notifier
Copy link

@openjdk-notifier openjdk-notifier bot commented on d6b5544 Dec 15, 2021

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.