[foreign-abi] RFR: 8253373: Add package-level javadoc for foreign linker support

[Jorn Vernee]

On Fri, 18 Sep 2020 20:55:30 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch modifies the toplevel javadoc of jdk.incubator.foreign to add details about the ABI support.
> 
> I've decided to split the javadoc into two main sections - one about memory access, and one about foreign function
> access; they have subsections for more detailed info.
> There's also a trailing toplevel section on "restricted method". I'm still wordsmithing the definition of "what's it
> like to be a restricted method" together with Alex, but this is a first attempt. It is likely that, once we have this
> done, we can have the various restrcited definitions inside the API refer bakc to this section.
> Link to javadoc:
> http://cr.openjdk.java.net/~mcimadamore/panama/foreign-linker-javadoc/javadoc/jdk/incubator/foreign/package-summary.html

Marked as reviewed by jvernee (Committer).

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java line 116:

> 114: );
> 115:
> 116: long len = strlen.invokeExact(CLinker.toCString("Hello").address()) // 5

This is leaking the created C string, which seems like a bad thing to do in an example. Maybe use TWR?
Suggestion:

try (var cString = CLinker.toCString("Hello")) {
    long len = strlen.invokeExact(cString.address()) // 5
}

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java line 137:

> 135:  * are fully known at segment creation. But when interacting with native libraries, clients will often receive
> <em>raw</em> pointers; 136:  * such pointers have no spatial bounds (example: does the C type {@code char*} refer to a
> single {@code char} value, 137:  * or an array of {@code char} values, of given size?), no notion of temporal bounds,
> nor thread-confinement.

Maybe this is already covered in the memaccess section, but I feel like there is a missing 'As such, MemoryAddresses
can not be used to access memory directly.' Or something like that here.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java line 175:

> 173:  *
> 174:  * <h3>Upcalls</h3>
> 175:  * The {@link jdk.incubator.foreign.CLinker} class also allows to turn an existing method handles (which might
> point

Suggestion:

 * The {@link jdk.incubator.foreign.CLinker} class also allows to turn an existing method handle (which might point

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java line 223:

> 221:  * spatial bounds are incorrect, a client of the segment returned by that method might crash the VM, or corrupt
> 222:  * memory when attempting to dereference said segment. For these reasons, it is crucial for code that calls a
> restricted method 223:  * to never pass arguments that might causes incorrect binding of foreign data and/or functions
> to a Java API.

Suggestion:

 * to never pass arguments that might cause incorrect binding of foreign data and/or functions to a Java API.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java line 225:

> 223:  * to never pass arguments that might causes incorrect binding of foreign data and/or functions to a Java API.
> 224:  * <p>
> 225:  * Access to restricted method is <em>disabled</em> by default; to enable restricted methods, the JDK property

Suggestion:

 * Access to restricted methods is <em>disabled</em> by default; to enable restricted methods, the JDK property

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java line 231:

> 229:  * <li>{@code permit}: allows restricted calls;</li>
> 230:  * <li>{@code warn}: like permit, but also prints a one-line warning on each restricted call;</li>
> 231:  * <li>{@code debug}: like permit, but also dumps the stack corresponding to any given restricted.</li>

Suggestion:

 * <li>{@code debug}: like permit, but also dumps the stack corresponding to any given restricted call.</li>

-------------

PR: https://git.openjdk.java.net/panama-foreign/pull/346