Summary

Derefrence methods such as MemorySegment::set and MemorySegment::setAtIndex should be documented to throw UnsupportedOperationException if the memory segment is read-only.

Problem

The MemorySegment API allows the creation of so called read-only views (see MemorySegment::asReadOnly) - segments that can be read but not written. When attempting to write a value into a read-only view using MemorySegment::set or MemorySegment::setAtIndex, the underlying VarHandle access logic throws an UnsupportedOperationException, which is not documented in the javadoc.

Solution

The javadoc should document the exception that can arise when attempting to write to a read-only segment.

Specification

Below is a link to revised javadoc and specdiff (as of Dec, 2nd 2021):

Javadoc: http://cr.openjdk.java.net/~mcimadamore/8278144/v1/javadoc/jdk/incubator/foreign/package-summary.html

Specdiff: http://cr.openjdk.java.net/~mcimadamore/8278144/v1/spec_diff/overview-summary.html