Skip to content

Commit

Permalink
8319607: FFM: Review the language in the FFM documentation
Browse files Browse the repository at this point in the history
Reviewed-by: mcimadamore
  • Loading branch information
minborg committed Nov 7, 2023
1 parent bf9a93d commit ef8c840
Show file tree
Hide file tree
Showing 12 changed files with 128 additions and 128 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,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.
* @return an address layout with the 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
* @see #targetLayout()
*/
Expand All @@ -114,7 +114,7 @@ public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.O
*
* @apiNote This can be useful to compare two address layouts that have different target layouts, but are otherwise equal.
*
* @return an address layout with same characteristics as this layout, but with no target layout.
* @return an address layout with the same characteristics as this layout, but with no target layout.
* @see #targetLayout()
*/
AddressLayout withoutTargetLayout();
Expand Down
2 changes: 1 addition & 1 deletion src/java.base/share/classes/java/lang/foreign/Arena.java
Original file line number Diff line number Diff line change
Expand Up @@ -246,7 +246,7 @@ static Arena ofShared() {
* The returned segment is associated with this {@linkplain #scope() arena scope}.
* The segment's {@link MemorySegment#address() address} is the starting address of the
* allocated off-heap region of memory backing the segment, and the address is
* aligned according the provided alignment constraint.
* aligned according to the provided alignment constraint.
*
* @implSpec
* Implementations of this method must return a native segment featuring the requested size,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl {
* Returns a function descriptor with the given argument layouts inserted at the given index, into the argument
* layout array of this function descriptor.
* @param index the index at which to insert the arguments
* @param addedLayouts the argument layouts to insert at given index.
* @param addedLayouts the argument layouts to insert at the 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()}
Expand Down Expand Up @@ -100,7 +100,7 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl {
* </ul>
*
* @apiNote A function descriptor cannot, by construction, contain any padding layouts. As such, it is not
* necessary to specify how padding layout should be mapped to carrier types.
* necessary to specify how padding layouts should be mapped to carrier types.
*
* @return the method type consisting of the carrier types of the layouts in this function descriptor.
*/
Expand All @@ -121,7 +121,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
* Creates a function descriptor with the given argument layouts and no return layout. This is useful for modeling functions
* that return no values.
* @param argLayouts the argument layouts.
* @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ public sealed interface GroupLayout extends MemoryLayout permits StructLayout, U
/**
* {@return the member layouts of this group layout}
*
* @apiNote the order in which member layouts are returned is the same order in which member layouts have
* @apiNote the order in which member layouts are returned in the same order in which member layouts have
* been passed to one of the group layout factory methods (see {@link MemoryLayout#structLayout(MemoryLayout...)},
* {@link MemoryLayout#unionLayout(MemoryLayout...)}).
*/
Expand Down
42 changes: 21 additions & 21 deletions src/java.base/share/classes/java/lang/foreign/Linker.java
Original file line number Diff line number Diff line change
Expand Up @@ -43,13 +43,13 @@
/**
* A linker provides access to foreign functions from Java code, and access to Java code from foreign functions.
* <p>
* Foreign functions typically reside in libraries that can be loaded on-demand. Each library conforms to
* Foreign functions typically reside in libraries that can be loaded on demand. Each library conforms to
* a specific ABI (Application Binary Interface). An ABI is a set of calling conventions and data types associated with
* the compiler, OS, and processor where the library was built. For example, a C compiler on Linux/x64 usually
* builds libraries that conform to the SystemV ABI.
* <p>
* A linker has detailed knowledge of the calling conventions and data types used by a specific ABI.
* For any library which conforms to that ABI, the linker can mediate between Java code running
* For any library that conforms to that ABI, the linker can mediate between Java code running
* in the JVM and foreign functions in the library. In particular:
* <ul>
* <li>A linker allows Java code to link against foreign functions, via
Expand Down Expand Up @@ -106,21 +106,21 @@
* of the C function they wish to link against. This description, a {@link FunctionDescriptor function descriptor},
* defines the layouts associated with the parameter types and return type (if any) of the C function.
* <p>
* Scalar C types such as {@code bool}, {@code int} are modelled as {@linkplain ValueLayout value layouts}
* Scalar C types such as {@code bool}, {@code int} are modeled as {@linkplain ValueLayout value layouts}
* of a suitable carrier. The {@linkplain #canonicalLayouts() mapping} between a scalar type and its corresponding
* canonical layout is dependent on the ABI implemented by the native linker (see below).
* <p>
* Composite types are modelled as {@linkplain GroupLayout group layouts}. More specifically, a C {@code struct} type
* Composite types are modeled as {@linkplain GroupLayout group layouts}. More specifically, a C {@code struct} type
* maps to a {@linkplain StructLayout struct layout}, whereas a C {@code union} type maps to a {@link UnionLayout union
* layout}. When defining a struct or union layout, clients must pay attention to the size and alignment constraint
* of the corresponding composite type definition in C. For instance, padding between two struct fields
* must be modelled explicitly, by adding an adequately sized {@linkplain PaddingLayout padding layout} member
* must be modeled explicitly, by adding an adequately sized {@linkplain PaddingLayout padding layout} member
* to the resulting struct layout.
* <p>
* Finally, pointer types such as {@code int**} and {@code int(*)(size_t*, size_t*)} are modelled as
* Finally, pointer types such as {@code int**} and {@code int(*)(size_t*, size_t*)} are modeled as
* {@linkplain AddressLayout address layouts}. When the spatial bounds of the pointer type are known statically,
* the address layout can be associated with a {@linkplain AddressLayout#targetLayout() target layout}. For instance,
* a pointer that is known to point to a C {@code int[2]} array can be modelled as an address layout whose
* a pointer that is known to point to a C {@code int[2]} array can be modeled as an address layout whose
* target layout is a sequence layout whose element count is 2, and whose element type is {@link ValueLayout#JAVA_INT}.
* <p>
* All native linker implementations are guaranteed to provide canonical layouts for the following set of types:
Expand All @@ -144,11 +144,11 @@
* constant {@link ValueLayout#JAVA_INT} on 32-bit platforms.
* <p>
* A native linker typically does not provide canonical layouts for C's unsigned integral types. Instead, they are
* modelled using the canonical layouts associated with their corresponding signed integral types. For instance,
* modeled using the canonical layouts associated with their corresponding signed integral types. For instance,
* the C type {@code unsigned long} maps to the layout constant {@link ValueLayout#JAVA_LONG} on Linux/x64, but maps to
* the layout constant {@link ValueLayout#JAVA_INT} on Windows/x64.
* <p>
* The following table shows some examples of how C types are modelled in Linux/x64 according to the
* The following table shows some examples of how C types are modeled in Linux/x64 according to the
* "System V Application Binary Interface" (all the examples provided here will assume these platform-dependent mappings):
*
* <blockquote><table class="plain">
Expand Down Expand Up @@ -246,7 +246,7 @@
*
* Linker implementations may optionally support additional layouts, such as <em>packed</em> struct layouts.
* A packed struct is a struct in which there is at least one member layout {@code L} that has an alignment
* constraint less strict than its natural alignment. This allows avoiding padding between member layouts,
* constraint less strict than its natural alignment. This allows to avoid padding between member layouts,
* as well as avoiding padding at the end of the struct layout. For example:
* {@snippet lang = java:
* // No padding between the 2 element layouts:
Expand Down Expand Up @@ -317,7 +317,7 @@
* as the target layout for the address layouts of both parameters. This will allow the comparator method to access
* the contents of the array elements to be compared. We then {@linkplain FunctionDescriptor#toMethodType() turn}
* that function descriptor into a suitable {@linkplain java.lang.invoke.MethodType method type} which we then use to look up
* the comparator method handle. We can now create an upcall stub which points to that method, and pass it, as a function
* the comparator method handle. We can now create an upcall stub that points to that method, and pass it, as a function
* pointer, to the {@code qsort} downcall handle, as follows:
*
* {@snippet lang = java:
Expand All @@ -343,7 +343,7 @@
* void *malloc(size_t size);
* }
*
* The {@code malloc} function allocates a region of memory of given size,
* The {@code malloc} function allocates a region of memory with the given size,
* and returns a pointer to that region of memory, which is later deallocated using another function from
* the C standard library:
*
Expand Down Expand Up @@ -415,12 +415,12 @@
* }
*
* Note how the segment obtained from {@code allocateMemory} acts as any other segment managed by the confined arena. More
* specifically, the obtained segment has the desired size, can only be accessed by a single thread (the thread which created
* specifically, the obtained segment has the desired size, can only be accessed by a single thread (the thread that created
* the confined arena), and its lifetime is tied to the surrounding <em>try-with-resources</em> block.
*
* <h3 id="variadic-funcs">Variadic functions</h3>
*
* Variadic functions are C functions which can accept a variable number and type of arguments. They are declared with a
* Variadic functions are C functions that can accept a variable number and type of arguments. They are declared with a
* trailing ellipsis ({@code ...}) at the end of the formal parameter list, such as: {@code void foo(int x, ...);}
* The arguments passed in place of the ellipsis are called <em>variadic arguments</em>. Variadic functions are,
* essentially, templates that can be <em>specialized</em> into multiple non-variadic functions by replacing the
Expand All @@ -435,7 +435,7 @@
* <li>{@code float} -> {@code double}</li>
* </ul>
* whereby the signed-ness of the source type corresponds to the signed-ness of the promoted type. The complete process
* of default argument promotion is described in the C specification. In effect these promotions place limits on the
* of default argument promotion is described in the C specification. In effect, these promotions place limits on the
* types that can be used to replace the {@code ...}, as the variadic parameters of the specialized form of a variadic
* function will always have a promoted type.
* <p>
Expand Down Expand Up @@ -503,7 +503,7 @@
* associated with the upcall stub to a type that is incompatible with the type of the upcall stub, and then attempts to
* invoke the function through the resulting function pointer. Moreover, if the method
* handle associated with an upcall stub returns a {@linkplain MemorySegment memory segment}, clients must ensure
* that this address cannot become invalid after the upcall completes. This can lead to unspecified behavior,
* that this address cannot become invalid after the upcall is completed. This can lead to unspecified behavior,
* and even JVM crashes, since an upcall is typically executed in the context of a downcall method handle invocation.
*
* @implSpec
Expand All @@ -529,7 +529,7 @@ static Linker nativeLinker() {
}

/**
* Creates a method handle which is used to call a foreign function with the given signature and address.
* Creates a method handle that is used to call a foreign function with the given signature and address.
* <p>
* Calling this method is equivalent to the following code:
* {@snippet lang=java :
Expand All @@ -553,7 +553,7 @@ static Linker nativeLinker() {
MethodHandle downcallHandle(MemorySegment address, FunctionDescriptor function, Option... options);

/**
* Creates a method handle which is used to call a foreign function with the given signature.
* Creates a method handle that is used to call a foreign function with the given signature.
* <p>
* The Java {@linkplain java.lang.invoke.MethodType method type} associated with the returned method handle is
* {@linkplain FunctionDescriptor#toMethodType() derived} from the argument and return layouts in the function descriptor,
Expand Down Expand Up @@ -660,7 +660,7 @@ static Linker nativeLinker() {
* <p>
* Each {@link Linker} is responsible for choosing the data types that are widely recognized as useful on the OS
* and processor combination supported by the {@link Linker}. Accordingly, the precise set of data type names
* and canonical layouts exposed by the linker is unspecified; it varies from one {@link Linker} to another.
* and canonical layouts exposed by the linker are unspecified; they vary from one {@link Linker} to another.
* @implNote It is strongly recommended that the result of {@link #canonicalLayouts()} exposes a set of symbols that is stable over time.
* Clients of {@link #canonicalLayouts()} are likely to fail if a data type that was previously exposed by the linker
* is no longer exposed, or if its canonical layout is updated.
Expand Down Expand Up @@ -787,11 +787,11 @@ static StructLayout captureStateLayout() {
* A critical function is a function that has an extremely short running time in all cases
* (similar to calling an empty function), and does not call back into Java (e.g. using an upcall stub).
* <p>
* Using this linker option is a hint which some implementations may use to apply
* Using this linker option is a hint that some implementations may use to apply
* optimizations that are only valid for critical functions.
* <p>
* Using this linker option when linking non-critical functions is likely to have adverse effects,
* such as loss of performance, or JVM crashes.
* such as loss of performance or JVM crashes.
*/
static Option critical() {
return LinkerOptions.Critical.INSTANCE;
Expand Down

1 comment on commit ef8c840

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