W3cubDocs

/OpenJDK 21

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 Summary

Modifier and Type Method Description
FunctionDescriptorPREVIEW appendArgumentLayouts(MemoryLayoutPREVIEW... addedLayouts)
Returns a function descriptor with the given argument layouts appended to the argument layouts of this function descriptor.
List<MemoryLayoutPREVIEW> argumentLayouts()
Returns the argument layouts of this function descriptor (as an unmodifiable list).
FunctionDescriptorPREVIEW changeReturnLayout(MemoryLayoutPREVIEW newReturn)
Returns a function descriptor with the provided return layout.
FunctionDescriptorPREVIEW dropReturnLayout()
Returns a new function descriptor, with no return layout.
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.
static FunctionDescriptorPREVIEW of(MemoryLayoutPREVIEW resLayout, MemoryLayoutPREVIEW... argLayouts)
Creates a function descriptor with the given return and argument layouts.
static FunctionDescriptorPREVIEW ofVoid(MemoryLayoutPREVIEW... argLayouts)
Creates a function descriptor with the given argument layouts and no return layout.
Optional<MemoryLayoutPREVIEW> 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<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.

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/FunctionDescriptor.html