8254693: Add Panama feature to pass heap segments to native code

Reviewed-by: mcimadamore, lucy, vlivanov

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

@@ -669,8 +669,13 @@ public sealed interface Linker permits AbstractLinker {
      * might attempt to access the contents of the segment. As such, one of the
      * exceptions specified by the {@link MemorySegment#get(ValueLayout.OfByte, long)} or
      * the {@link MemorySegment#copy(MemorySegment, long, MemorySegment, long, long)}
-     * methods may be thrown. The returned method handle will additionally throw
-     * {@link NullPointerException} if any argument passed to it is {@code null}.
+     * methods may be thrown. If an argument is a {@link MemorySegment} whose
+     * corresponding layout is an {@linkplain AddressLayout address layout}, the linker
+     * will throw an {@link IllegalArgumentException} if the segment is a heap memory
+     * segment, unless heap memory segments are explicitly allowed through the
+     * {@link Linker.Option#critical(boolean)} linker option. The returned method handle
+     * will additionally throw {@link NullPointerException} if any argument passed to it
+     * is {@code null}.
      *
      * @param function the function descriptor of the target foreign function
      * @param options  the linker options associated with this linkage request
@@ -914,9 +919,23 @@ public sealed interface Linker permits AbstractLinker {
          * <p>
          * Using this linker option when linking non-critical functions is likely to have
          * adverse effects, such as loss of performance or JVM crashes.
+         * <p>
+         * Critical functions can optionally allow access to the Java heap. This allows
+         * clients to pass heap memory segments as addresses, where normally only off-heap
+         * memory segments would be allowed. The memory region inside the Java heap is
+         * exposed through a temporary native address that is valid for the duration of
+         * the function call. Use of this mechanism is therefore only recommended when a
+         * function needs to do short-lived access to Java heap memory, and copying the
+         * relevant data to an off-heap memory segment would be prohibitive in terms of
+         * performance.
+         *
+         * @param allowHeapAccess whether the linked function should allow access to the
+         *                        Java heap.
          */
-        static Option critical() {
-            return LinkerOptions.Critical.INSTANCE;
+        static Option critical(boolean allowHeapAccess) {
+            return allowHeapAccess
+                ? LinkerOptions.Critical.ALLOW_HEAP
+                : LinkerOptions.Critical.DONT_ALLOW_HEAP;
         }
     }
 }

src/java.base/share/classes/java/lang/invoke/NativeMethodHandle.java

@@ -77,7 +77,8 @@ import static java.lang.invoke.MethodHandleStatics.newInternalError;
               || pType == int.class
               || pType == float.class
               || pType == double.class
-              || pType == void.class);
+              || pType == void.class
+              || pType == Object.class);
     }
 
     private static final MemberName.Factory IMPL_NAMES = MemberName.getFactory();