Top Description Constructors Methods
org.graalvm.nativeimage

public final Class StackValue

Additional top-level class in compilation unit: StackValueSnippets.

extends Object
Class Inheritance
Imports
org.graalvm.nativeimage.c.CContext, org.graalvm.nativeimage.c.struct.CField, .CStruct, .SizeOf, org.graalvm.word.PointerBase
Contains static methods for memory allocation in the stack frame. Stack allocation is not permitted in virtual threads because the returned pointers would become invalid when a virtual thread migrates to a different carrier thread.
Since
19.0

Constructor Summary

AccessConstructor and Description
private
StackValue()

Method Summary

Modifier and TypeMethod and Description
public static <
the type, annotated by CStruct annotation
T extends PointerBase> T

Returns:

pointer to on-stack allocated location for the requested structure
get(Class<T>
the requested structure class - must be a compile time constant
structType)

Reserves a block of memory for given CStruct class in the stack frame of the method that calls this intrinsic.

public static <
the type, annotated by CStruct annotation
T extends PointerBase> T

Returns:

pointer to on-stack allocated location for the requested structure
get(int
number of array elements to allocate
numberOfElements, Class<T>
the requested structure class - must be a compile time constant
structType)

Reserves a block of memory for array of given CStruct type in the stack frame of the method that calls this intrinsic.

public static <T extends PointerBase> T
get(int size)

Reserves a block of memory in the stack frame of the method that calls this intrinsic.

public static <T extends PointerBase> T
get(int numberOfElements, int elementSize)

Utility method that performs size arithmetic, otherwise equivalent to get(int).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

StackValueback to summary
private StackValue()

Method Detail

getback to summary
public static <T extends PointerBase> T get(Class<T> structType)

Reserves a block of memory for given CStruct class in the stack frame of the method that calls this intrinsic. This is a convenience method for calls to:

file="org/graalvm/nativeimage/StackValue.java" region="withSizeOf" 
file="org/graalvm/nativeimage/StackValue.java" region="withSizeOf"

It can be used to allocate a structure on the stack. The following example allocates a ComplexValue and then sends it as a regular parameter to another function to compute absolute value of the number:

file="org/graalvm/nativeimage/StackValue.java" region="ninePlusSixteenSqrt" 
file="org/graalvm/nativeimage/StackValue.java" region="ninePlusSixteenSqrt"

Parameters
<T>
the type, annotated by CStruct annotation
structType:Class<T>

the requested structure class - must be a compile time constant

Returns:T

pointer to on-stack allocated location for the requested structure

Exceptions
IllegalThreadStateException:
when called in a virtual thread.
Since
19.0
getback to summary
public static <T extends PointerBase> T get(int numberOfElements, Class<T> structType)

Reserves a block of memory for array of given CStruct type in the stack frame of the method that calls this intrinsic. This is a convenience method for calls to:

file="org/graalvm/nativeimage/StackValue.java" region="withSizeOfArray" 
file="org/graalvm/nativeimage/StackValue.java" region="withSizeOfArray"
*

It can be used to allocate a array of parameters on the stack. The following example allocates a three element array, fills them with two int values and one double value and then sends it to a method that accepts such parameter convention:

file="org/graalvm/nativeimage/StackValue.java" region="callIntIntDouble" 
file="org/graalvm/nativeimage/StackValue.java" region="callIntIntDouble"

Parameters
<T>
the type, annotated by CStruct annotation
numberOfElements:int

number of array elements to allocate

structType:Class<T>

the requested structure class - must be a compile time constant

Returns:T

pointer to on-stack allocated location for the requested structure

Exceptions
IllegalThreadStateException:
when called in a virtual thread.
Since
19.0
getback to summary
public static <T extends PointerBase> T get(int size)

Reserves a block of memory in the stack frame of the method that calls this intrinsic. The returned pointer is aligned to the same alignment required by the operating system for stack frames. If the requested size is 0, the method returns null. The size must be a compile time constant. If the call to this method is in a loop, always the same pointer is returned. In other words: this method does not allocate memory; it returns the address of a fixed-size block of memory that is reserved in the stack frame when the method starts execution. The memory is not initialized. Two distinct calls of this method return different pointers.

Annotations
@SuppressWarnings:unused
Exceptions
IllegalThreadStateException:
when called in a virtual thread.
Since
19.0
getback to summary
public static <T extends PointerBase> T get(int numberOfElements, int elementSize)

Utility method that performs size arithmetic, otherwise equivalent to get(int).

Annotations
@SuppressWarnings:unused
Since
19.0