Class SegmentStack

java.lang.Object
org.lwjgl.system.SegmentStack
All Implemented Interfaces:
AutoCloseable, SegmentAllocator, StackAllocator<SegmentStack>
public class SegmentStack extends Object implements StackAllocator<SegmentStack>, AutoCloseable
An off-heap memory stack.

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

See Also:

  • Method Details

    • create

      public static SegmentStack create()
      Creates a new MemoryStack with the default size.

      In the initial state, there is no active stack frame. The push() method must be used before any allocations.

    • create

      public static SegmentStack create(long capacity)
      Creates a new MemoryStack with the specified size.

      In the initial state, there is no active stack frame. The push() method must be used before any allocations.

      Parameters:
      capacity - the maximum number of bytes that may be allocated on the stack

    • create

      public static SegmentStack create(MemorySegment segment)
      Creates a new MemoryStack backed by the specified memory segment.

      In the initial state, there is no active stack frame. The push() method must be used before any allocations.

      Parameters:
      segment - the backing memory segment

    • push

      public SegmentStack 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 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
      Specified by:
      push in interface StackAllocator<SegmentStack>
      Returns:
      this stack

    • pop

      public SegmentStack pop()
      Pops the current stack frame and moves the stack pointer to the end of the previous stack frame.
      Specified by:
      pop in interface StackAllocator<SegmentStack>
      Returns:
      this stack

    • close

      public void close()
      Calls 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 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 long 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 push() calls.

    • getPointerAddress

      public long getPointerAddress()
      Returns the memory address at the current stack pointer.

    • getPointer

      public long 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 + pointer points to the first byte of the last allocation.

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

    • setPointer

      public void setPointer(long 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.

    • allocate

      public MemorySegment allocate(long byteSize)
      Same as SegmentAllocator.allocate(long), but with ValueLayout.ADDRESS alignment and no zero-initialization.
      Specified by:
      allocate in interface SegmentAllocator

    • allocate

      public MemorySegment allocate(long byteSize, long byteAlignment)
      Same as Arena.allocate(long, long), but without zero-initialization.
      Specified by:
      allocate in interface SegmentAllocator

    • allocate

      public MemorySegment allocate(MemoryLayout layout)
      Same as SegmentAllocator.allocate(MemoryLayout), but without zero-initialization.
      Specified by:
      allocate in interface SegmentAllocator

    • allocate

      public MemorySegment allocate(MemoryLayout elementLayout, long count)
      Same as SegmentAllocator.allocate(MemoryLayout, long), but without zero-initialization.
      Specified by:
      allocate in interface SegmentAllocator

    • calloc

      public MemorySegment calloc(long byteSize)
      Same as SegmentAllocator.allocate(long).

    • calloc

      public MemorySegment calloc(long byteSize, long byteAlignment)
      Same as Arena.allocate(long, long).

    • calloc

      public MemorySegment calloc(MemoryLayout layout)
      Same as SegmentAllocator.allocate(MemoryLayout).

    • calloc

      public MemorySegment calloc(MemoryLayout elementLayout, long count)
      Same as SegmentAllocator.allocate(MemoryLayout, long).

    • stackGet

      public static SegmentStack stackGet()
      Returns the stack of the current thread.

    • stackPush

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