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

[Maurizio Cimadamore]

On Fri, 27 Oct 2023 04:54:04 GMT, David Holmes <dholmes at openjdk.org> wrote:

>> 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 15 classes in java.base that explicitly document this.

Taking inspiration from other methods that throw this exception, maybe something like this might work:

`if the downcall method handle cannot be allocated by the Linker`

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

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