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

[Roger Riggs]

On Wed, 31 Aug 2022 13:03:00 GMT, Per Minborg <duke at openjdk.org> wrote:

>> This PR improves the ability to visualize a `MemorySegment` in human-readable forms (`ByteBuffer`, `byte[]` or any other memory abstraction can be viewed by means of wrapping).
>> 
>> It exposes a new method via the new utility class `MemoryInspection`
>> 
>> 
>>     /**
>>      * Returns a human-readable view of the provided {@code memory} abstraction by optionally
>>      * (if not a {@link MemorySession} and {@link Adapter#ofMemorySegment()} already) copying the contents
>>      * to a fresh MemorySegment and then view the resulting MemorySegment through the provided {@code layout}.
>>      * <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 MemorySegment viewed though the following memory layout
>>      * {@snippet lang = java:
>>      * var layout = 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 abstractions through small and medium-sized memory layouts.
>>      *
>>      * @param memory   to be viewed
>>      * @param adapter  to apply to the provided memory to determine the size and content of the memory abstraction.
>>      * @param layout   to use as a layout when viewing the memory segment
>>      * @param renderer to apply when rendering value layouts
>>      * @param <M>      the memory abstraction type.
>>      * @return a view of the memory abstraction viewed through the memory layout
>>      * @throws OutOfMemoryError if the view exceeds the array size VM limit
>>      */
>>     public static <M> String toString(M memory,
>>                                       Adapter<M> adapter,
>>                                       MemoryLayout layout,
>>                                       ValueLayoutRenderer renderer) {
>>                                       
>> 
>> 
>> the existing `HexFormat` class will also get two overloads for MemorySegments as well as a new static `dump(segment)` method that can be used to generate hex dumps like:
>> 
>> 
>> 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                                       |....|
>> 
>> Again, other memory abstractions like ByteBuffer and byte arrays can be dumped by first wrapping them into a `MemorySegment`.
>
> Per Minborg has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix errors in JavaDoc

The fixed format and function of dump() doesn't fit with the existing methods of HexFormat.
The methods of HexFormat should provide basic building blocks related to hex encoding and decoding.

The `formatHex(MemorySegment)` and `formatHex(Appendable, MemorySegment)` are ok.

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

Changes requested by rriggs (no project role).

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