FunctionDescriptor (Java SE 22 & JDK 22)
Description: declaration: module: java.base, package: java.lang.foreign, interface: FunctionDescriptor
Keywords: java.lang.foreign.FunctionDescriptor interface

Module java.base
Package java.lang.foreign

# Interface FunctionDescriptor

public sealed interface FunctionDescriptor
A function descriptor models the signature of a foreign function. A function descriptor is made up of zero or more argument layouts, and zero or one return layout. A function descriptor is used to create downcall method handlesRESTRICTED and upcall stubsRESTRICTED.

Implementation Requirements:
  Implementing classes are immutable, thread-safe and value-based.
Since:
  22
See Also:
  - `MemoryLayout`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FunctionDescriptor`
  `appendArgumentLayouts(MemoryLayout... addedLayouts)`
  Returns a function descriptor with the given argument layouts appended to the argument layouts of this function descriptor.
  `List<MemoryLayout>`
  `argumentLayouts()`
  Returns the argument layouts of this function descriptor (as an unmodifiable list).
  `FunctionDescriptor`
  `changeReturnLayout(MemoryLayout newReturn)`
  Returns a function descriptor with the provided return layout.
  `FunctionDescriptor`
  `dropReturnLayout()`
  Returns a new function descriptor, with no return layout.
  `FunctionDescriptor`
  `insertArgumentLayouts(int index, 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.
  `static FunctionDescriptor`
  `of(MemoryLayout resLayout, MemoryLayout... argLayouts)`
  Creates a function descriptor with the given return and argument layouts.
  `static FunctionDescriptor`
  `ofVoid(MemoryLayout... argLayouts)`
  Creates a function descriptor with the given argument layouts and no return layout.
  `Optional<MemoryLayout>`
  `returnLayout()`
  Returns the return layout (if any) of this function descriptor.
  `MethodType`
  `toMethodType()`
  Returns the method type consisting of the carrier types of the layouts in this function descriptor.

- ## Method Details

  - ### returnLayout

    Optional<MemoryLayout> returnLayout()
    Returns the return layout (if any) of this function descriptor.
    Returns:
      the return layout (if any) of this function descriptor

  - ### argumentLayouts

    List<MemoryLayout> argumentLayouts()
    Returns the argument layouts of this function descriptor (as an unmodifiable list).
    Returns:
      the argument layouts of this function descriptor (as an unmodifiable list)

  - ### appendArgumentLayouts

    FunctionDescriptor appendArgumentLayouts(MemoryLayout... addedLayouts)
    Returns a function descriptor with the given argument layouts appended to the argument layouts of this function descriptor.
    Parameters:
      `addedLayouts` - the argument layouts to append
    Returns:
      a new function descriptor, with the provided additional argument layouts
    Throws:
      `IllegalArgumentException` - if one of the layouts in `addedLayouts` is a padding layout

  - ### insertArgumentLayouts

    FunctionDescriptor insertArgumentLayouts(int index, 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.
    Parameters:
      `index` - the index at which to insert the arguments
      `addedLayouts` - the argument layouts to insert at given index
    Returns:
      a new function descriptor, with the provided additional argument layouts
    Throws:
      `IllegalArgumentException` - if one of the layouts in `addedLayouts` is a padding layout
      `IllegalArgumentException` - if `index < 0 || index > argumentLayouts().size()`

  - ### changeReturnLayout

    FunctionDescriptor changeReturnLayout(MemoryLayout newReturn)
    Returns a function descriptor with the provided return layout.
    Parameters:
      `newReturn` - the new return layout
    Returns:
      a new function descriptor, with the provided return layout
    Throws:
      `IllegalArgumentException` - if `newReturn` is a padding layout

  - ### dropReturnLayout

    FunctionDescriptor dropReturnLayout()
    Returns a new function descriptor, with no return layout.
    Returns:
      a new function descriptor, with no return layout

  - ### toMethodType

    MethodType toMethodType()
    Returns the method type consisting of the carrier types of the layouts in this function descriptor.

    The carrier type of a layout `L` is determined as follows:

    - If `L` is a `ValueLayout` the carrier type is determined through `ValueLayout.carrier()`.
    - If `L` is a `GroupLayout` or a `SequenceLayout`, the carrier type is `MemorySegment`.
    API Note:
      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.
    Returns:
      the method type consisting of the carrier types of the layouts in this function descriptor

  - ### of

    static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argLayouts)
    Creates a function descriptor with the given return and argument layouts.
    Parameters:
      `resLayout` - the return layout
      `argLayouts` - the argument layouts
    Returns:
      a new function descriptor with the provided return and argument layouts
    Throws:
      `IllegalArgumentException` - if `resLayout` is a padding layout
      `IllegalArgumentException` - if one of the layouts in `argLayouts` is a padding layout

  - ### ofVoid

    static FunctionDescriptor ofVoid(MemoryLayout... argLayouts)
    Creates a function descriptor with the given argument layouts and no return layout. This is useful to model functions that return no values.
    Parameters:
      `argLayouts` - the argument layouts
    Returns:
      a new function descriptor with the provided argument layouts
    Throws:
      `IllegalArgumentException` - if one of the layouts in `argLayouts` is a padding layout