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

[Alan Bateman]

On Mon, 23 Sep 2024 09:21:35 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> 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.

We use "no caller class" in the CS methods, maybe it could be improved. 

I think "can not be determined" just begs questions. Is this a JDK limitation, something I'm doing wrong, or something else, ... if you see what I mean.

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

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