Class MemoryStack

  • All Implemented Interfaces:
    java.lang.AutoCloseable


    public class MemoryStack
    extends java.lang.Object
    implements java.lang.AutoCloseable
    An off-heap memory stack.

    This class should be used in a thread-local manner for stack allocations.

    See Also:
    Configuration.STACK_SIZE, Configuration.DEBUG_STACK
    • Method Detail

      • create

        public static MemoryStack create(int size)
        Creates a new MemoryStack with the specified size.
        Parameters:
        size - the maximum number of bytes that may be allocated on the stack
      • push

        public MemoryStack push()
        Stores the current stack pointer and pushes a new frame to the stack.

        This method should be called when entering a method, before doing any stack allocations. When exiting a method, call the MemoryStack.pop() method to restore the previous stack frame.

        Pairs of push/pop calls may be nested. Care must be taken to:

        • match every push with a pop
        • not call pop before push has been called at least once
        • not nest push calls to more than the maximum supported depth
        Returns:
        this stack
      • pop

        public MemoryStack pop()
        Pops the current stack frame and moves the stack pointer to the end of the previous stack frame.
        Returns:
        this stack
      • close

        public void close()
        Calls MemoryStack.pop() on this MemoryStack.

        This method should not be used directly. It is called automatically when the MemoryStack is used as a resource in a try-with-resources statement.

        Specified by:
        close in interface java.lang.AutoCloseable
      • getAddress

        public long getAddress()
        Returns the address of the backing off-heap memory.

        The stack grows "downwards", so the bottom of the stack is at address + size, while the top is at address.

      • getSize

        public int getSize()
        Returns the size of the backing off-heap memory.

        This is the maximum number of bytes that may be allocated on the stack.

      • getFrameIndex

        public int getFrameIndex()
        Returns the current frame index.

        This is the current number of nested MemoryStack.push() calls.

      • getPointer

        public int getPointer()
        Returns the current stack pointer.

        The stack grows "downwards", so when the stack is empty pointer is equal to size. On every allocation pointer is reduced by the allocated size (after alignment) and address + pointers points to the last byte of the last allocation.

        Effectively, this methods returns how many more bytes may be allocated on the stack.

      • setPointer

        public void setPointer(int pointer)
        Sets the current stack pointer.

        This method directly manipulates the stack pointer. Using it irresponsibly may break the internal state of the stack. It should only be used in rare cases or in auto-generated code.

      • nmalloc

        public long nmalloc(int size)
        Calls MemoryStack.nmalloc(int, int) with alignment equal to 1.
        Parameters:
        size - the allocation size
        Returns:
        the memory address on the stack for the requested allocation
      • nmalloc

        public long nmalloc(int alignment,
                            int size)
        Allocates a block of size bytes of memory on the stack. The content of the newly allocated block of memory is not initialized, remaining with indeterminate values.
        Parameters:
        alignment - the required alignment
        size - the allocation size
        Returns:
        the memory address on the stack for the requested allocation
      • ncalloc

        public long ncalloc(int alignment,
                            int num,
                            int size)
        Allocates a block of memory on the stack for an array of num elements, each of them size bytes long, and initializes all its bits to zero.
        Parameters:
        alignment - the required element alignment
        num - num the number of elements to allocate
        size - the size of each element
        Returns:
        the memory address on the stack for the requested allocation
      • malloc

        public java.nio.ByteBuffer malloc(int alignment,
                                          int size)
        Allocates an aligned ByteBuffer on the stack.
        Parameters:
        alignment - the required buffer alignment
        size - the number of elements in the buffer
        Returns:
        the allocated buffer
      • malloc

        public java.nio.ByteBuffer malloc(int size)
        Allocates a ByteBuffer on the stack.
        Parameters:
        size - the number of elements in the buffer
        Returns:
        the allocated buffer
      • doubles

        public java.nio.DoubleBuffer doubles(double x,
                                             double y,
                                             double z,
                                             double w)
        Four value version of MemoryStack.mallocDouble(int).
      • ASCII

        public java.nio.ByteBuffer ASCII(java.lang.CharSequence text)
        Encodes the specified text on the stack using ASCII encoding and returns a ByteBuffer that points to the encoded text, including a null-terminator.
        Parameters:
        text - the text to encode
      • ASCII

        public java.nio.ByteBuffer ASCII(java.lang.CharSequence text,
                                         boolean nullTerminated)
        Encodes the specified text on the stack using ASCII encoding and returns a ByteBuffer that points to the encoded text.
        Parameters:
        text - the text to encode
        nullTerminated - if true, a null-terminator is included at the end of the encoded text
      • ASCIISafe

        @Nullable
        public java.nio.ByteBuffer ASCIISafe(@Nullable
                                             java.lang.CharSequence text)
        Like ASCII, but returns null if text is null.
      • ASCIISafe

        @Nullable
        public java.nio.ByteBuffer ASCIISafe(@Nullable
                                             java.lang.CharSequence text,
                                             boolean nullTerminated)
        Like ASCII, but returns null if text is null.
      • UTF8

        public java.nio.ByteBuffer UTF8(java.lang.CharSequence text)
        Encodes the specified text on the stack using UTF8 encoding and returns a ByteBuffer that points to the encoded text, including a null-terminator.
        Parameters:
        text - the text to encode
      • UTF8

        public java.nio.ByteBuffer UTF8(java.lang.CharSequence text,
                                        boolean nullTerminated)
        Encodes the specified text on the stack using UTF8 encoding and returns a ByteBuffer that points to the encoded text.
        Parameters:
        text - the text to encode
        nullTerminated - if true, a null-terminator is included at the end of the encoded text
      • UTF8Safe

        @Nullable
        public java.nio.ByteBuffer UTF8Safe(@Nullable
                                            java.lang.CharSequence text)
        Like UTF8, but returns null if text is null.
      • UTF8Safe

        @Nullable
        public java.nio.ByteBuffer UTF8Safe(@Nullable
                                            java.lang.CharSequence text,
                                            boolean nullTerminated)
        Like UTF8, but returns null if text is null.
      • UTF16

        public java.nio.ByteBuffer UTF16(java.lang.CharSequence text)
        Encodes the specified text on the stack using UTF16 encoding and returns a ByteBuffer that points to the encoded text, including a null-terminator.
        Parameters:
        text - the text to encode
      • UTF16

        public java.nio.ByteBuffer UTF16(java.lang.CharSequence text,
                                         boolean nullTerminated)
        Encodes the specified text on the stack using UTF16 encoding and returns a ByteBuffer that points to the encoded text.
        Parameters:
        text - the text to encode
        nullTerminated - if true, a null-terminator is included at the end of the encoded text
      • UTF16Safe

        @Nullable
        public java.nio.ByteBuffer UTF16Safe(@Nullable
                                             java.lang.CharSequence text)
        Like UTF16, but returns null if text is null.
      • UTF16Safe

        @Nullable
        public java.nio.ByteBuffer UTF16Safe(@Nullable
                                             java.lang.CharSequence text,
                                             boolean nullTerminated)
        Like UTF16, but returns null if text is null.
      • stackGet

        public static MemoryStack stackGet()
        Returns the stack of the current thread.
      • stackPush

        public static MemoryStack stackPush()
        Calls MemoryStack.push() on the stack of the current thread.
        Returns:
        the stack of the current thread.
      • stackPop

        public static MemoryStack stackPop()
        Calls MemoryStack.pop() on the stack of the current thread.
        Returns:
        the stack of the current thread.
      • stackBytes

        public static java.nio.ByteBuffer stackBytes(byte x)
        Thread-local version of MemoryStack.bytes(byte).
      • stackInts

        public static java.nio.IntBuffer stackInts(int x)
        Thread-local version of MemoryStack.ints(int).
      • stackInts

        public static java.nio.IntBuffer stackInts(int... values)
        Thread-local version of MemoryStack.ints(int...).
      • stackLongs

        public static java.nio.LongBuffer stackLongs(long x)
        Thread-local version of MemoryStack.longs(long).
      • stackASCIISafe

        @Nullable
        public static java.nio.ByteBuffer stackASCIISafe(@Nullable
                                                         java.lang.CharSequence text)
        Thread-local version of MemoryStack.ASCII(CharSequence).
      • stackASCIISafe

        @Nullable
        public static java.nio.ByteBuffer stackASCIISafe(@Nullable
                                                         java.lang.CharSequence text,
                                                         boolean nullTerminated)
      • stackUTF8Safe

        @Nullable
        public static java.nio.ByteBuffer stackUTF8Safe(@Nullable
                                                        java.lang.CharSequence text)
        Thread-local version of MemoryStack.UTF8(CharSequence).
      • stackUTF8Safe

        @Nullable
        public static java.nio.ByteBuffer stackUTF8Safe(@Nullable
                                                        java.lang.CharSequence text,
                                                        boolean nullTerminated)
      • stackUTF16Safe

        @Nullable
        public static java.nio.ByteBuffer stackUTF16Safe(@Nullable
                                                         java.lang.CharSequence text)
        Thread-local version of MemoryStack.UTF16(CharSequence).
      • stackUTF16Safe

        @Nullable
        public static java.nio.ByteBuffer stackUTF16Safe(@Nullable
                                                         java.lang.CharSequence text,
                                                         boolean nullTerminated)