[foreign-memaccess+abi] RFR: 8291639: Improve the ability to visualize a MemorySegment in human readable forms [v8]
Athijegannathan Sundararajan
sundar at openjdk.org
Tue Aug 23 13:10:36 UTC 2022
On Tue, 23 Aug 2022 12:44:34 GMT, Per Minborg <duke 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).
>>
>> A public method in `MemorySegment`:
>>
>>
>> /**
>> * Returns a human-readable view of this memory segment viewed through
>> * the provided {@code layout}.
>> * <p>
>> * The format of the returned view is as follows:
>> * <ol>
>> * <li>tag/value pairs are separated with an "=" character.</li>
>> * <li>Each element is tagged with its {@link MemoryLayout#name()} or, if no name exists,
>> * its {@link MemoryLayout#toString()} representation.</li>
>> * <li> Values are rendered differently depending on their type:
>> * <ul>
>> * <li>Numeric values are rendered in decimal form (e.g 1 or 1.2).</li>
>> * <li>Boolean values are rendered as {@code true} or {@code false}.</li>
>> * <li>Character values are rendered as {@code char}.</li>
>> * <li>Address values are rendered in hexadecimal form e.g. {@code 0x0000000000000000}.</li>
>> * </ul>
>> * </li>
>> * <li>Values in a group layout are rendered with enclosing curly braces.</li>
>> * <li>Structure and sequence elements are separated with a "," character.</li>
>> * <li>Union elements are separated with a "|" character.</li>
>> * <li>Lines are separated with the system-dependent line separator {@link System#lineSeparator() }.</li>
>> * </ol>
>> * 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
>> * {@snippet lang = java:
>> * memorySegment.set(ValueLayout.JAVA_INT, 0, 1);
>> * memorySegment.set(ValueLayout.JAVA_INT, 4, 2);
>> *
>> * var layout = MemoryLayout.structLayout(
>> * ValueLayout.JAVA_INT.withName("x"),
>> * ValueLayout.JAVA_INT.withName("y")
>> * ).withName("Point");
>> *
>> * System.out.println(memorySegment.toString(layout));
>> *}
>> * will print:
>> * {@snippet lang = text:
>> * Point {
>> * x=1,
>> * y=2
>> * }
>> *}
>> *
>> * @param layout to use as a layout when viewing the memory segment
>> * @return a view of the memory segment viewed through a memory layout layout
>> * @throws OutOfMemoryError if the size of the UTF-8 string is greater than the largest string
>> * supported by the platform.
>> */
>> default String toString(MemoryLayout layout) {
>> Objects.requireNonNull(layout);
>> return MemorySegmentRenderUtil.toString(this, layout);
>> }
>>
>>
>> and an internal method (not exposed in the public API):
>>
>>
>> /**
>> * Returns a Stream of human-readable, lines with hexadecimal values for this memory segment.
>> * <p>
>> * Each element in the stream comprises the following characters:
>> * <ol>
>> * <li>an initial 64-bit offset (e.g. "0000000000000010").</li>
>> * <li>a sequence of two spaces (i.e. " ").</li>
>> * <li>a sequence of at most eight bytes (e.g. "66 6F 78 20 6A 75 6D 70") where
>> * each byte is separated by a space.</li>
>> * <li>a sequence of two spaces (i.e. " ").</li>
>> * <li>a sequence of at most eight bytes (e.g. "65 64 20 6F 76 65 72 20") where
>> * each byte separated by a space.</li>
>> * <li>a sequence of N spaces (i.e. " ") such that the intermediate line is aligned to 68 characters</li>
>> * <li>a "|" separator.</li>
>> * <li>a sequence of at most 16 printable Ascii characters (values outside [32, 127] will be printed as ".").</li>
>> * <li>a "|" separator.</li>
>> * </ol>
>> * All the values above are given in hexadecimal form with leading zeros. As there are at most 16 bytes
>> * rendered for each line, there will be N = ({@link MemorySegment#byteSize()} + 15) / 16 elements in the returned stream.
>> * <p>
>> * As a consequence of the above, this method renders to 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 segment = memorySession.allocate(64 + 4);
>> * segment.setUtf8String(0, "The quick brown fox jumped over the lazy dog\nSecond line\t:here");
>> * segment.hexDump()
>> * .forEach(System.out::println);
>> *}
>> * will be printed as:
>> * {@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.
>> * <p>
>> * This method can be used to dump the contents of various other memory containers such as
>> * {@linkplain ByteBuffer ByteBuffers} and byte arrays by means of first wrapping the container
>> * into a MemorySegment:
>> * {@snippet lang = java:
>> * MemorySegment.ofArray(byteArray).hexDump();
>> * MemorySegment.ofBuffer(byteBuffer).hexDump();
>> *}
>> *
>> * @param segment to inspect
>> * @return a Stream of human-readable, lines with hexadecimal values
>> */
>> public static Stream<String> hexDump(MemorySegment segment) {
>> ```
>>
>> and
>
> Per Minborg has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 10 commits:
>
> - Merge branch 'foreign-memaccess+abi' into render
> - Add ValueLayoutRenderer and fix issue
> - Add test
> - Change address output form and improve JavaDocs
> - Fix failing test and rename variables
> - Make dumpHex() internal and improve JavaDoc
> - Merge branch 'render' of https://github.com/minborg/panama-foreign into render
> - Merge branch 'foreign-memaccess+abi' into render
> - Update to reflect most initial PR comments
> - Add rendering of MemorySegments
test/jdk/java/foreign/RenderTest.java line 2:
> 1: /*
> 2: * Copyright (c) 2020, 2022, Oracle and/or its affiliates. All rights reserved.
new test. why 2020?
-------------
PR: https://git.openjdk.org/panama-foreign/pull/695
More information about the panama-dev
mailing list