<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
<p>Please look at the new linked javadoc:</p>
<p><a class="moz-txt-link-freetext" href="http://cr.openjdk.java.net/~mcimadamore/panama/memory_segment_refresh_javadoc/javadoc/java.base/java/lang/foreign/MemorySegment.html#segment-alignment">http://cr.openjdk.java.net/~mcimadamore/panama/memory_segment_refresh_javadoc/javadoc/java.base/java/lang/foreign/MemorySegment.html#segment-alignment</a></p>
<p>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.</p>
<p>As for referencing javadoc sections from exception messages, I'm
not sure there is any precedent in other JDK APIs.<br>
</p>
<p>Maurizio<br>
</p>
<div class="moz-cite-prefix">On 21/09/2022 12:21, Gavin Ray wrote:<br>
</div>
<blockquote type="cite" cite="mid:CAFtvWZPTn_xaDgoj-hZXcjr5bpuPBS_Pi7N-Dv9d-CQixjZjAw@mail.gmail.com">
<div dir="ltr">Maurizio, while the area of docs in MemorySegment
is being worked on, could it make sense to include a section on
memory alignment?
<div><br>
</div>
<div>(It may be out of scope)</div>
<div><br>
</div>
<div>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:</div>
<div><a href="https://stackoverflow.com/questions/73430301/java-foreign-memory-varhandlesegmentviewbase-error-misaligned-access-at-addr" moz-do-not-send="true" class="moz-txt-link-freetext">https://stackoverflow.com/questions/73430301/java-foreign-memory-varhandlesegmentviewbase-error-misaligned-access-at-addr</a><br>
</div>
<div><br>
</div>
<div>If the error message included something like:</div>
<div>"See the Javadoc on MemorySegment#foo to understand
alignment"</div>
<div><br>
</div>
<div>And then there was a brief explainer somewhere about how
memory alignment works for newbies</div>
<div><br>
</div>
<div>I think that would save a lot of pain for folks.</div>
<div><br>
</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Wed, Sep 21, 2022 at 6:54
AM Maurizio Cimadamore <<a href="mailto:mcimadamore@openjdk.org" moz-do-not-send="true" class="moz-txt-link-freetext">mcimadamore@openjdk.org</a>>
wrote:<br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px
0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On
Wed, 21 Sep 2022 10:47:07 GMT, Maurizio Cimadamore <<a href="mailto:mcimadamore@openjdk.org" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">mcimadamore@openjdk.org</a>>
wrote:<br>
<br>
> This is a rather big patch which overhauls the javadoc of
the `MemorySegment` class.<br>
> A big thanks to Alex Buckley, who helped review the API
javadoc and contributed many of the changes you see here.<br>
> <br>
> The main things touched in this PR are:<br>
> <br>
> * 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<br>
> * 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.<br>
> * 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<br>
> * 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).<br>
> * 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)<br>
> <br>
> 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.<br>
> But, given the size of the changes, I'd rather deal with
that separately.<br>
<br>
Rather than looking at code changes, it might be perhaps more
valuable to look at the javadoc, here:<br>
<a href="http://cr.openjdk.java.net/~mcimadamore/panama/memory_segment_refresh_javadoc/javadoc/java.base/module-summary.html" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">http://cr.openjdk.java.net/~mcimadamore/panama/memory_segment_refresh_javadoc/javadoc/java.base/module-summary.html</a><br>
<br>
-------------<br>
<br>
PR: <a href="https://git.openjdk.org/panama-foreign/pull/730" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://git.openjdk.org/panama-foreign/pull/730</a><br>
</blockquote>
</div>
</blockquote>
</body>
</html>