[foreign-memaccess+abi] RFR: 8291639: Improve the ability to visualize a MemorySegment in human readable forms [v12]
Per Minborg
duke at openjdk.org
Thu Aug 25 13:05:22 UTC 2022
> This PR improves the ability to visualize a `MemorySegment`, `ByteBuffer`, `byte[]` or any other memory abstraction in human-readable forms.
>
> It exposes two new methods via the new utility class `MemoryInspection` (and one of them indirectly via the `MemorySegment::toString` method).
>
> A public method `MemoryInspection::toString` (also exposed via `MemorySegment::toString`) :
>
>
> /**
> * 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) {
>
>
>
> and `MemoryInspection::hexDump`:
>
>
> /**
> * Returns a Stream of human-readable, lines with hexadecimal values for the provided
> * {@code memory} abstraction. The memory abstraction can be of arbitrary type.
> * <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 = ({@code adapter.length(memory)} + 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 created, initialized and used as follows
> * {@snippet lang = java:
> * MemorySegment memory = memorySession.allocate(64 + 4);
> * memory.setUtf8String(0, "The quick brown fox jumped over the lazy dog\nSecond line\t:here");
> * MemoryInspection.hexDump(memory, Adapter.ofMemorySegment())
> * .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} or similar memory slicing capabilities to
> * inspect a specific region of a memory.
> * <p>
> * This method can be used to directly dump the contents of various other memory abstractions such as
> * {@linkplain ByteBuffer ByteBuffers} and byte arrays:
> * {@snippet lang = java:
> * MemoryInspection.hexDump(byteArray, Adapter.ofByteArray());
> * MemoryInspection.hexDump(byteBuffer, Adapter.ofByteBuffer());
> *}
> *
> * @param memory the memory abstraction to inspect.
> * @param adapter to apply to the provided memory to determine the size and content of the memory abstraction.
> * @param <M> the memory abstraction type.
> * @return a Stream of human-readable, lines with hexadecimal values
> * @throws RuntimeException depending on the provided extractors whose exceptions will be relayed to the
> * call site.
> */
> public static <M> Stream<String> hexDump(M memory,
> Adapter<M> adapter) {
> ```
>
> 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 19 commits:
- 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
- Fix copyright date
- Cleanup test
- Merge branch 'foreign-memaccess+abi' into render
- ... and 9 more: https://git.openjdk.org/panama-foreign/compare/8f8f03c7...01a44361
-------------
Changes: https://git.openjdk.org/panama-foreign/pull/695/files
Webrev: https://webrevs.openjdk.org/?repo=panama-foreign&pr=695&range=11
Stats: 1116 lines in 6 files changed: 1108 ins; 2 del; 6 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