RFR: 8338596: Clarify handling of restricted and caller-sensitive methods [v4]

[Maurizio Cimadamore]

On Mon, 23 Sep 2024 10:30:18 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This PR moves the section on restricted methods from the the javadoc of `java.lang.foreign` package into a standalone static [javadoc page](https://cr.openjdk.org/~mcimadamore/jdk/restricted_javadoc_section/docs/api/java.base/java/lang/foreign/doc-files/RestrictedMethods.html).
>> 
>> This is because, after [JEP 472](https://openjdk.org/jeps/472), we now have restricted methods *outside* the foreign package, namely `System::loadLibrary`, `Runtime::loadLibrary` (and related methods). And, even before, we also had a restricted method in `ModuleLayer.Controller`.
>> 
>> The new static page contains some guidance of what happens when a restricted method is called when there's no Java frame on the stack (this can happen e.g. when upcalling into a restricted method from a native thread not known to the JVM) - that is, the call is treated as originating from an unnamed module.
>> 
>> The static page is linked from the restricted method banner in a restricted method javadoc. Here's an [example](https://cr.openjdk.org/~mcimadamore/jdk/restricted_javadoc_section/docs/api/java.base/java/lang/foreign/Linker.html#downcallHandle(java.lang.foreign.MemorySegment,java.lang.foreign.FunctionDescriptor,java.lang.foreign.Linker.Option...)).
>
> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Revert reference to caller stack

I've reverted the sentence that refers to "no caller class on the stack".

As for the remaining comments, I'm not sure how to proceed. Especially stuff like:

> though at the moment the restricted method text doesn't seem to talk about simple native method calls at all, so the reason for loadLibrary being restricted is not at all obvious IMO.

I don't see the connection between "restricted methods" and "simple native methods". Restricted methods, as per the new javadoc text:

> allow Java code to interoperate with resources outside the Java runtime in such a way that the runtime cannot prove correct or safe use of the resources

It is outside the scope of the javadoc text to state exactly *why* each restricted method is marked as such. In general, we do not provide many clarifications in any of the existing restricted methods, as the reason for "restrictedness" is rather obvious from reading the javadoc. In the case of `System::loadLibrary` things are more subtle, although, again, when reading the javadoc, the javadoc refers to the JNI specification, which then brings up `JNI_OnLoad` - e.g. loading a native library *might* result in the execution of native code - hence the restricted status.

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

PR Comment: https://git.openjdk.org/jdk/pull/21067#issuecomment-2367829201