[foreign-memaccess+abi] RFR: 8292034: Improve javadoc after memory segment/memory address unification

[Gavin Ray]

Wow, that is fantastic!

Thanks to all involved for documenting that

On Wed, Sep 21, 2022 at 7:31 AM Maurizio Cimadamore <
maurizio.cimadamore at oracle.com> wrote:

> Please look at the new linked javadoc:
>
>
> http://cr.openjdk.java.net/~mcimadamore/panama/memory_segment_refresh_javadoc/javadoc/java.base/java/lang/foreign/MemorySegment.html#segment-alignment
>
> The section has been reworked big time, and a lot of new examples (both on
> what alignment _means_ and on how clients are supposed to work with it)
> have been added.
>
> As for referencing javadoc sections from exception messages, I'm not sure
> there is any precedent in other JDK APIs.
>
> Maurizio
> On 21/09/2022 12:21, Gavin Ray wrote:
>
> Maurizio, while the area of docs in MemorySegment is being worked on,
> could it make sense to include a section on memory alignment?
>
> (It may be out of scope)
>
> But for example, not knowing much about low-level programming I tried to
> do some basic things with Foreign Memory and got "misaligned access" errors:
>
> https://stackoverflow.com/questions/73430301/java-foreign-memory-varhandlesegmentviewbase-error-misaligned-access-at-addr
>
> If the error message included something like:
> "See the Javadoc on MemorySegment#foo to understand alignment"
>
> And then there was a brief explainer somewhere about how memory alignment
> works for newbies
>
> I think that would save a lot of pain for folks.
>
>
> On Wed, Sep 21, 2022 at 6:54 AM Maurizio Cimadamore <
> mcimadamore at openjdk.org> wrote:
>
>> On Wed, 21 Sep 2022 10:47:07 GMT, Maurizio Cimadamore <
>> mcimadamore at openjdk.org> wrote:
>>
>> > This is a rather big patch which overhauls the javadoc of the
>> `MemorySegment` class.
>> > A big thanks to Alex Buckley, who helped review the API javadoc and
>> contributed many of the changes you see here.
>> >
>> > The main things touched in this PR are:
>> >
>> > * the section on unsafe segments is gone from the package-level
>> javadoc. In its place, there's a new section on zero-length memory segments
>> in the `MemorySegment` javadoc
>> > * the class javadoc for `MemorySegment` has been overhauled greatly. It
>> now focusses on two kinds of segments (native segments, and heap segments)
>> and define how address, size, alignment of both is handled by the API.
>> > * we introduce a distinction between memory segment and "the region of
>> memory" which backs the segment, which helps spelling out a lot of these
>> properties in a cleaner way
>> > * perhaps the biggest change in the javadoc is the section on memory
>> segment alignment, which now is much more clearly defined, and provides
>> lots of examples (as that's a complex topic).
>> > * some of the javadoc, in both this class and other classes have been
>> tweaked to reflect the new terminology (for instance, references to the
>> term `base address` are gone)
>> >
>> > Other javadoc changes might follow, at some point later. The `Linker`
>> class might need some attention, as we don't really spell out how
>> zero-length segments interacts with downcalls and upcalls.
>> > But, given the size of the changes, I'd rather deal with that
>> separately.
>>
>> Rather than looking at code changes, it might be perhaps more valuable to
>> look at the javadoc, here:
>>
>> http://cr.openjdk.java.net/~mcimadamore/panama/memory_segment_refresh_javadoc/javadoc/java.base/module-summary.html
>>
>> -------------
>>
>> PR: https://git.openjdk.org/panama-foreign/pull/730
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/panama-dev/attachments/20220921/48475556/attachment.htm>