Package 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
    Description
    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, int elementSize)
    Utility method that performs size arithmetic, otherwise equivalent to get(int).
    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(Class<T> structType)
    Reserves a block of memory for given CStruct class in the stack frame of the method that calls this intrinsic.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • 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 get(int).
      Since:
      19.0