RFR: 8298095: Refine implSpec for SegmentAllocator [v4]

[Maurizio Cimadamore]

On Tue, 8 Aug 2023 08:35:51 GMT, Per Minborg <pminborg at openjdk.org> wrote:

>> This PR suggests refining the `@implSpec` for the SegmentAllocator::allocate methods as well as clarifying the docs a bit more. Also, a local variable is renamed.
>
> Per Minborg has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains seven additional commits since the last revision:
> 
>  - Add snippet for MS::allocateArray methods
>  - Merge branch 'master' into segallocjavadoc
>  - Simplify snippets
>  - Update after comments
>  - Update array methods
>  - Improve javadocs
>  - Update javadocs for SegmentAllocator::allocate methods

Looks good.

src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java line 352:

> 350:      *  int size = Objects.requireNonNull(elements).length;
> 351:      *  MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size);
> 352:      *  MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0,

there's overloads for copy which accepts the array directly too - so no need to wrap the array into an heap segments - that should simplify the snippet some more

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

Marked as reviewed by mcimadamore (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/14997#pullrequestreview-1570211102
PR Review Comment: https://git.openjdk.org/jdk/pull/14997#discussion_r1288945094