On Wed, 18 Sep 2024 15:47:01 GMT, Maurizio Cimadamore <mcimadam...@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...)). Is the `java/lang/foreign` package still the right place for this? (Maybe it should be under `java/lang`). src/java.base/share/classes/java/lang/foreign/doc-files/RestrictedMethods.html line 34: > 32: > 33: Some methods in the Java SE API are considered <em>restricted</em>. > Restricted methods > 34: are typically used to bind native foreign data and/or functions to > first-class I feel like a short general description is warranted here as well. Maybe something like: 'Restricted methods are APIs that can, when used incorrectly, violate the integrity of the Java Virtual Machine, but are conditionally made available to users as they provide essential functionality' src/java.base/share/classes/java/lang/foreign/doc-files/RestrictedMethods.html line 39: > 37: can be used to create a fresh segment with the same address and temporal > bounds, but with > 38: the provided size. This can be useful to resize memory segments obtained > when > 39: interacting with native functions. This example is now talking about 'segment'/'address'/'temporal bounds' without the context of the other text in the package-info file, which seems a bit confusing. I suggest removing the example here, as essentially the same example is given in the next paragraph as well. ------------- PR Review: https://git.openjdk.org/jdk/pull/21067#pullrequestreview-2313392631 PR Review Comment: https://git.openjdk.org/jdk/pull/21067#discussion_r1765490635 PR Review Comment: https://git.openjdk.org/jdk/pull/21067#discussion_r1765482794
