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

[Jorn Vernee]

On Mon, 23 Sep 2024 08:22:52 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update src/java.base/share/classes/java/lang/doc-files/RestrictedMethods.html
>>   
>>   Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
>
> 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 a Java caller can not be determined, it is as if the restricted method call occurred in an <em>unnamed module</em>.</p>
> 
> Is there any scenario where there are Java frames on the stack but calling through a native frame and back to Java with an upcall leads to the "can not be determined". I can't think of any so wonder if this can be changed to say "no caller class on the stack" as is done in the several CS methods.

I suggested the current wording here: https://github.com/openjdk/jdk/pull/21067#discussion_r1767316787

I think 'no caller on the stack' is too vague. AFAICT, the mechanism by which a CS method determines its caller is not documented (if it is, we should link to that here). Also, I think a user might reasonably ask: "In which cases would there not be a caller class on the stack?". So, I suggested the blanket statement instead, rather than leaning on poorly defined concepts.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21067#discussion_r1771041947