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.

That said, I also agree with @dholmes-ora - e.g. I'm not sure how much OOME is important to document here, since it reflects an internal state of the JVM, rather than something the client can do something about.

E.g. if you create an allocator with `SegmentAllocator::slicingAllocator`, at some point you are going to run out of space in the underlying segment, so it makes sense to report failures (and to document why that happens). But in this case the documentation is going to be very vague, and I don't think it provides a lot of value.

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

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