archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8338596: Clarify handling of restricted and caller-sensitive methods

Browse source 
Co-authored-by: Hannes Wallnöfer <hannesw@openjdk.org>
Reviewed-by: alanb, jvernee
This commit is contained in:
Maurizio Cimadamore 2024-10-15 09:10:13 +00:00
parent 3b8a2f8c45
commit f4dccfd4cf
5 changed files with 78 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

40
src/java.base/share/classes/java/lang/foreign/package-info.java
View file

@ -128,49 +128,9 @@
* {@linkplain java.lang.foreign.SegmentAllocator#allocateFrom(java.lang.String) converting}
* Java strings into zero-terminated, UTF-8 strings, as demonstrated in the above example.
*
* <h2 id="restricted">Restricted methods</h2>
*
* Some methods in this package are considered <em>restricted</em>. Restricted methods
* are typically used to bind native foreign data and/or functions to first-class
* Java API elements which can then be used directly by clients. For instance the
* restricted method {@link java.lang.foreign.MemorySegment#reinterpret(long)} can be
* used to create a fresh segment with the same address and temporal bounds, but with
* the provided size. This can be useful to resize memory segments obtained when
* interacting with native functions.
* <p>
* Binding foreign data and/or functions is generally unsafe and, if done incorrectly,
* can result in VM crashes, or memory corruption when the bound Java API element
* is accessed. For instance, incorrectly resizing a native memory segment using
* {@link java.lang.foreign.MemorySegment#reinterpret(long)} can lead to a JVM crash, or,
* worse, lead to silent memory corruption when attempting to access the resized segment.
* For these reasons, it is crucial for code that calls a restricted method to never pass
* arguments that might cause incorrect binding of foreign data and/or functions to
* a Java API.
* <p>
* Given the potential danger of restricted methods, the Java runtime issues a warning on
* the standard error stream every time a restricted method is invoked. Such warnings can
* be disabled by granting access to restricted methods to selected modules. This can be
* done either via implementation-specific command line options or programmatically, e.g.
* by calling {@link java.lang.ModuleLayer.Controller#enableNativeAccess(java.lang.Module)}.
* <p>
* For every class in this package, unless specified otherwise, any method arguments of
* reference type must not be {@code null}, and any null argument will elicit a
* {@code NullPointerException}. This fact is not individually documented for methods of
* this API.
*
* @apiNote Usual memory model guarantees (see {@jls 17.4}) do not apply when accessing
* native memory segments as these segments are backed by off-heap regions of memory.
*
* @implNote
* In the reference implementation, access to restricted methods can be granted to
* specific modules using the command line option {@code --enable-native-access=M1,M2, ... Mn},
* where {@code M1}, {@code M2}, {@code ... Mn} are module names (for the unnamed module,
* the special value {@code ALL-UNNAMED} can be used). Access to restricted methods
* from modules not listed by that option is deemed <em>illegal</em>. Clients can
* control how access to restricted methods is handled, using the command line
* option {@code --illegal-native-access}. If this option is not specified,
* illegal access to restricted methods will result in runtime warnings.
*
* @spec jni/index.html Java Native Interface Specification
*
* @since 22