[foreign-memaccess+abi] RFR: 8270376: Finalize API for memory copy [v10]

[Maurizio Cimadamore]

On Mon, 9 Aug 2021 10:47:41 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This patch ties up some loose ends with the MemoryCopy API, and it also prepares the ground for some other related refactorings in this area.
>> 
>> The meat of this patch is represented by the various changes in MemoryCopy, where all methods were renamed to simply `copy`, and the length parameter (now called `elementCount`) is always moved to the end.
>> 
>> I've also simplified naming of parameters, as I think distinguishing between `index` and `offset` is enough (e.g. an array has an index, a segment has an offset).
>> 
>> You will see that, at the very end of the class, three more copy methods have been added, which deal fully in terms of segments. I have also moved the complex layout-based memory segment copy operation (which does the swap) as a static method in this class, as I believe the static form makes the method more regular and usable.
>> 
>> I've made some changes to our uses of `copyFrom` in the linker, to use the new methods in `MemoryCopy` when the copy operation was performing slicing in the source/target segment, which I think makes the code more readable. Of course these changes are completely optional and could be omitted as well.
>
> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Leave only one copyFrom method (as in Java 17).
>   Add back remaining copy method as statics.

In the end, I've decided to:

* only leave one `copyFrom` method taking a segment - this is a version that is friendly with slicing
* leave the toXYZArray - again these methods are friendly with slicing
* add back remaining segment copy method as statics, as I think the instance declaration makes order of argument harder to parse, and using System::arrayCopy-like parameter order is cleaner for more complex copies.

I believe this strikes a good balance. Copy operations are common enough that some special casing in the API is required - even though that comes at a slight cost in terms of API uniformity.

I also decided to leave `fill` where it is - while in some cases I'm able to see better performances with a straight loop and dereference, performance seem to be more fragile - especially as, in the general case, we have to take into account segment sizes that exceed `Integer.MAX_VALUE`.

Javadoc updated inline here:
http://cr.openjdk.java.net/~mcimadamore/panama/memorycopy_finalize_javadoc/javadoc/jdk/incubator/foreign/package-summary.html

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

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