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 foreign functions. A function descriptor is made up of zero or more argument layouts and zero or one return layout. A function descriptor is typically used when creating downcall method handlesPREVIEW or 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) associated with this function descriptor.
      Returns:
      the return layout (if any) associated with this function descriptor

    • argumentLayouts

      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)

    • appendArgumentLayouts

      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.
      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:
      the new function descriptor.
      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 given memory layout as the new return layout.
      Parameters:
      newReturn - the new return layout.
      Returns:
      the new function descriptor.
      Throws:
      IllegalArgumentException - if newReturn is a padding layout.

    • dropReturnLayout

      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.

    • 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 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
      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).

    • 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:
      the new function descriptor.
      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.
      Parameters:
      argLayouts - the argument layouts.
      Returns:
      the new function descriptor.
      Throws:
      IllegalArgumentException - if one of the layouts in argLayouts is a padding layout.