Skip to content
This repository has been archived by the owner. It is now read-only.

8278607: Misc issues in foreign API javadoc #17

Closed
wants to merge 4 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
@@ -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>