# 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