[foreign-memaccess+abi] RFR: 8291639: Improve the ability to visualize a MemorySegment in human readable forms [v7]
Per Minborg
duke at openjdk.org
Tue Aug 23 12:39:47 UTC 2022
> 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 incrementally with one additional commit since the last revision:
Add ValueLayoutRenderer and fix issue
-------------
Changes:
- all: https://git.openjdk.org/panama-foreign/pull/695/files
- new: https://git.openjdk.org/panama-foreign/pull/695/files/a6bbd55b..ea9bd822
Webrevs:
- full: https://webrevs.openjdk.org/?repo=panama-foreign&pr=695&range=06
- incr: https://webrevs.openjdk.org/?repo=panama-foreign&pr=695&range=05-06
Stats: 392 lines in 4 files changed: 298 ins; 37 del; 57 mod
Patch: https://git.openjdk.org/panama-foreign/pull/695.diff
Fetch: git fetch https://git.openjdk.org/panama-foreign pull/695/head:pull/695
PR: https://git.openjdk.org/panama-foreign/pull/695
More information about the panama-dev
mailing list