Summary

Deprecate the memory-access methods in sun.misc.Unsafe for removal in a future release, as proposed in JEP 471.

Add a command line option to allow or deny usage of these methods. The default value for JDK 23 will be to allow, without warnings, so the only immediate compatibility / impact of the changes is removal warnings at compile-time.

Problem

VarHandles were introduced in Java 9 to safely and efficiently manipulate on-heap memory. The MemorySegment API (part of the Foreign Function & Memory API) became a permanent API in Java 22 to safely and efficiently access off-heap memory. It's time to encourage library developers that use the undocumented Unsafe API to move to the supported replacements. This is important to allow applications migrate smoothly to JDK releases in the future.

Solution

Deprecate the memory-access methods for removal. In total we propose to deprecate 97 methods and constants, for removal in a future release. 3 of the methods were previously deprecated in JDK 18 (JDK-8278223).

Add the command line option --sun-misc-unsafe-memory-access=<value> to control whether to allow or deny usage of the memory access methods. This command line option can also be used to get a warning on first usage, or print a stack trace so that the code using these methods can be quickly identified.

Specification

Deprecate for removal all memory access methods as listed in JEP 471. A @deprecated message is added to each method and constant. Attached is the generated javadoc. The JDK does not generate or publish the javadoc for this class so it will only be seen by developers that open the source file.

java -X will have the following in the usage output:

    --sun-misc-unsafe-memory-access=<value>
                      allow or deny usage of unsupported API sun.misc.Unsafe
                      <value> is one of "allow", "warn", "debug", or "deny".
                     The default value is "allow".

The default value for JDK 23 will be "allow". It allows the memory access methods be used without any warning.

The value "warn" allows the memory access methods be used and prints at most one warning to standard error when any memory methods is used. An example warning is shown in the JEP.

The value "debug" allows the memory access methods be used and prints a message and stack trace to standard error when a memory access method is used.

The value "deny" causes all memory access methods to throw UnsupportedOperationException.

The man page for the "java" command is updated to document the option, see attached text.

A release note is planned.