Module java.base
Package java.lang.foreign

Interface FunctionDescriptor

public sealed interface FunctionDescriptor
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 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 handlesPREVIEW and upcall stubsPREVIEW.
Implementation Requirements:
Implementing classes are immutable, thread-safe and value-based.
Since:
19
See Also:

  • Method Details

    • returnLayout

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

    • argumentLayouts

      List<MemoryLayoutPREVIEW> 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

      FunctionDescriptorPREVIEW appendArgumentLayouts(MemoryLayoutPREVIEW... 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

      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:
      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

      FunctionDescriptorPREVIEW changeReturnLayout(MemoryLayoutPREVIEW 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

      FunctionDescriptorPREVIEW 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:

      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 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:
      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 FunctionDescriptorPREVIEW ofVoid(MemoryLayoutPREVIEW... 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.