FunctionDescriptor::toMethodType should allow sequence layouts (mainline)

Summary

FunctionDescriptor should not make too many assumptions on how linkers might use it.

Problem

The FunctionDescriptor class provides a method (namely FunctionDescriptor::toMethodType) which is used to map a function descriptor to a MethodType. This mapping is specified to throw if the function descriptor contains any sequence layout. That is, the mapping is currently biased towards what the native linker can actually support. While in C passing arrays by value does not make sense, other languages (such as Pascal) might allow it. It should be up to the linker, and not to the function descriptor, to reject invalid combinations.

Solution

As part of this CSR, we propose the following API changes:

• FunctionDescriptor::toMethodType is changed to allow sequence layouts (and using MemorySegment as corresponding carrier type);
• FunctionDescriptor::of and FunctionDescriptor::ofVoid are changed to eagerly reject function descriptor creation with a padding layout argument/return (as that doesn't make any sense in any linker).
• Adapter methods in FunctionDescriptor are also tweaked to specify that e.g. changing a return layout might throw (if such a layout is a padding layout).

Specification

Below is the javadoc of the affected methods (Note: the main change is in FunctionDescriptor::toMethodType. Other methods are changed to document that IllegalArgumentException will be thrown on padding layout arguments):

    /**
     * Returns a function descriptor with the given argument layouts appended to the argument layout array
     * of this function descriptor.
     * @param addedLayouts the argument layouts to append.
     * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout.
     * @return the new function descriptor.
     */
    FunctionDescriptor appendArgumentLayouts(MemoryLayout... addedLayouts);

    /**
     * Returns a function descriptor with the given argument layouts inserted at the given index, into the argument
     * layout array of this function descriptor.
     * @param index the index at which to insert the arguments
     * @param addedLayouts the argument layouts to insert at given index.
     * @return the new function descriptor.
     * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout.
     * @throws IllegalArgumentException if {@code index < 0 || index > argumentLayouts().size()}.
     */
    FunctionDescriptor insertArgumentLayouts(int index, MemoryLayout... addedLayouts);

    /**
     * Returns a function descriptor with the given memory layout as the new return layout.
     * @param newReturn the new return layout.
     * @throws IllegalArgumentException if {@code newReturn} is a padding layout.
     * @return the new function descriptor.
     */
    FunctionDescriptor changeReturnLayout(MemoryLayout newReturn);

    /**
     * Returns the method type consisting of the carrier types of the layouts in this function descriptor.
     * <p>
     * The carrier type of a layout is determined as follows:
     * <ul>
     * <li>If the layout is a {@link ValueLayout} the carrier type is determined through {@link ValueLayout#carrier()}.</li>
     * <li>If the layout is a {@link GroupLayout} or a {@link SequenceLayout}, the carrier type is {@link MemorySegment}.</li>
     * </ul>
     *
     * @apiNote A function descriptor cannot, by construction, contain any padding layouts. As such, it is not
     * necessary to specify how padding layout should be mapped to carrier types.
     *
     * @return the method type consisting of the carrier types of the layouts in this function descriptor
     * @throws IllegalArgumentException if one or more layouts in the function descriptor can not be mapped to carrier
     *                                  types (e.g. if they are sequence layouts or padding layouts).
     */
    MethodType toMethodType();

    /**
     * Creates a function descriptor with the given return and argument layouts.
     * @param resLayout the return layout.
     * @param argLayouts the argument layouts.
     * @throws IllegalArgumentException if {@code resLayout} is a padding layout.
     * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout.
     * @return the new function descriptor.
     */
    static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argLayouts) { ... }

    /**
     * Creates a function descriptor with the given argument layouts and no return layout.
     * @param argLayouts the argument layouts.
     * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout.
     * @return the new function descriptor.
     */
    static FunctionDescriptor ofVoid(MemoryLayout... argLayouts) { ... }