Summary

Replace usages of IllegalStateException with WrongThreadException in java.lang.foreign.

Problem

A number of API points in java.lang.foreign throws IllegalStateException when called from the wrong thread, that is, these API points support the notion of thread-confinement.

This is suboptimal, because some of the methods involved can already throw IllegalStateException for a different reason (e.g. if a segment is accessed when its underlying session has already been closed). This makes it cumbersome for clients to analyze why a call to a thread-confined method has failed, as this can only be done by processing the String message attached to the exception.

Solution

As part of the support for virtual threads, a new exception has been added to the Java SE API, namely WrongThreadException. This exception will be used by the incubating StructuredTaskScope API.

As such, it seems apt for the API in java.lang.foreign to also use WrongThreadException to denote failures associated with thread-confinement.

Specification

Consider this method in java.lang.foreign:

    /**
     * Reads a byte at the given offset from this segment, with the given layout.
     *
     * @param layout the layout of the memory region to be read.
     * @param offset offset in bytes (relative to this segment). For instance, if this segment is a {@linkplain #isNative() native} segment,
     *               the final address of this read operation can be expressed as {@code address().toRowLongValue() + offset}.
     * @return a byte value read from this address.
     * @throws IllegalStateException if the {@linkplain #session() session} associated with this segment is not
     * {@linkplain MemorySession#isAlive() alive}, or if access occurs from a thread other than the thread owning that session.
     * @throws IllegalArgumentException if the dereference operation is
     * <a href="MemorySegment.html#segment-alignment">incompatible with the alignment constraints</a> in the provided layout.
     * @throws IndexOutOfBoundsException when the dereference operation falls outside the <em>spatial bounds</em> of the
     * memory segment.
     */
    @ForceInline
    default byte get(ValueLayout.OfByte layout, long offset) {
        return (byte)layout.accessHandle().get(this, offset);
    }

We propose to tweak the Javadoc as follows:

    /**
     * Reads a byte at the given offset from this segment, with the given layout.
     *
     * @param layout the layout of the memory region to be read.
     * @param offset offset in bytes (relative to this segment). For instance, if this segment is a {@linkplain #isNative() native} segment,
     *               the final address of this read operation can be expressed as {@code address().toRowLongValue() + offset}.
     * @return a byte value read from this address.
     * @throws IllegalStateException if the {@linkplain #session() session} associated with this segment is not
     * {@linkplain MemorySession#isAlive() alive}.
     * @throws WrongThreadException if this method is called from a thread other than the thread owning
     * the {@linkplain #session() session} associated with this segment.
     * @throws IllegalArgumentException if the dereference operation is
     * <a href="MemorySegment.html#segment-alignment">incompatible with the alignment constraints</a> in the provided layout.
     * @throws IndexOutOfBoundsException when the dereference operation falls outside the <em>spatial bounds</em> of the
     * memory segment.
     */
    @ForceInline
    default byte get(ValueLayout.OfByte layout, long offset) {
        return (byte)layout.accessHandle().get(this, offset);
    }

A javadoc including the proposed changes can be found here:

http://cr.openjdk.java.net/~mcimadamore/8287206/v1/javadoc/java.base/module-summary.html

A specdiff including the proposed changes can be found here:

http://cr.openjdk.java.net/~mcimadamore/8287206/v1/specdiff_out/overview-summary.html

Both are attached in this CSR (see v1.zip).