OpenJDK 27 · jdk.internal.foreign.abi.CallingSequence

Modifier and Type	Field and Description
private final long	allocationSize
private final List<List<Binding>>	argumentBindings
private final MethodType	calleeMethodType
private final MethodType	callerMethodType
private final FunctionDescriptor	desc
private final boolean	forUpcall
private final LinkerOptions	linkerOptions
private final boolean	needsReturnBuffer
private final List<Binding>	returnBindings
private final long	returnBufferSize

Access	Constructor and Description
public	CallingSequence(boolean forUpcall, MethodType callerMethodType, MethodType calleeMethodType, FunctionDescriptor desc, boolean needsReturnBuffer, long returnBufferSize, long allocationSize, List<List<Binding>> argumentBindings, List<Binding> returnBindings, LinkerOptions linkerOptions)

Method Summary

Modifier and Type	Method and Description
public long	Returns: the allocation size allocationSize() The amount of bytes this calling sequence needs to allocate during an invocation.
public List<Binding>	argumentBindings(int i)
public Stream<Binding>	argumentBindings()
public int	Returns: the number of binding recipes in this calling sequence argumentBindingsCount() An important distinction is that downcalls have 1 recipe per caller parameter and each callee parameter corresponds to a VM_STORE.
public String	asString()
public MethodType	Returns: the callee method type. calleeMethodType() Returns the callee method type, which is the low-level method type (all primitives, VM facing) for downcalls and the high-level method type for upcalls (also the method type of the user-supplied target MH).
public MethodType	Returns: the caller method type. callerMethodType() Returns the caller method type, which is the high-level method type for downcalls (the type of the downcall method handle) and the low-level method type (all primitives, VM facing) for upcalls.
public int	capturedStateMask()
public boolean	forDowncall()
public boolean	forUpcall()
public FunctionDescriptor	functionDesc()
public boolean	hasReturnBindings()
public boolean	Returns: whether this calling sequence needs a return buffer. needsReturnBuffer() Whether this calling sequence needs a return buffer.
public boolean	needsTransition()
public int	numLeadingParams()
public List<Binding>	returnBindings()
public long	Returns: the return buffer size returnBufferSize() The size of the return buffer, if one is needed.
public boolean	usingAddressPairs()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

allocationSize	back to summary
private final long allocationSize

argumentBindings	back to summary
private final List<List<Binding>> argumentBindings

calleeMethodType	back to summary
private final MethodType calleeMethodType

callerMethodType	back to summary
private final MethodType callerMethodType

desc	back to summary
private final FunctionDescriptor desc

forUpcall	back to summary
private final boolean forUpcall

linkerOptions	back to summary
private final LinkerOptions linkerOptions

needsReturnBuffer	back to summary
private final boolean needsReturnBuffer

returnBindings	back to summary
private final List<Binding> returnBindings

returnBufferSize	back to summary
private final long returnBufferSize

CallingSequence	back to summary
public CallingSequence(boolean forUpcall, MethodType callerMethodType, MethodType calleeMethodType, FunctionDescriptor desc, boolean needsReturnBuffer, long returnBufferSize, long allocationSize, List<List<Binding>> argumentBindings, List<Binding> returnBindings, LinkerOptions linkerOptions)

Method Detail

allocationSize	back to summary
public long allocationSize() The amount of bytes this calling sequence needs to allocate during an invocation. Includes the return buffer size as well as space for any buffer copies in the recipes. Returns:long the allocation size

allocationSize

back to summary

public long allocationSize()

The amount of bytes this calling sequence needs to allocate during an invocation. Includes the return buffer size as well as space for any buffer copies in the recipes.

Returns:long: the allocation size

argumentBindings	back to summary
public List<Binding> argumentBindings(int i)

argumentBindings	back to summary
public Stream<Binding> argumentBindings()

argumentBindingsCount	back to summary
public int argumentBindingsCount() An important distinction is that downcalls have 1 recipe per caller parameter and each callee parameter corresponds to a VM_STORE. Upcalls have 1 recipe per callee parameter and each caller parameter corresponds to a VM_LOAD. The VM_STOREs are then implemented by the leaf handle for downcalls, and vice versa, the wrapper stub that wraps an upcall handle implements the VM_LOADS. In both cases the register values are communicated through Java primitives. The 'argumentBindingsCount' below corresponds to the number of recipes, so it is the caller parameter count for downcalls, and the callee parameter count for upcalls. Returns:int the number of binding recipes in this calling sequence

argumentBindingsCount

back to summary

public int argumentBindingsCount()

An important distinction is that downcalls have 1 recipe per caller parameter and each callee parameter corresponds to a VM_STORE. Upcalls have 1 recipe per callee parameter and each caller parameter corresponds to a VM_LOAD. The VM_STOREs are then implemented by the leaf handle for downcalls, and vice versa, the wrapper stub that wraps an upcall handle implements the VM_LOADS. In both cases the register values are communicated through Java primitives. The 'argumentBindingsCount' below corresponds to the number of recipes, so it is the caller parameter count for downcalls, and the callee parameter count for upcalls.

Returns:int: the number of binding recipes in this calling sequence

asString	back to summary
public String asString()

calleeMethodType	back to summary
public MethodType calleeMethodType() Returns the callee method type, which is the low-level method type (all primitives, VM facing) for downcalls and the high-level method type for upcalls (also the method type of the user-supplied target MH). Note that for upcalls a single parameter in this method type corresponds to a single argument binding recipe in this calling sequence, but it may correspond to multiple parameters in the caller method type (for instance if a struct is reconstructed from multiple register values). Returns:MethodType the callee method type.

calleeMethodType

back to summary

public MethodType calleeMethodType()

Returns the callee method type, which is the low-level method type (all primitives, VM facing) for downcalls and the high-level method type for upcalls (also the method type of the user-supplied target MH). Note that for upcalls a single parameter in this method type corresponds to a single argument binding recipe in this calling sequence, but it may correspond to multiple parameters in the caller method type (for instance if a struct is reconstructed from multiple register values).

Returns:MethodType: the callee method type.

callerMethodType	back to summary
public MethodType callerMethodType() Returns the caller method type, which is the high-level method type for downcalls (the type of the downcall method handle) and the low-level method type (all primitives, VM facing) for upcalls. Note that for downcalls a single parameter in this method type corresponds to a single argument binding recipe in this calling sequence, but it may correspond to multiple parameters in the callee method type (for instance if a struct is split into multiple register values). Returns:MethodType the caller method type.

callerMethodType

back to summary

public MethodType callerMethodType()

Returns the caller method type, which is the high-level method type for downcalls (the type of the downcall method handle) and the low-level method type (all primitives, VM facing) for upcalls. Note that for downcalls a single parameter in this method type corresponds to a single argument binding recipe in this calling sequence, but it may correspond to multiple parameters in the callee method type (for instance if a struct is split into multiple register values).

Returns:MethodType: the caller method type.

capturedStateMask	back to summary
public int capturedStateMask()

forDowncall	back to summary
public boolean forDowncall()

forUpcall	back to summary
public boolean forUpcall()

functionDesc	back to summary
public FunctionDescriptor functionDesc()

hasReturnBindings	back to summary
public boolean hasReturnBindings()

needsReturnBuffer	back to summary
public boolean needsReturnBuffer() Whether this calling sequence needs a return buffer. A return buffer is used to support functions that return values in multiple registers, which is not possible to do just with Java primitives (we can only return 1 value in Java, meaning only 1 register value). To emulate these multi-register returns, we instead use a pre-allocated buffer (the return buffer) from/into which the return values are loaded/stored. For downcalls, we allocate the buffer in Java code, and pass the address down to the VM stub, which stores the returned register values into this buffer. VM_LOADs in the binding recipe for the return value then load the value from this buffer. For upcalls, the VM stub allocates a buffer (on the stack), and passes the address to the Java method handle it calls. VM_STOREs in the return binding recipe then store values into this buffer, after which the VM stub moves the values from the buffer into the right register. Returns:boolean whether this calling sequence needs a return buffer.

needsReturnBuffer

back to summary

public boolean needsReturnBuffer()

Whether this calling sequence needs a return buffer. A return buffer is used to support functions that return values in multiple registers, which is not possible to do just with Java primitives (we can only return 1 value in Java, meaning only 1 register value). To emulate these multi-register returns, we instead use a pre-allocated buffer (the return buffer) from/into which the return values are loaded/stored. For downcalls, we allocate the buffer in Java code, and pass the address down to the VM stub, which stores the returned register values into this buffer. VM_LOADs in the binding recipe for the return value then load the value from this buffer. For upcalls, the VM stub allocates a buffer (on the stack), and passes the address to the Java method handle it calls. VM_STOREs in the return binding recipe then store values into this buffer, after which the VM stub moves the values from the buffer into the right register.

Returns:boolean: whether this calling sequence needs a return buffer.

needsTransition	back to summary
public boolean needsTransition()

numLeadingParams	back to summary
public int numLeadingParams()

returnBindings	back to summary
public List<Binding> returnBindings()

returnBufferSize back to summary

returnBufferSize	back to summary
public long returnBufferSize() The size of the return buffer, if one is needed. Returns:long the return buffer size See Also `needsReturnBuffer`

public long returnBufferSize()

The size of the return buffer, if one is needed.

Returns:long: the return buffer size
See Also: needsReturnBuffer

usingAddressPairs	back to summary
public boolean usingAddressPairs()

public Class CallingSequence

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail