[foreign-memaccess+abi] RFR: Add support for high-level functions to copy to and from Java arrays [v5]

[Lee Rhodes]

On Thu, 24 Jun 2021 10:07:23 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This patch includes some of the changes from Lee to support a set of static functions to allow bulk copy from Java arrays to segments (and viceversa) in a more succint fashion (so that the user doesn't have to create a temporary heap segment to do the copy).
>> 
>> I've added a new public method to `MemorySegment` which performs an *element-wise* bulk copy; it takes a source segment and a couple of element layouts: the source element layout and the destination element layout. The two layouts must have same size, but can have different alignments (which will be checked against the corresponding segments) and byte orders. If the byte order differs, a bulk copy with swap will be performed. As such, this method generalizes the previous `copyFrom` - as follows:
>> 
>> 
>> copyFrom(srcSegment) -> copyFrom(JAVA_BYTE, srcSegment, JAVA_BYTE)
>> 
>> I've added support for argument type profiling for MemoryCopy static methods to avoid type pollution in cases where same metod is called with different memory segment types.
>> 
>> I've done a pass over the javadoc, and make it more consistent with the rest of the API. I've also reworked the test a bit to use the data provider functionality of TestNG, since all the test cases were similar, except for the carrier type.
>> 
>> There are other cosmetic changes as well, compared to original code from Lee, such as naming of static fields which is now capitalized. Everything else is the same.
>
> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
> 
>   * Add null checks for ByteOrder
>   * Beef up test to check for various OOB conditions

The conceptual model I had in mind when I proposed this API was that it seemed sensible to order the parameters first by the data flow: {source parameters, destination parameters}, then by {Object, offset, length} with ByteOrder stuck at the end. Thus:

- copyToArray(srcSegment, srcOffsetBytes, dstArray, dstIndexChars, dstCopyLengthChars, order);
- copyFromArray(srcArray, srcIndexChars, srcCopyLengthChars, dstSegment, dstOffsetBytes, order);

But this is by no means the only mental model we could use as this {source, destination} flow model is not consistently followed even within the current FMA API.

As an alternative, we could use the conceptual model of {segment parameters, array parameters}. Thus:

- copyToArray(srcSegment, srcOffsetBytes, dstArray, dstIndexChars, dstCopyLengthChars, order);
- copyFromArray(dstSegment, dstOffsetBytes, srcArray, srcIndexChars, srcCopyLengthChars, order);

For the user, this model has the parameters by type always in the same order, the length (and order) are at the end, and because of that the prefixes for the copy length could probably be dropped.  But I would prefer to keep the other prefixes as they are as additional cues to the user of the flow direction as well as association.

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

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