Summary

The javadoc for Arena::close should specify what happens when exceptions are thrown by cleanup actions passed to MemorySegment::reinterpret.

Problem

MemorySegment::reinterpret allows developers to specify a cleanup action - an action that should be executed when the arena associated with the reinterpreted segment is closed.

The custom cleanup action might throw some exceptions. Unfortunately, in the current API, Arena::close is only specified to throw IllegalStateException, UnsupportedOperationException or WrongThreadException, meaning that any exception thrown by the custom cleanup action would effectively violate the API contract for that method.

Solution

It would be better for the javadoc to say something about the fact that Arena::close might fail with a runtime exception. Note, cleanup actions are specified using Consumer, so only runtime exception (or errors) are possible. The case of error is less interesting, as I believe errors can occur pretty much everywhere, and it it not too interesting to document them.

Specification

The change in this CSR are as follows:

index adfc3a1fe6b..195f8a44db6 100644
--- a/src/java.base/share/classes/java/lang/foreign/Arena.java
+++ b/src/java.base/share/classes/java/lang/foreign/Arena.java
@@ -29,6 +29,7 @@
 import jdk.internal.ref.CleanerFactory;

 import java.lang.foreign.MemorySegment.Scope;
+import java.util.function.Consumer;

 /**
  * An arena controls the lifecycle of native memory segments, providing both flexible
@@ -317,8 +318,11 @@ static Arena ofShared() {
      * @throws WrongThreadException if this arena is confined, and this method is called
      *         from a thread other than the arena's owner thread
      * @throws UnsupportedOperationException if this arena cannot be closed explicitly
+     * @throws RuntimeException if an exception is thrown while executing a custom cleanup action
+     *                          associated with this arena (e.g. as a result of calling
+     *                          {@link MemorySegment#reinterpret(long, Arena, Consumer)} or
+     *                          {@link MemorySegment#reinterpret(Arena, Consumer)}).
      */
     @Override
     void close();
 }