RFR: 8308645: Javadoc of FFM API needs to be refreshed [v4]

[Maurizio Cimadamore]

On Thu, 1 Jun 2023 13:00:58 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fix wrong link in layout well-formedness doc
>
> src/java.base/share/classes/java/lang/foreign/Arena.java line 269:
> 
>> 267:      * @throws IllegalStateException if this arena has already been {@linkplain #close() closed}.
>> 268:      * @throws WrongThreadException if this arena is confined, and this method is called from a thread {@code T}
>> 269:      * other than the arena's owner thread.
> 
> "thread T" hints that "T" will be used later, maybe it's not needed.

Correct - this is mostly a copy/paste issue for similar throws clauses in methods outside arena.

> src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java line 363:
> 
>> 361:      * The returned allocator throws {@link IndexOutOfBoundsException} when a slice of the provided
>> 362:      * segment with the requested size and alignment cannot be found.
>> 363:      * @implNote A slicing allocator is not <em>thread-safe</em>.
> 
> The implNote about thread safety makes me wonder if the SegmentAllocator should say something about thread safety, e.g. should it specify that the allocate methods are thread safe?

I think SegmentAllocator should be agnostic re. thread safety. Allocation is a world of compromises, where if you give up (thread) safety you can gain more performance (and viceversa). So I think having a "one size fits all" thread-safety blanket might not work very well.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14098#discussion_r1213686844
PR Review Comment: https://git.openjdk.org/jdk/pull/14098#discussion_r1213685702