[foreign-memaccess+abi] RFR: 8291639: Improve the ability to visualize a MemorySegment in human readable forms

[Per-Åke Minborg]

On Tue, 2 Aug 2022 15:35:36 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This PR imrproves the ability to visualize a `MemorySegment` in human-readable forms.
>> 
>> It exposes two new methods by adding them directly to the MemorySegment interface. There are other ways to add the methods (e.g. by exposing them via a utility class).
>> 
>> The methods
>> 
>> 
>>     /**
>>      * Returns a Stream of human-readable, lines with hexadecimal values for this memory segment.
>>      * <p>
>>      * The exact format of the stream elements is unspecified and should not
>>      * be acted upon programmatically. Loosely speaking, this method renders
>>      * a format similar to the *nix command "hexdump -C".
>>      * <p>
>>      * As an example, a memory segment created, initialized and used as follows
>>      * {@snippet lang = java:
>>      * MemorySegment memorySegment = memorySession.allocate(64 + 4);
>>      * memorySegment.setUtf8String(0, "The quick brown fox jumped over the lazy dog\nSecond line\t:here");
>>      * memorySegment.hexStream()
>>      *     .forEach(System.out::println);
>>      *}
>>      * might print to something like this:
>>      * {@snippet lang = text:
>>      * 0000000000000000  54 68 65 20 71 75 69 63  6B 20 62 72 6F 77 6E 20  |The quick brown |
>>      * 0000000000000010  66 6F 78 20 6A 75 6D 70  65 64 20 6F 76 65 72 20  |fox jumped over |
>>      * 0000000000000020  74 68 65 20 6C 61 7A 79  20 64 6F 67 0A 53 65 63  |the lazy dog.Sec|
>>      * 0000000000000030  6F 6E 64 20 6C 69 6E 65  09 3A 68 65 72 65 00 00  |ond line.:here..|
>>      * 0000000000000040  00 00 00 00                                       |....|
>>      *}
>>      * <p>
>>      * Use a {@linkplain MemorySegment#asSlice(long, long) slice} to inspect a specific region
>>      * of a memory segment.
>>      *
>>      * @return a Stream of human-readable, lines with hexadecimal values
>>      */
>>      default Stream<String> hexStream() {
>>         return MemorySegmentRenderUtil.hexStream(this);
>>     }
>> ``` 
>> 
>> and
>> 
>> 
>>     /**
>>      * Returns a human-readable view of this memory segment viewed through
>>      * the provided memory layout {@code lens}.
>>      * <p>
>>      * Lines are separated with the system-dependent line separator {@link System#lineSeparator() }.
>>      * Otherwise, the exact format of the returned view is unspecified and should not
>>      * be acted upon programmatically.
>>      * <p>
>>      * As an example, a memory segment viewed though the following memory layout lens
>>      * {@snippet lang = java:
>>      * var lens = MemoryLayout.structLayout(
>>      *         ValueLayout.JAVA_INT.withName("x"),
>>      *         ValueLayout.JAVA_INT.withName("y")
>>      * ).withName("Point");
>>      *}
>>      * might be rendered to something like this:
>>      * {@snippet lang = text:
>>      * Point {
>>      *   x=1,
>>      *   y=2
>>      * }
>>      *}
>>      * <p>
>>      * This method is intended to view memory segments through small and medium-sized memory layout
>>      * lenses and is, in all cases, restricted by the inherent String capacity limit.
>>      *
>>      * @param lens  to use as a lens when viewing the memory segment
>>      * @return a view of the memory segment viewed through a memory layout lens
>>      * @throws OutOfMemoryError if the view exceeds the array size VM limit
>>      */
>>     default String viewThrough(MemoryLayout lens) {
>>         Objects.requireNonNull(lens);
>>         return MemorySegmentRenderUtil.viewThrough(this, lens);
>>     }
>
> src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 1903:
> 
>> 1901:      * @return a Stream of human-readable, lines with hexadecimal values
>> 1902:      */
>> 1903:     default Stream<String> hexStream() {
> 
> I think `hexDump` or `hexDumpStream` would be a better name

I think it is possible to specify the `hexDump()` method in detail and also make it more general so it can be applied to virtually any memory representation such as `byte[]` or `ByteBuffer`.

> src/java.base/share/classes/java/lang/foreign/PaddingLayout.java line 38:
> 
>> 36:  * This class is immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
>> 37:  */
>> 38: public final class PaddingLayout extends AbstractLayout implements MemoryLayout {
> 
> I don't think this change should be part of this patch. Whether that's something we want o pursue, it's an orthogonal question (e.g. to make use of pattern matching more nice).

We can re-write the check using a replacement for `instanceof` and revert the PaddingLayout change.

> src/java.base/share/classes/jdk/internal/foreign/MemorySegmentRenderUtil.java line 207:
> 
>> 205:         if (memoryLayout instanceof GroupLayout groupLayout) {
>> 206: 
>> 207:             // Strictly, we should provide all permutations of nested unions.
> 
> Not sure I get this comment

So, suppose there is a nested union such that: U = (A|B)|(C|D). Then the actual layout U could be either of AC, AD, BC or BD. Hence, we could present all these combinations.

> src/java.base/share/classes/jdk/internal/foreign/MemorySegmentRenderUtil.java line 262:
> 
>> 260:     }
>> 261: 
>> 262:     static final class HexStreamState {
> 
> While this class is simple - I note that there are many others hex utils in the JDK like src/java.base/share/classes/sun/security/util/HexDumpEncoder.java

True. This class operates on input/output streams and so there is an impedance mismatch. But it would be possible to use it via an adaptor.

-------------

PR: https://git.openjdk.org/panama-foreign/pull/695