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

[Alan Bateman]

On Mon, 23 Sep 2024 12:06:51 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>>> 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.
>> 
>> I think saying 'no caller class on the stack' has the same effect though, unless someone knows how the implementation works (which may not be unreasonable), and is aware of the scenario where a java method is called from a new native thread. I thought it would look cleaner to have this be more 'explicitly unspecified' instead. But, maybe having something (vague or not), is better than nothing...
>
>> It is documented by the CS JEP: https://openjdk.org/jeps/176
> 
> I read the JEP, but it only refers to `sun.reflect.Reflection.getCallerClass`, which is an internal API that I don't expect external users to know about/understand.
> 
> To be clear: I don't think we should explain exactly how CS methods determine the caller. IMO, the fact that this is implemented using a stack walk is an implementation detail that users shouldn't have to know about (and it seems plausible for VM implementations to use other mechanisms). Or at least, that's what I would _like_ to think.
> 
> In lieu of that, I think it would be better to say that: in general (depending on the VM impl) there may be cases in which the caller can not be determined, and then as an example explicitly enumerate the cases in which the caller class can not be determined by the reference implementation. That explanation can then be linked to from the CS methods.

The "stack" is exposed in the API with StackWalker, Thread::getStackTrace and other APIs. For CS and restricted methods then I think we are trying to convey that there are no Java frames on the caller stack. Several existing CS APIs document the case where there is "no caller frame on the stack". This is mostly to cover the case where a CS method is invoked from a JNI attached thread. If there are native frames sandwiched between Java frames and a CS method then the intention was that these methods use the Java frame for the check, but that is hard to specify and it sounds like we have to re-visit this a bit.

For now, I think the proposed wording in this PR is okay. There are clearly some follows up needed.

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

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