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

Maurizio Cimadamore mcimadamore at openjdk.org
Fri Sep 20 08:52:48 UTC 2024


On Thu, 19 Sep 2024 21:25:21 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:
> 
>   Update src/java.base/share/classes/java/lang/doc-files/RestrictedMethods.html
>   
>   Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>

> > And I claim that this is outside the scope of this PR.
> 
> And I strongly disagree because the only reason I conceded that this documentation issue need not be addressed by the CSR request for JEP 472 was because JDK-8338596 was filed to address it - ref the comment from @jddarcy : https://bugs.openjdk.org/browse/JDK-8331672?focusedId=14699206&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14699206



> > And I claim that this is outside the scope of this PR.
> 
> And I strongly disagree because the only reason I conceded that this documentation issue need not be addressed by the CSR request for JEP 472 was because JDK-8338596 was filed to address it - ref the comment from @jddarcy : https://bugs.openjdk.org/browse/JDK-8331672?focusedId=14699206&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14699206

Just be clarify: is it your expectation that, in order for this issue to be fixed, we should fix the javadoc of *all* caller sensitive methods, addressing issues that have nothing to do with restricted-ness? If so, then my reading of this issue was incorrect, I will close this PR, and file a separate, more targeted, issue to improve the situation of restricted methods only (which is the goal of this PR).

Separately, while I agree that the javadoc for caller sensitive methods is lacking in many ways, I don't see the connection between correctly specifying what classloader is used in `System.loadLibrary` and JEP 472. That is, that javadoc issue has been there before JEP 472 - and unaffected by it. Restrictedness, on the other hand, adds a new dimension (and this is indeed new in JEP 472, at least for some of the methods outside FFM), so it makes sense to say: now we have to say what happens when restricted methods are called and there's no Java class in the caller stack.

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

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


More information about the core-libs-dev mailing list