RFR: 8318586: Explicitly handle upcall stub allocation failure [v3]

[David Holmes]

On Thu, 26 Oct 2023 18:07:24 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Throw OOME for allocation failures
>
> src/java.base/share/classes/java/lang/foreign/Linker.java line 532:
> 
>> 530:      * @throws IllegalArgumentException if an invalid combination of linker options is given.
>> 531:      * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
>> 532:      * @throws OutOfMemoryError if the runtime does not have the memory needed to create the downcall handle.
> 
> Suggestions for the phrasing here are welcome. I think we should use something that works for both downcall handles and upcall stubs though.

OOME is pretty much understood to be possible anywhere, given it is a VirtualMachineError. We often do not document it explicitly. The risk with documenting it is that it gives the impression that other methods, which don't document it, can never throw it. A rough grep for `@throws OutOfMemoryError` reveals only 12 classes in java.base that explicitly document this.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16311#discussion_r1374071184