Package Summary Overview Summary

Package Summary Overview Summary

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 handles and upcall stubs .

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

- ## 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`.
    Returns:
      the method type consisting of the carrier types of the layouts in this function descriptor.
    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.

  - ### 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.