RFR: 8295044: Implementation of Foreign Function and Memory API (Second Preview) [v17]

[Paul Sandoz]

On Wed, 9 Nov 2022 13:24:54 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This PR contains the API and implementation changes for JEP-434 [1]. A more detailed description of such changes, to avoid repetitions during the review process, is included as a separate comment.
>> 
>> [1] - https://openjdk.org/jeps/434
>
> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Tweak Arena::close javadoc

src/java.base/share/classes/java/lang/foreign/Arena.java line 101:

> 99:      * @throws IllegalArgumentException if {@code bytesSize < 0}, {@code alignmentBytes <= 0}, or if {@code alignmentBytes}
> 100:      * is not a power of 2.
> 101:      * @throws IllegalStateException if the session associated with this arena is not {@linkplain MemorySession#isAlive() alive}.

Suggestion:

     * @throws IllegalStateException if arena's session is not {@linkplain MemorySession#isAlive() alive}.

src/java.base/share/classes/java/lang/foreign/Arena.java line 121:

> 119:      * segments associated with that memory session are also released.
> 120:      * @throws IllegalStateException if the session associated with this arena is not {@linkplain MemorySession#isAlive() alive}.
> 121:      * @throws IllegalStateException if this session is {@linkplain MemorySession#whileAlive(Runnable) kept alive} by another client.

Suggestion:

     * @throws IllegalStateException if the arena's session is not {@linkplain MemorySession#isAlive() alive}.
     * @throws IllegalStateException if the arena's session is {@linkplain MemorySession#whileAlive(Runnable) kept alive}.


Note i removed "by another client". I wanted to say "by another thread", but then there is the case of calling close from within the Runnable passed to whileAlive, so i wanted to say "by another caller". But, i think this can all be implied and we don't need to say anything.

src/java.base/share/classes/java/lang/foreign/MemorySession.java line 66:

> 64:  * is not critical, or in unstructured cases where the boundaries of the lifetime associated with a memory session
> 65:  * cannot be easily determined. As shown in the example above, a memory session that is managed implicitly cannot end
> 66:  * if a program references to one or more segments associated with that session. This means that memory segments associated

Suggestion:

 * if a program references one or more segments associated with that session. This means that memory segments associated

src/java.base/share/classes/java/lang/foreign/MemorySession.java line 89:

> 87: 
> 88:     /**
> 89:      * {@return {@code true} if the provided thread can access and/or obtain segments associated with this memory session}

Is the following accurate and more concise?
Suggestion:

     * {@return {@code true} if the provided thread can access and/or associate segments with this memory session}

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

PR: https://git.openjdk.org/jdk/pull/10872