Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8278145

Javadoc for MemorySegment::set/MemorySegment::setAtIndex is missing throws tag

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P3 P3
    • 18
    • core-libs
    • None
    • behavioral
    • low
    • The exception was already occurring - this change only affects the documentation.
    • Java API

      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

            mcimadamore Maurizio Cimadamore
            mcimadamore Maurizio Cimadamore
            Sundararajan Athijegannathan
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: