Module overrungl.core

Package overrungl.util

Class MemoryStack

java.lang.Object

overrungl.Pointer

overrungl.util.MemoryStack

All Implemented Interfaces:

AutoCloseable, SegmentAllocatorPREVIEW, Addressable

public sealed class MemoryStack
extends Pointer
implements SegmentAllocatorPREVIEW, AutoCloseable

MemoryStack relies on preview features of the Java platform:

• MemoryStack refers to one or more preview APIs: Arena, MemoryLayout, MemorySegment, SegmentAllocator.

Programs can only use MemoryStack when preview features are enabled.

Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.

An off-heap memory stack.

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

Since:

0.1.0

Author:

Spasi, lwjgl3, squid233

See Also:

• Configurations.STACK_SIZE
• Configurations.STACK_FRAMES
• Configurations.DEBUG_STACK

Field Summary

Fields

Modifier and Type	Field	Description
protected int	frameIndex

Fields inherited from class overrungl.Pointer

address, allocator, managedSegment

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	MemoryStack(@Nullable MemorySegmentPREVIEW container, MemorySegmentPREVIEW address, long size, ArenaPREVIEW arena)	Creates a new MemoryStack backed by the specified memory region.

Method Summary

Modifier and Type	Method	Description
MemorySegmentPREVIEW	address()	Returns the address of the backing off-heap memory.
MemorySegmentPREVIEW	allocate(long byteSize, long byteAlignment)
MemorySegmentPREVIEW	bytes(byte x)	Single value version of malloc(long, long).
MemorySegmentPREVIEW	bytes(byte... values)	Vararg version of malloc(long, long).
MemorySegmentPREVIEW	bytes(byte x, byte y)	Two value version of malloc(long, long).
MemorySegmentPREVIEW	bytes(byte x, byte y, byte z)	Three value version of malloc(long, long).
MemorySegmentPREVIEW	bytes(byte x, byte y, byte z, byte w)	Four value version of malloc(long, long).
MemorySegmentPREVIEW	calloc(long size)	Calloc version of malloc(long).
MemorySegmentPREVIEW	calloc(long alignment, long size)	Calloc version of malloc(long, long).
MemorySegmentPREVIEW	calloc(MemoryLayoutPREVIEW layout)
MemorySegmentPREVIEW	calloc(MemoryLayoutPREVIEW layout, long num)
void	close()	Calls pop() on this MemoryStack.
static MemoryStackPREVIEW	create()	Creates a new MemoryStack with the default size.
static MemoryStackPREVIEW	create(long capacity)	Creates a new MemoryStack with the specified size.
static MemoryStackPREVIEW	create(MemorySegmentPREVIEW buffer, long size, ArenaPREVIEW arena)	Creates a new MemoryStack backed by the specified memory buffer.
MemorySegmentPREVIEW	doubles(double x)	Single value version of malloc(long, long).
MemorySegmentPREVIEW	doubles(double... values)	Vararg version of malloc(long, long).
MemorySegmentPREVIEW	doubles(double x, double y)	Two value version of malloc(long, long).
MemorySegmentPREVIEW	doubles(double x, double y, double z)	Three value version of malloc(long, long).
MemorySegmentPREVIEW	doubles(double x, double y, double z, double w)	Four value version of malloc(long, long).
MemorySegmentPREVIEW	floats(float x)	Single value version of malloc(long, long).
MemorySegmentPREVIEW	floats(float... values)	Vararg version of malloc(long, long).
MemorySegmentPREVIEW	floats(float x, float y)	Two value version of malloc(long, long).
MemorySegmentPREVIEW	floats(float x, float y, float z)	Three value version of malloc(long, long).
MemorySegmentPREVIEW	floats(float x, float y, float z, float w)	Four value version of malloc(long, long).
int	getFrameIndex()	Returns the current frame index.
long	getPointer()	Returns the current stack pointer.
MemorySegmentPREVIEW	getPointerAddress()	Returns the memory address at the current stack pointer.
long	getSize()	Returns the size of the backing off-heap memory.
MemorySegmentPREVIEW	ints(int x)	Single value version of malloc(long, long).
MemorySegmentPREVIEW	ints(int... values)	Vararg version of malloc(long, long).
MemorySegmentPREVIEW	ints(int x, int y)	Two value version of malloc(long, long).
MemorySegmentPREVIEW	ints(int x, int y, int z)	Three value version of malloc(long, long).
MemorySegmentPREVIEW	ints(int x, int y, int z, int w)	Four value version of malloc(long, long).
MemorySegmentPREVIEW	longs(long x)	Single value version of malloc(long, long).
MemorySegmentPREVIEW	longs(long... values)	Vararg version of malloc(long, long).
MemorySegmentPREVIEW	longs(long x, long y)	Two value version of malloc(long, long).
MemorySegmentPREVIEW	longs(long x, long y, long z)	Three value version of malloc(long, long).
MemorySegmentPREVIEW	longs(long x, long y, long z, long w)	Four value version of malloc(long, long).
MemorySegmentPREVIEW	malloc(long size)	Allocates a MemorySegmentPREVIEW on the stack with alignment equal to POINTER_SIZEPREVIEW.
MemorySegmentPREVIEW	malloc(long alignment, long size)	Allocates an aligned MemorySegmentPREVIEW on the stack.
MemorySegmentPREVIEW	malloc(MemoryLayoutPREVIEW layout)
MemorySegmentPREVIEW	ncalloc(long alignment, long num, long 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.
static MemoryStackPREVIEW	ncreate(MemorySegmentPREVIEW address, long size, ArenaPREVIEW arena)	Creates a new MemoryStack backed by the specified memory region.
MemorySegmentPREVIEW	nmalloc(long alignment, long size)	Allocates a block of size bytes of memory on the stack.
static MemorySegmentPREVIEW	nstackCalloc(long alignment, long num, long size)	Thread-local version of ncalloc(long, long, long).
static MemorySegmentPREVIEW	nstackMalloc(long alignment, long size)	Thread-local version of nmalloc(long, long).
MemorySegmentPREVIEW	pointers(MemorySegmentPREVIEW x)	Single value version of malloc(long, long).
MemorySegmentPREVIEW	pointers(MemorySegmentPREVIEW... values)	Vararg version of malloc(long, long).
MemorySegmentPREVIEW	pointers(MemorySegmentPREVIEW x, MemorySegmentPREVIEW y)	Two value version of malloc(long, long).
MemorySegmentPREVIEW	pointers(MemorySegmentPREVIEW x, MemorySegmentPREVIEW y, MemorySegmentPREVIEW z)	Three value version of malloc(long, long).
MemorySegmentPREVIEW	pointers(MemorySegmentPREVIEW x, MemorySegmentPREVIEW y, MemorySegmentPREVIEW z, MemorySegmentPREVIEW w)	Four value version of malloc(long, long).
MemoryStackPREVIEW	pop()	Pops the current stack frame and moves the stack pointer to the end of the previous stack frame.
MemoryStackPREVIEW	push()	Stores the current stack pointer and pushes a new frame to the stack.
void	setPointer(long pointer)	Sets the current stack pointer.
MemorySegmentPREVIEW	shorts(short x)	Single value version of malloc(long, long).
MemorySegmentPREVIEW	shorts(short... values)	Vararg version of malloc(long, long).
MemorySegmentPREVIEW	shorts(short x, short y)	Two value version of malloc(long, long).
MemorySegmentPREVIEW	shorts(short x, short y, short z)	Three value version of malloc(long, long).
MemorySegmentPREVIEW	shorts(short x, short y, short z, short w)	Four value version of malloc(long, long).
static MemorySegmentPREVIEW	stackCalloc(long size)	Thread-local version of calloc.
static MemoryStackPREVIEW	stackGet()	Returns the stack of the current thread.
static MemorySegmentPREVIEW	stackMalloc(long size)	Thread-local version of malloc.
static MemoryStackPREVIEW	stackPop()	Calls pop() on the stack of the current thread.
static MemoryStackPREVIEW	stackPush()	Calls push() on the stack of the current thread.

Methods inherited from class overrungl.Pointer

allocator, segment, segment

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.foreign.SegmentAllocator^PREVIEW

allocate, allocate, allocate, allocate, allocate, allocate, allocate, allocate, allocate, allocate, allocateArray, allocateArray, allocateArray, allocateArray, allocateArray, allocateArray, allocateArray, allocateArray, allocateUtf8String

Field Details

frameIndex

protected int frameIndex

Constructor Details

MemoryStack

protected MemoryStack(@Nullable
 @Nullable MemorySegmentPREVIEW container,
 MemorySegmentPREVIEW address,
 long size,
 ArenaPREVIEW arena)

Creates a new MemoryStack backed by the specified memory region.

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

Parameters:

container - the backing memory buffer, may be null

address - the backing memory address

size - the backing memory size

arena - the backing arena

Method Details

create

public static MemoryStackPREVIEW 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 MemoryStackPREVIEW 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 MemoryStackPREVIEW create(MemorySegmentPREVIEW buffer,
 long size,
 ArenaPREVIEW arena)

Creates a new MemoryStack backed by the specified memory buffer.

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

Parameters:

buffer - the backing memory buffer

size - the memory buffer size

arena - the backing arena

ncreate

public static MemoryStackPREVIEW ncreate(MemorySegmentPREVIEW address,
 long size,
 ArenaPREVIEW arena)

Creates a new MemoryStack backed by the specified memory region.

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

Parameters:

address - the backing memory address

size - the backing memory size

arena - the backing arena

push

public MemoryStackPREVIEW 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

Returns:

this stack

pop

public MemoryStackPREVIEW 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 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

address

public MemorySegmentPREVIEW address()

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.

Specified by:

address in interface Addressable

Overrides:

address in class Pointer

Returns:

the address of the backing off-heap memory

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.

Returns:

the size of the backing off-heap memory

getFrameIndex

public int getFrameIndex()

Returns the current frame index.

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

Returns:

the current frame index

getPointerAddress

public MemorySegmentPREVIEW getPointerAddress()

Returns the memory address at the current stack pointer.

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.

Returns:

the current stack pointer

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.

nmalloc

public MemorySegmentPREVIEW nmalloc(long alignment,
 long 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 MemorySegmentPREVIEW ncalloc(long alignment,
 long num,
 long 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 - 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 MemorySegmentPREVIEW malloc(long alignment,
 long size)

Allocates an aligned MemorySegment^PREVIEW on the stack.

Parameters:

alignment - the required buffer alignment

size - the number of elements in the buffer

Returns:

the allocated buffer

calloc

public MemorySegmentPREVIEW calloc(long alignment,
 long size)

Calloc version of malloc(long, long).

malloc

public MemorySegmentPREVIEW malloc(long size)

Allocates a MemorySegment^PREVIEW on the stack with alignment equal to POINTER_SIZE^PREVIEW.

Parameters:

size - the allocation size

Returns:

the memory address on the stack for the requested allocation

malloc

public MemorySegmentPREVIEW malloc(MemoryLayoutPREVIEW layout)

calloc

public MemorySegmentPREVIEW calloc(long size)

Calloc version of malloc(long).

calloc

public MemorySegmentPREVIEW calloc(MemoryLayoutPREVIEW layout,
 long num)

calloc

public MemorySegmentPREVIEW calloc(MemoryLayoutPREVIEW layout)

allocate

public MemorySegmentPREVIEW allocate(long byteSize,
 long byteAlignment)
                              throws IllegalArgumentException

Specified by:

allocate in interface SegmentAllocatorPREVIEW

Throws:

IllegalArgumentException

bytes

public MemorySegmentPREVIEW bytes(byte x)

Single value version of malloc(long, long).

bytes

public MemorySegmentPREVIEW bytes(byte x,
 byte y)

Two value version of malloc(long, long).

bytes

public MemorySegmentPREVIEW bytes(byte x,
 byte y,
 byte z)

Three value version of malloc(long, long).

bytes

public MemorySegmentPREVIEW bytes(byte x,
 byte y,
 byte z,
 byte w)

Four value version of malloc(long, long).

bytes

public MemorySegmentPREVIEW bytes(byte... values)

Vararg version of malloc(long, long).

shorts

public MemorySegmentPREVIEW shorts(short x)

Single value version of malloc(long, long).

shorts

public MemorySegmentPREVIEW shorts(short x,
 short y)

Two value version of malloc(long, long).

shorts

public MemorySegmentPREVIEW shorts(short x,
 short y,
 short z)

Three value version of malloc(long, long).

shorts

public MemorySegmentPREVIEW shorts(short x,
 short y,
 short z,
 short w)

Four value version of malloc(long, long).

shorts

public MemorySegmentPREVIEW shorts(short... values)

Vararg version of malloc(long, long).

ints

public MemorySegmentPREVIEW ints(int x)

Single value version of malloc(long, long).

ints

public MemorySegmentPREVIEW ints(int x,
 int y)

Two value version of malloc(long, long).

ints

public MemorySegmentPREVIEW ints(int x,
 int y,
 int z)

Three value version of malloc(long, long).

ints

public MemorySegmentPREVIEW ints(int x,
 int y,
 int z,
 int w)

Four value version of malloc(long, long).

ints

public MemorySegmentPREVIEW ints(int... values)

Vararg version of malloc(long, long).

longs

public MemorySegmentPREVIEW longs(long x)

Single value version of malloc(long, long).

longs

public MemorySegmentPREVIEW longs(long x,
 long y)

Two value version of malloc(long, long).

longs

public MemorySegmentPREVIEW longs(long x,
 long y,
 long z)

Three value version of malloc(long, long).

longs

public MemorySegmentPREVIEW longs(long x,
 long y,
 long z,
 long w)

Four value version of malloc(long, long).

longs

public MemorySegmentPREVIEW longs(long... values)

Vararg version of malloc(long, long).

floats

public MemorySegmentPREVIEW floats(float x)

Single value version of malloc(long, long).

floats

public MemorySegmentPREVIEW floats(float x,
 float y)

Two value version of malloc(long, long).

floats

public MemorySegmentPREVIEW floats(float x,
 float y,
 float z)

Three value version of malloc(long, long).

floats

public MemorySegmentPREVIEW floats(float x,
 float y,
 float z,
 float w)

Four value version of malloc(long, long).

floats

public MemorySegmentPREVIEW floats(float... values)

Vararg version of malloc(long, long).

doubles

public MemorySegmentPREVIEW doubles(double x)

Single value version of malloc(long, long).

doubles

public MemorySegmentPREVIEW doubles(double x,
 double y)

Two value version of malloc(long, long).

doubles

public MemorySegmentPREVIEW doubles(double x,
 double y,
 double z)

Three value version of malloc(long, long).

doubles

public MemorySegmentPREVIEW doubles(double x,
 double y,
 double z,
 double w)

Four value version of malloc(long, long).

doubles

public MemorySegmentPREVIEW doubles(double... values)

Vararg version of malloc(long, long).

pointers

public MemorySegmentPREVIEW pointers(MemorySegmentPREVIEW x)

Single value version of malloc(long, long).

pointers

public MemorySegmentPREVIEW pointers(MemorySegmentPREVIEW x,
 MemorySegmentPREVIEW y)

Two value version of malloc(long, long).

pointers

public MemorySegmentPREVIEW pointers(MemorySegmentPREVIEW x,
 MemorySegmentPREVIEW y,
 MemorySegmentPREVIEW z)

Three value version of malloc(long, long).

pointers

public MemorySegmentPREVIEW pointers(MemorySegmentPREVIEW x,
 MemorySegmentPREVIEW y,
 MemorySegmentPREVIEW z,
 MemorySegmentPREVIEW w)

Four value version of malloc(long, long).

pointers

public MemorySegmentPREVIEW pointers(MemorySegmentPREVIEW... values)

Vararg version of malloc(long, long).

stackGet

public static MemoryStackPREVIEW stackGet()

Returns the stack of the current thread.

Returns:

the stack of the current thread

stackPush

public static MemoryStackPREVIEW stackPush()

Calls push() on the stack of the current thread.

Returns:

the stack of the current thread.

stackPop

public static MemoryStackPREVIEW stackPop()

Calls pop() on the stack of the current thread.

Returns:

the stack of the current thread.

nstackMalloc

public static MemorySegmentPREVIEW nstackMalloc(long alignment,
 long size)

Thread-local version of nmalloc(long, long).

nstackCalloc

public static MemorySegmentPREVIEW nstackCalloc(long alignment,
 long num,
 long size)

Thread-local version of ncalloc(long, long, long).

stackMalloc

public static MemorySegmentPREVIEW stackMalloc(long size)

Thread-local version of malloc.

stackCalloc

public static MemorySegmentPREVIEW stackCalloc(long size)

Thread-local version of calloc.