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

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