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](https://openjdk.org/jeps/454) 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.
 
+    -   `restricted`: Warns about the use of restricted methods.
+
     -   `requires-automatic`: Warns developers about the use of automatic
         modules in requires clauses.
 
```