[foreign-memaccess+abi] RFR: 8264933: Improve stream support in memory segments

[Paul Sandoz]

On Thu, 8 Apr 2021 15:56:32 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch improves stream support for memory segments - it does so in two ways:
> 
> * first, tweaking the `MemorySegment::spliterator` method to take an *element layout*, instead of a full sequence layout whose size had to match that of the segment.
> * secondly, by adding convenience methods to create streams directly, w/o needing to call `StreamSupport.stream`. As for `Collection`, two methods are provided: `MemorySegment::stream` and `MemorySegment::parallelStream`.
> 
> I've fixed up the documentation in places - I realized that, for example, the javadoc for `MemorySegment::spliterator` was missing a `@throws` clause for when there's a size mismatch between layout and segment.
> Also, I've removed scope liveness check on the spliterator call - after all, a spliterator is going to make slices - a liveness check will occur when the slice is accessed.

Marked as reviewed by psandoz (Committer).

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 183:

> 181:     /**
> 182:      * Returns a sequential {@code Stream} over disjoint slices (whose size matches that of the specified layout)
> 183:      * in this segment. Calling this method is equivalent to the following code:

The equivalent text could be converted to an API note.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 185:

> 183:      * in this segment. Calling this method is equivalent to the following code:
> 184:      * <blockquote><pre>{@code
> 185:     StreamSupport.stream(segment.spliterator(), false);

Suggestion:

    StreamSupport.stream(segment.spliterator(elementLayout), false);

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 192:

> 190:      * @throws IllegalArgumentException if this segment size is not a multiple of the size of {@code elementLayout}.
> 191:      */
> 192:     Stream<MemorySegment> stream(MemoryLayout elementLayout);

Renaming to `elements` could also work.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java line 205:

> 203:      * @throws IllegalArgumentException if this segment size is not a multiple of the size of {@code elementLayout}.
> 204:      */
> 205:     Stream<MemorySegment> parallelStream(MemoryLayout elementLayout);

I don't think we need this method. Except for collections we generally don't use this pattern, and instead encourage the use of `Stream.parallel()` in such cases.

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

PR: https://git.openjdk.java.net/panama-foreign/pull/494