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

[Jorn Vernee]

On Thu, 19 Sep 2024 13:59:30 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:
> 
>   Move restricted method page to `java.lang`
>   Update restricted method page

Looks good!

src/java.base/share/classes/java/lang/doc-files/RestrictedMethods.html line 43:

> 41: <p>When a restricted method is invoked by <a href="../../../../specs/jni/index.html">JNI code</a>,
> 42:     or from an <a href="../Linker.html#upcallStub(java.lang.invoke.MethodHandle,java.lang.foreign.FunctionDescriptor,java.lang.foreign.Arena,java.lang.foreign.Linker.Option...)">upcall stub</a>
> 43:     and there is no caller class on the stack, it is as if the restricted method call occurred in an <em>unnamed module</em>.</p>

> there is no caller class on the stack

I feel like this could be a little more elaborate. I'm not sure if it's clear enough which 'stack' this is talking about, and what it means for a class to be on the stack, considering a reader who doesn't know that the caller of a caller-sensitive method is determined through a stack walk.

Maybe this could be a vague blanket statement instead, like:

Suggestion:

    and a Java caller can not be determined, it is as if the restricted method call occurred in an <em>unnamed module</em>.</p>


Unfortunately, there doesn't seem to be a central place we can link to that describes how a caller for a caller sensitive method is determined, and in which cases it can not be determined (because there is no caller), which we could link to from here. There's a short discussion of caller sensitive methods [here](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/invoke/MethodHandles.Lookup.html#callsens), but it doesn't explain how the caller is determined.

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

Marked as reviewed by jvernee (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/21067#pullrequestreview-2316287230
PR Review Comment: https://git.openjdk.org/jdk/pull/21067#discussion_r1767316787