FunctionDescriptor (Java SE 17 & JDK 17)
Description: declaration: module: jdk.incubator.foreign, package: jdk.incubator.foreign, class: FunctionDescriptor
Keywords: jdk.incubator.foreign.FunctionDescriptor class

Module jdk.incubator.foreign
Package jdk.incubator.foreign

# Class FunctionDescriptor

java.lang.Object
jdk.incubator.foreign.FunctionDescriptor

All Implemented Interfaces:
  `Constable`

public final class FunctionDescriptor extends Object implements Constable
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.

Unless otherwise specified, passing a `null` argument, or an array argument containing one or more `null` elements to a method in this class causes a `NullPointerException` to be thrown.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `TRIVIAL_ATTRIBUTE_NAME`
  The name of the function descriptor attribute (see `attributes()` used to mark trivial functions.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `List<MemoryLayout>`
  `argumentLayouts()`
  Returns the argument layouts associated with this function.
  `Optional<Constable>`
  `attribute(String name)`
  Returns the attribute with the given name (if it exists).
  `Stream<String>`
  `attributes()`
  Returns a stream of the attribute names associated with this function descriptor.
  `Optional<DynamicConstantDesc<FunctionDescriptor>>`
  `describeConstable()`
  Returns an `Optional` containing the nominal descriptor for this instance, if one can be constructed, or an empty `Optional` if one cannot be constructed.
  `boolean`
  `equals(Object other)`
  Compares the specified object with this function descriptor for equality.
  `int`
  `hashCode()`
  Returns the hash code value for this function descriptor.
  `static FunctionDescriptor`
  `of(MemoryLayout resLayout, MemoryLayout... argLayouts)`
  Create a function descriptor with given return and argument layouts.
  `static FunctionDescriptor`
  `ofVoid(MemoryLayout... argLayouts)`
  Create a function descriptor with given argument layouts and no return layout.
  `Optional<MemoryLayout>`
  `returnLayout()`
  Returns the return layout associated with this function.
  `String`
  `toString()`
  Returns a string representation of this function descriptor.
  `FunctionDescriptor`
  `withAppendedArgumentLayouts(MemoryLayout... addedLayouts)`
  Create a new function descriptor with the given argument layouts appended to the argument layout array of this function descriptor.
  `FunctionDescriptor`
  `withAttribute(String name, Constable value)`
  Returns a new function descriptor which features the same attributes as this descriptor, plus the newly specified attribute.
  `FunctionDescriptor`
  `withReturnLayout(MemoryLayout newReturn)`
  Create a new function descriptor with the given memory layout as the new return layout.
  `FunctionDescriptor`
  `withVoidReturnLayout()`
  Create a new function descriptor with the return layout dropped.

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

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

- ## Field Details

  - ### TRIVIAL_ATTRIBUTE_NAME

    public static final String TRIVIAL_ATTRIBUTE_NAME
    The name of the function descriptor attribute (see `attributes()` used to mark trivial functions. The attribute value must be a boolean.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### attribute

    public Optional<Constable> attribute(String name)
    Returns the attribute with the given name (if it exists).
    Parameters:
      `name` - the attribute name.
    Returns:
      the attribute with the given name (if it exists).

  - ### attributes

    public Stream<String> attributes()
    Returns a stream of the attribute names associated with this function descriptor.
    Returns:
      a stream of the attribute names associated with this function descriptor.

  - ### withAttribute

    public FunctionDescriptor withAttribute(String name, Constable value)
    Returns a new function descriptor which features the same attributes as this descriptor, plus the newly specified attribute. If this descriptor already contains an attribute with the same name, the existing attribute value is overwritten in the returned descriptor.
    Parameters:
      `name` - the attribute name.
      `value` - the attribute value.
    Returns:
      a new function descriptor which features the same attributes as this descriptor, plus the newly specified attribute.

  - ### returnLayout

    public Optional<MemoryLayout> returnLayout()
    Returns the return layout associated with this function.
    Returns:
      the return layout.

  - ### argumentLayouts

    public List<MemoryLayout> argumentLayouts()
    Returns the argument layouts associated with this function.
    Returns:
      the argument layouts.

  - ### of

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

  - ### ofVoid

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

  - ### withAppendedArgumentLayouts

    public FunctionDescriptor withAppendedArgumentLayouts(MemoryLayout... addedLayouts)
    Create a new 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.

  - ### withReturnLayout

    public FunctionDescriptor withReturnLayout(MemoryLayout newReturn)
    Create a new function descriptor with the given memory layout as the new return layout.
    Parameters:
      `newReturn` - the new return layout.
    Returns:
      the new function descriptor.

  - ### withVoidReturnLayout

    public FunctionDescriptor withVoidReturnLayout()
    Create a new function descriptor with the return layout dropped.
    Returns:
      the new function descriptor.

  - ### toString

    public String toString()
    Returns a string representation of this function descriptor.
    Overrides:
      `toString` in class `Object`
    Returns:
      a 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 of the following conditions are met:
    - the two function descriptors have equals return layouts (see `MemoryLayout.equals(Object)`), or both have no return layout
    - the two function descriptors have argument layouts that are pair-wise equal (see `MemoryLayout.equals(Object)`)
    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)`

  - ### describeConstable

    public Optional<DynamicConstantDesc<FunctionDescriptor>> describeConstable()
    Description copied from interface: `Constable`
    Returns an `Optional` containing the nominal descriptor for this instance, if one can be constructed, or an empty `Optional` if one cannot be constructed.
    Specified by:
      `describeConstable` in interface `Constable`
    Returns:
      An `Optional` containing the resulting nominal descriptor, or an empty `Optional` if one cannot be constructed.