Package Summary Overview Summary

Module java.base
Package java.lang.foreign

# Class FunctionDescriptor

java.lang.Object
java.lang.foreign.FunctionDescriptor

public sealed class FunctionDescriptor extends Object
`FunctionDescriptor` is a preview API of the Java platform.
Programs can only use `FunctionDescriptor` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A function descriptor is made up of zero or more argument layouts and zero or one return layout. A function descriptor is used to model the signature of foreign functions when creating downcall method handles PREVIEW or upcall stubs PREVIEW.

Implementation Requirements:
  This class is immutable, thread-safe and value-based.
Since:
  19
See Also:
  - `MemoryLayout`PREVIEW

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FunctionDescriptorPREVIEW`
  `appendArgumentLayouts (MemoryLayoutPREVIEW... addedLayouts)`
  Returns a function descriptor with the given argument layouts appended to the argument layout array of this function descriptor.
  `List<MemoryLayoutPREVIEW>`
  `argumentLayouts()`
  Returns the argument layouts associated with this function descriptor (as an immutable list).
  `FunctionDescriptorPREVIEW`
  `asVariadic (MemoryLayoutPREVIEW... variadicLayouts)`
  Creates a specialized variadic function descriptor, by appending given variadic layouts to this function descriptor argument layouts.
  `FunctionDescriptorPREVIEW`
  `changeReturnLayout (MemoryLayoutPREVIEW newReturn)`
  Returns a function descriptor with the given memory layout as the new return layout.
  `FunctionDescriptorPREVIEW`
  `dropReturnLayout()`
  Returns a function descriptor with the return layout dropped.
  `boolean`
  `equals (Object other)`
  Compares the specified object with this function descriptor for equality.
  `int`
  `firstVariadicArgumentIndex()`
  The index of the first variadic argument layout (where defined).
  `int`
  `hashCode()`
  Returns the hash code value for this function descriptor.
  `FunctionDescriptorPREVIEW`
  `insertArgumentLayouts (int index, MemoryLayoutPREVIEW... addedLayouts)`
  Returns a function descriptor with the given argument layouts inserted at the given index, into the argument layout array of this function descriptor.
  `static FunctionDescriptorPREVIEW`
  `of (MemoryLayoutPREVIEW resLayout, MemoryLayoutPREVIEW... argLayouts)`
  Creates a function descriptor with the given return and argument layouts.
  `static FunctionDescriptorPREVIEW`
  `ofVoid (MemoryLayoutPREVIEW... argLayouts)`
  Creates a function descriptor with the given argument layouts and no return layout.
  `Optional<MemoryLayoutPREVIEW>`
  `returnLayout()`
  Returns the return layout (if any) associated with this function descriptor.
  `String`
  `toString()`
  Returns the string representation of this function descriptor.

  ### Methods declared in class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Method Details

  - ### returnLayout

    public Optional<MemoryLayoutPREVIEW> returnLayout()
    Returns the return layout (if any) associated with this function descriptor.
    Returns:
      the return layout (if any) associated with this function descriptor

  - ### argumentLayouts

    public List<MemoryLayoutPREVIEW> argumentLayouts()
    Returns the argument layouts associated with this function descriptor (as an immutable list)..
    Returns:
      the argument layouts associated with this function descriptor (as an immutable list)

  - ### of

    public static FunctionDescriptorPREVIEW of (MemoryLayoutPREVIEW resLayout, MemoryLayoutPREVIEW... argLayouts)
    Creates a function descriptor with the given return and argument layouts.
    Parameters:
      `resLayout` - the return layout.
      `argLayouts` - the argument layouts.
    Returns:
      the new function descriptor.

  - ### ofVoid

    public static FunctionDescriptorPREVIEW ofVoid (MemoryLayoutPREVIEW... argLayouts)
    Creates a function descriptor with the given argument layouts and no return layout.
    Parameters:
      `argLayouts` - the argument layouts.
    Returns:
      the new function descriptor.

  - ### asVariadic

    public FunctionDescriptorPREVIEW asVariadic (MemoryLayoutPREVIEW... variadicLayouts)
    Creates a specialized variadic function descriptor, by appending given variadic layouts to this function descriptor argument layouts. The resulting function descriptor can report the position of the first variadic argument , and cannot be altered in any way: for instance, calling `changeReturnLayout(MemoryLayout)` on the resulting descriptor will throw an `UnsupportedOperationException`.
    Parameters:
      `variadicLayouts` - the variadic argument layouts to be appended to this descriptor argument layouts.
    Returns:
      a variadic function descriptor, or this descriptor if `variadicLayouts.length == 0` .

  - ### firstVariadicArgumentIndex

    public int firstVariadicArgumentIndex()
    The index of the first variadic argument layout (where defined).
    Returns:
      The index of the first variadic argument layout, or `-1` if this is not a variadic layout.

  - ### appendArgumentLayouts

    public FunctionDescriptorPREVIEW appendArgumentLayouts (MemoryLayoutPREVIEW... addedLayouts)
    Returns a function descriptor with the given argument layouts appended to the argument layout array of this function descriptor.
    Parameters:
      `addedLayouts` - the argument layouts to append.
    Returns:
      the new function descriptor.

  - ### insertArgumentLayouts

    public FunctionDescriptorPREVIEW insertArgumentLayouts (int index, MemoryLayoutPREVIEW... addedLayouts)
    Returns a function descriptor with the given argument layouts inserted at the given index, into the argument layout array of this function descriptor.
    Parameters:
      `index` - the index at which to insert the arguments
      `addedLayouts` - the argument layouts to insert at given index.
    Returns:
      the new function descriptor.
    Throws:
      `IllegalArgumentException` - if `index < 0 || index > argumentLayouts().size()` .

  - ### changeReturnLayout

    public FunctionDescriptorPREVIEW changeReturnLayout (MemoryLayoutPREVIEW newReturn)
    Returns a function descriptor with the given memory layout as the new return layout.
    Parameters:
      `newReturn` - the new return layout.
    Returns:
      the new function descriptor.

  - ### dropReturnLayout

    public FunctionDescriptorPREVIEW dropReturnLayout()
    Returns a function descriptor with the return layout dropped. This is useful to model functions which return no values.
    Returns:
      the new function descriptor.

  - ### toString

    public String toString()
    Returns the string representation of this function descriptor.
    Overrides:
      `toString` in class `Object`
    Returns:
      the string representation of this function descriptor

  - ### equals

    public boolean equals (Object other)
    Compares the specified object with this function descriptor for equality. Returns `true` if and only if the specified object is also a function descriptor, and all the following conditions are met:
    - the two function descriptors have equals return layouts (see `MemoryLayout.equals(Object)`PREVIEW), or both have no return layout;
    - the two function descriptors have argument layouts that are pair-wise equalPREVIEW; and
    - the two function descriptors have the same leading variadic argument index
    Overrides:
      `equals` in class `Object`
    Parameters:
      `other` - the object to be compared for equality with this function descriptor.
    Returns:
      `true` if the specified object is equal to this function descriptor.
    See Also:
      - `Object.hashCode()`
      - `HashMap`

  - ### hashCode

    public int hashCode()
    Returns the hash code value for this function descriptor.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash code value for this function descriptor
    See Also:
      - `Object.equals(java.lang.Object)`
      - `System.identityHashCode(java.lang.Object)`