[foreign-memaccess+abi] RFR: 8311533: SegmentAllocator::allocateArray call can be ambiguous [v2]

[Maurizio Cimadamore]

> This PR updates the name of some methods in the SegmentAllocator interface. As discussed in [1], the current naming scheme suffers from the following ambiguity:
> 
> allocator.allocateArray(JAVA_LONG, 3);
> 
> 
> This callsite actually matches two signatures:
> 
> * `allocateArray(MemoryLayout, long)`
> * `allocateArray(ValueLayout.OfLong, long...)`
> 
> Since the former is non-variadic, it is preferred. Note how the semantics of these two methods is completely different - the former allocates a segment that can store N longs (where N is the parameter being passed). The latter allocates a segment that is big enough to hold the provided array.
> 
> So, in the case of the above call, the first method would allocate 8 * 3 = 24 bytes, whereas the latter would only allocate 8 bytes.
> 
> To rectify this, we started from the observation that a call like:
> 
> 
> allocator.allocate(JAVA_LONG, 3);
> 
> 
> Will probably be intuitively associated with a calloc where the element size is 8 and the element count is 3 (e.g. request to allocate 24 bytes). So:
> 
> * `allocateArray(MemoryLayout, long)` has been renamed to just `allocate(MemoryLayout, long)`.
> * all the allocation methods that allocate some segment and initialize it to some provided value (which could be an array or a single value) are renamed from `allocate`/`allocateArray` to just `allocateFrom`.
> 
> I think this naming scheme is more robust, and less surprising. While there are still multiple candidates in a call like this:
> 
> 
> allocator.allocateFrom(JAVA_LONG, 3);
> 
> 
> Now all the candidates are semantically equivalent (allocate 8 bytes and stick the value `3` in it), and overload resolution would pick the variant that has less overhead, which is what we want.
> 
> There's an open question (which I have not addressed, and I'd like feedback on) as to whether the two `allocateString` methods should also be renamed to `allocateFrom`, since they also allocate a segment from a provided value. This would make naming more consistent (currently, the two `allocateString` methods stick out a little bit when staring at the javadoc).

Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:

  Consolidate naming for SegmentAllocator::allocateString

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

Changes:
  - all: https://git.openjdk.org/panama-foreign/pull/845/files
  - new: https://git.openjdk.org/panama-foreign/pull/845/files/a0283955..3e0d6780

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=panama-foreign&pr=845&range=01
 - incr: https://webrevs.openjdk.org/?repo=panama-foreign&pr=845&range=00-01

  Stats: 28 lines in 9 files changed: 0 ins; 0 del; 28 mod
  Patch: https://git.openjdk.org/panama-foreign/pull/845.diff
  Fetch: git fetch https://git.openjdk.org/panama-foreign.git pull/845/head:pull/845

PR: https://git.openjdk.org/panama-foreign/pull/845