RFR: 8308293: A linker should expose the layouts it supports [v3]

[Maurizio Cimadamore]

On Fri, 19 May 2023 22:20:32 GMT, Paul Sandoz <psandoz at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Address review comments
>>  - More javadoc tweaks
>
> src/java.base/share/classes/java/lang/foreign/Linker.java line 62:
> 
>> 60:  * </ul>
>> 61:  * A linker provides a way to lookup up the <em>canonical layouts</em> associated with the data types used by the ABI.
>> 62:  * For example, the canonical layout for the C {@code size_t} type is equal to {@link ValueLayout#JAVA_LONG}. The canonical
> 
> Suggestion:
> 
>  * For example, the canonical layout for the C {@code size_t} type is equal to {@link ValueLayout#JAVA_LONG} on 64-bit platforms. The canonical
> 
> ?

You are correct in calling this out. I think this should be spelled out more (similarly to what we do for default lookup) since we're still in the "general" linker section. E.g.


A linker provides a way to lookup up the <em>canonical layouts</em> associated with the data types used by the ABI.
For example, a linker implementing the C ABI might chose to provide a canonical layout for the C {@code size_t} type. On 64-bit platforms, this canonical layout might be equal to {@link ValueLayout#JAVA_LONG}. The canonical
layouts supported by a linker are exposed via the {@link #canonicalLayouts()} method, which returns a map from
ABI type names to canonical layouts.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14037#discussion_r1199485729