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

[Per Minborg]

On Wed, 31 Aug 2022 12:32:14 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 with a new target base due to a merge or a rebase. The pull request now contains 22 commits:
> 
>  - Add dump method to HexFormat
>  - Merge branch 'foreign-memaccess+abi' into render
>  - Rollback unintended reformatting
>  - MemoryInspect to return Stream of Strings
>  - Cleanup
>  - Remove/simplify some methods and overloads
>  - Add MemorySegment support to HexFormat and remove old public hex feature
>  - Merge remote-tracking branch 'origin/foreign-memaccess+abi' into render
>  - Rename and add Adapter.ofIntArray
>  - Add general MemoryInspection
>  - ... and 12 more: https://git.openjdk.org/panama-foreign/compare/3e4879f8...7037f8b9

Should we have a util class `MemoryInspection` with a single static method or should we add this method to `MemorySegment` itself (e.g. segment.toString(layout, renderer))?

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

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