8298797: Specification of some restricted methods is incorrect

Reviewed-by: jvernee, pminborg

src/java.base/share/classes/java/lang/foreign/Linker.java

@@ -180,9 +180,7 @@ public sealed interface Linker permits AbstractLinker {
      *
      * @return a linker for the ABI associated with the OS and processor where the Java runtime is currently executing.
      * @throws UnsupportedOperationException if the underlying native platform is not supported.
-     * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
-     * {@code --enable-native-access} is specified, but does not mention the module name {@code M}, or
-     * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
      */
     @CallerSensitive
     static Linker nativeLinker() {

src/java.base/share/classes/java/lang/foreign/MemorySegment.java

@@ -1065,9 +1065,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
      * @param byteSize the size (in bytes) of the returned native segment.
      * @return a zero-length native segment with the given address and size.
      * @throws IllegalArgumentException if {@code byteSize < 0}.
-     * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
-     * {@code --enable-native-access} is specified, but does not mention the module name {@code M}, or
-     * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
      */
     @CallerSensitive
     static MemorySegment ofAddress(long address, long byteSize) {
@@ -1088,7 +1086,10 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
      * {@snippet lang = java:
      * ofAddress(address, byteSize, scope, null);
      *}
-     *
+     * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
+     * Restricted methods are unsafe, and, if used incorrectly, their use might crash
+     * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
+     * restricted methods, and use safe and supported functionalities, where possible.
      * @param address the returned segment's address.
      * @param byteSize the desired size.
      * @param scope the scope associated with the returned native segment.
@@ -1097,9 +1098,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
      * @throws IllegalStateException if {@code scope} is not {@linkplain SegmentScope#isAlive() alive}.
      * @throws WrongThreadException if this method is called from a thread {@code T},
      * such that {@code scope.isAccessibleBy(T) == false}.
-     * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
-     * {@code --enable-native-access} is specified, but does not mention the module name {@code M}, or
-     * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
      */
     @CallerSensitive
     @ForceInline
@@ -1140,9 +1139,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
      * @throws IllegalStateException if {@code scope} is not {@linkplain SegmentScope#isAlive() alive}.
      * @throws WrongThreadException if this method is called from a thread {@code T},
      * such that {@code scope.isAccessibleBy(T) == false}.
-     * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
-     * {@code --enable-native-access} is specified, but does not mention the module name {@code M}, or
-     * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
      */
     @CallerSensitive
     static MemorySegment ofAddress(long address, long byteSize, SegmentScope scope, Runnable cleanupAction) {

src/java.base/share/classes/java/lang/foreign/SymbolLookup.java

@@ -189,9 +189,7 @@ public interface SymbolLookup {
      * @param scope the scope associated with symbols obtained from the returned lookup.
      * @return a new symbol lookup suitable to find symbols in a library with the given name.
      * @throws IllegalArgumentException if {@code name} does not identify a valid library.
-     * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
-     * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
-     * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
      */
     @CallerSensitive
     static SymbolLookup libraryLookup(String name, SegmentScope scope) {
@@ -215,9 +213,7 @@ public interface SymbolLookup {
      * @param scope the scope associated with symbols obtained from the returned lookup.
      * @return a new symbol lookup suitable to find symbols in a library with the given path.
      * @throws IllegalArgumentException if {@code path} does not point to a valid library.
-     * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
-     * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
-     * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
      */
     @CallerSensitive
     static SymbolLookup libraryLookup(Path path, SegmentScope scope) {

src/java.base/share/classes/java/lang/foreign/VaList.java

@@ -247,9 +247,7 @@ public sealed interface VaList permits WinVaList, SysVVaList, LinuxAArch64VaList
      * @throws WrongThreadException          if this method is called from a thread {@code T},
      *                                       such that {@code scope.isAccessibleBy(T) == false}.
      * @throws UnsupportedOperationException if the underlying native platform is not supported.
-     * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
-     * {@code --enable-native-access} is specified, but does not mention the module name {@code M}, or
-     * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
      */
     @CallerSensitive
     static VaList ofAddress(long address, SegmentScope scope) {

src/java.base/share/classes/java/lang/foreign/ValueLayout.java

@@ -424,6 +424,7 @@ public sealed interface ValueLayout extends MemoryLayout {
          * restricted methods, and use safe and supported functionalities, where possible.
          *
          * @return an unbounded address layout with same characteristics as this layout.
+         * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
          * @see #isUnbounded()
          */
         @CallerSensitive

test/jdk/java/foreign/handles/lookup_module/handle/lookup/MethodHandleLookup.java

@@ -50,9 +50,15 @@ public class MethodHandleLookup {
             return new Object[][]{
                     { MethodHandles.lookup().findStatic(Linker.class, "nativeLinker",
                             MethodType.methodType(Linker.class)), "Linker::nativeLinker" },
+                    { MethodHandles.lookup().findStatic(MemorySegment.class, "ofAddress",
+                            MethodType.methodType(MemorySegment.class, long.class, long.class)),
+                            "MemorySegment::ofAddress/2" },
                     { MethodHandles.lookup().findStatic(MemorySegment.class, "ofAddress",
                             MethodType.methodType(MemorySegment.class, long.class, long.class, SegmentScope.class)),
-                            "MemorySegment::ofAddressNative" },
+                            "MemorySegment::ofAddress/3" },
+                    { MethodHandles.lookup().findStatic(MemorySegment.class, "ofAddress",
+                            MethodType.methodType(MemorySegment.class, long.class, long.class, SegmentScope.class, Runnable.class)),
+                            "MemorySegment::ofAddress/4" },
                     { MethodHandles.lookup().findStatic(SymbolLookup.class, "libraryLookup",
                             MethodType.methodType(SymbolLookup.class, String.class, SegmentScope.class)),
                             "SymbolLookup::libraryLookup(String)" },