org.graalvm.nativeimage

Class StackValue

java.lang.Object

org.graalvm.nativeimage.StackValue

public final class StackValue
extends Object

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

Method Summary

Modifier and Type	Method and Description
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.
static <T extends PointerBase> T	get(int size) Reserves a block of memory in the stack frame of the method that calls this intrinsic.
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.
static <T extends PointerBase> T	get(int numberOfElements, int elementSize) Utility method that performs size arithmetic, otherwise equivalent to StackValue.get(int).

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

get

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:

ComplexValue numberOnStack = StackValue.get(
                SizeOf.get(ComplexValue.class));

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:

ComplexValue numberOnStack = StackValue.get(ComplexValue.class);
numberOnStack.realPart(3.0);
numberOnStack.imagineryPart(4.0);
double absoluteValue = absoluteValue(numberOnStack);
assert 5.0 == absoluteValue;

Type Parameters:

T - the type, annotated by CStruct annotation

Parameters:

structType - the requested structure class - must be a compile time constant

Returns:

pointer to on-stack allocated location for the requested structure

Throws:

IllegalThreadStateException - when called in a virtual thread.

Since:

19.0

get

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:

IntOrDouble arrayOnStack = StackValue.get(
                3, // number of array elements
                SizeOf.get(IntOrDouble.class));

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:

IntOrDouble array = StackValue.get(3, IntOrDouble.class);
array.addressOf(0).i(10);
array.addressOf(2).i(12);
array.addressOf(3).d(20.0);
double sum = acceptIntIntDouble(array);

Type Parameters:

T - the type, annotated by CStruct annotation

Parameters:

numberOfElements - number of array elements to allocate

structType - the requested structure class - must be a compile time constant

Returns:

pointer to on-stack allocated location for the requested structure

Throws:

IllegalThreadStateException - when called in a virtual thread.

Since:

19.0

get

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.

Throws:

IllegalThreadStateException - when called in a virtual thread.

Since:

19.0

get

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

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

Since:

19.0