Summary

Introduce a new warning category, namely -Xlint:restricted to issue warnings on restricted method calls.

Problem

Some methods in the Foreign Function & Memory API are restricted. Restricted methods can, if used incorrectly, lead to loss of memory safety, JVM crashes or silent memory corruption. It would be desirable, for some clients, to be able to audit the usage of restricted methods using a compile-time warning that is issued whenever the compiler detects a restricted method invocation.

Solution

This CSR introduces a new warning category, namely -Xlint:restricted, which is used to enable warnings when restricted method calls are found.

As other lint warnings, these new warnings can be controlled via the command line: they are disabled by default, and enabled using the -Xlint:restricted flag. Moreover, they can be suppressed in the source code in the idiomatic way, using a @SuppressWarnings("restricted") annotation.

Below is an example of the compiler output when the warning is enabled:

Foo.java:6: warning: [restricted] MemorySegment.reinterpret(long) is a restricted method.
      Arena.ofAuto().allocate(10).reinterpret(100);
                                 ^
  (Restricted methods are unsafe and, if used incorrectly, might crash the Java runtime or corrupt memory)

Specification

The jdk.compiler's module-info.java file is updated as follows:

diff --git a/src/jdk.compiler/share/classes/module-info.java b/src/jdk.compiler/share/classes/module-info.java
index 79f2b8f2704..c8716233c0f 100644
--- a/src/jdk.compiler/share/classes/module-info.java
+++ b/src/jdk.compiler/share/classes/module-info.java
@@ -173,6 +173,7 @@
  * <tr><th scope="row">{@code preview}              <td>use of preview language features
  * <tr><th scope="row">{@code rawtypes}             <td>use of raw types
  * <tr><th scope="row">{@code removal}              <td>use of API that has been marked for removal
+ * <tr><th scope="row">{@code restricted}           <td>use of restricted methods
  * <tr><th scope="row">{@code requires-automatic}   <td>use of automatic modules in the {@code requires} clauses
  * <tr><th scope="row">{@code requires-transitive-automatic} <td>automatic modules in {@code requires transitive}
  * <tr><th scope="row">{@code serial}               <td>{@link java.base/java.io.Serializable Serializable} classes

The javac manpage is updated as follows:

diff --git a/closed/src/jdk.compiler/share/man/javac.md b/closed/src/jdk.compiler/share/man/javac.md
index 4e77cd7809..d2455464db 100644
--- a/closed/src/jdk.compiler/share/man/javac.md
+++ b/closed/src/jdk.compiler/share/man/javac.md
@@ -589,6 +589,8 @@ file system locations may be directories, JAR files or JMOD files.
     -   `removal`: Warns about the use of an API that has been marked for
         removal.

<ul>
<li><ul><li><code class="prettyprint" data-shared-secret="1733501424224-0.5958710644070302">restricted</code>: Warns about the use of restricted methods.
+
<ul><li><code class="prettyprint" data-shared-secret="1733501424224-0.5958710644070302">requires-automatic</code>: Warns developers about the use of automatic
modules in requires clauses.</li></ul></li></ul></li>
</ul>