Module overrungl.core

Package overrungl.internal

Class RuntimeHelper

java.lang.Object

overrungl.internal.RuntimeHelper

public final class RuntimeHelper
extends Object

RuntimeHelper relies on preview features of the Java platform:

• RuntimeHelper refers to one or more preview APIs: AddressLayout, FunctionDescriptor, Linker, MemorySegment, SegmentAllocator, SymbolLookup.

Programs can only use RuntimeHelper when preview features are enabled.

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

The runtime helper, for internal use.

Since:

0.1.0

Author:

squid233

Field Summary

Fields

Modifier and Type	Field	Description
static final AddressLayoutPREVIEW	ADDRESS_UNBOUNDED	An unbounded address layout.
static final LinkerPREVIEW	LINKER	The native linker.

Method Summary

Modifier and Type	Method	Description
static MemorySegmentPREVIEW	allocateUtf16LEString(SegmentAllocatorPREVIEW allocator, String str)	Deprecated.
static <T> void	consume(T t)	Make sure a method handle is returned as the specified type to deal with MethodHandle::invokeExact.
static @Nullable MethodHandle	downcallSafe(@Nullable MemorySegmentPREVIEW symbol, FunctionDescriptorPREVIEW function, Linker.OptionPREVIEW... options)	Creates a downcall handle or null.
static @Nullable MethodHandle	downcallSafe(@Nullable MemorySegmentPREVIEW symbol, FunctionDescriptors function, Linker.OptionPREVIEW... options)	Creates a downcall handle or null.
static MethodHandle	downcallThrow(Optional<MemorySegmentPREVIEW> optional, FunctionDescriptorPREVIEW function, Linker.OptionPREVIEW... options)	Creates a downcall handle or throws exception.
static MethodHandle	downcallThrow(Optional<MemorySegmentPREVIEW> optional, FunctionDescriptors function, Linker.OptionPREVIEW... options)	Creates a downcall handle or throws exception.
static String	getUtf16LEString(MemorySegmentPREVIEW segment, long offset)	Deprecated.
static boolean	isNullptr(@Nullable MemorySegmentPREVIEW segment)	Returns true if segment is a null pointer.
static SymbolLookupPREVIEW	load(String module, String basename, String version)	Loads a library from classpath or local.
static boolean[]	toArray(MemorySegmentPREVIEW seg, boolean[] arr)	Gets the booleans from a boolean array.
static byte[]	toArray(MemorySegmentPREVIEW seg, byte[] arr)	Gets the bytes from a byte array.
static double[]	toArray(MemorySegmentPREVIEW seg, double[] arr)	Gets the doubles from a double array.
static float[]	toArray(MemorySegmentPREVIEW seg, float[] arr)	Gets the floats from a float array.
static int[]	toArray(MemorySegmentPREVIEW seg, int[] arr)	Gets the ints from an int array.
static long[]	toArray(MemorySegmentPREVIEW seg, long[] arr)	Gets the longs from a long array.
static short[]	toArray(MemorySegmentPREVIEW seg, short[] arr)	Gets the shorts from a short array.
static MemorySegmentPREVIEW[]	toArray(MemorySegmentPREVIEW seg, MemorySegmentPREVIEW[] arr)	Gets the addresses from an address array.
static <T> T[]	toArray(MemorySegmentPREVIEW seg, T[] arr, Function<MemorySegmentPREVIEW,T> generator)	Gets the objects from an address array.
static String[]	toUnboundedArray(MemorySegmentPREVIEW seg, String[] arr)	Gets the strings from an unbounded address array.
static <T> T[]	toUnboundedArray(MemorySegmentPREVIEW seg, T[] arr, Function<MemorySegmentPREVIEW,T> generator)	Gets the objects from an address array.
static String	unboundPointerString(MemorySegmentPREVIEW segment)	Gets a string from the given pointer of a string.
static String	unboundPointerString(MemorySegmentPREVIEW segment, int index)	Gets a string from the given pointer of a string at the given index.
static String	unknownToken(int token)	Generates a string for unknown token.
static String	unknownToken(String description, int token)	Generates a string for unknown token.

Methods inherited from class java.lang.Object

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

Field Details

LINKER

public static final LinkerPREVIEW LINKER

The native linker.

ADDRESS_UNBOUNDED

public static final AddressLayoutPREVIEW ADDRESS_UNBOUNDED

An unbounded address layout.

Method Details

allocateUtf16LEString

@Deprecated(since="22")
public static MemorySegmentPREVIEW allocateUtf16LEString(SegmentAllocatorPREVIEW allocator,
 String str)

Deprecated.

getUtf16LEString

@Deprecated(since="22")
public static String getUtf16LEString(MemorySegmentPREVIEW segment,
 long offset)

Deprecated.

unboundPointerString

public static String unboundPointerString(MemorySegmentPREVIEW segment)

Gets a string from the given pointer of a string.

Parameters:

segment - the memory segment.

Returns:

the string.

unboundPointerString

public static String unboundPointerString(MemorySegmentPREVIEW segment,
 int index)

Gets a string from the given pointer of a string at the given index.

Parameters:

segment - the memory segment.

index - the index.

Returns:

the string.

consume

public static <T> void consume(T t)

Make sure a method handle is returned as the specified type to deal with MethodHandle::invokeExact.

Type Parameters:

T - the return type.

Parameters:

t - the invoking method.

unknownToken

public static String unknownToken(int token)

Generates a string for unknown token.

Parameters:

token - the token.

Returns:

the string formatted in Unknown [0x\{toHexString(token)}].

unknownToken

public static String unknownToken(String description,
 int token)

Generates a string for unknown token.

Parameters:

description - the description. default to Unknown

token - the token.

Returns:

the string is formatted in STR."\{description} [0x\{toHexString(token)}]".

load

public static SymbolLookupPREVIEW load(String module,
 String basename,
 String version)
                                throws IllegalStateException

Loads a library from classpath or local.

Parameters:

module - the module name. e.x. glfw

basename - the basename of the library (without file extensions)

version - the version suffix

Returns:

the SymbolLookup^PREVIEW

Throws:

IllegalStateException - if file isn't found

isNullptr

public static boolean isNullptr(@Nullable
 @Nullable MemorySegmentPREVIEW segment)

Returns true if segment is a null pointer.

Parameters:

segment - the segment.

Returns:

true if segment is a null pointer

downcallSafe

@Nullable
public static @Nullable MethodHandle downcallSafe(@Nullable
 @Nullable MemorySegmentPREVIEW symbol,
 FunctionDescriptorPREVIEW function,
 Linker.OptionPREVIEW... options)

Creates a downcall handle or null.

Parameters:

symbol - the address of the target function.

function - the function descriptor of the target function.

options - the linker options associated with this linkage request.

Returns:

a downcall method handle. or null if the symbol MemorySegment.NULL^PREVIEW

downcallThrow

public static MethodHandle downcallThrow(Optional<MemorySegmentPREVIEW> optional,
 FunctionDescriptorPREVIEW function,
 Linker.OptionPREVIEW... options)

Creates a downcall handle or throws exception.

Parameters:

optional - the optional contained the address of the target function.

function - the function descriptor of the target function.

options - the linker options associated with this linkage request.

Returns:

a downcall method handle.

downcallSafe

@Nullable
public static @Nullable MethodHandle downcallSafe(@Nullable
 @Nullable MemorySegmentPREVIEW symbol,
 FunctionDescriptors function,
 Linker.OptionPREVIEW... options)

Creates a downcall handle or null.

Parameters:

symbol - the address of the target function.

function - the function descriptor of the target function.

options - the linker options associated with this linkage request.

Returns:

a downcall method handle. or null if the symbol MemorySegment.NULL^PREVIEW

downcallThrow

public static MethodHandle downcallThrow(Optional<MemorySegmentPREVIEW> optional,
 FunctionDescriptors function,
 Linker.OptionPREVIEW... options)

Creates a downcall handle or throws exception.

Parameters:

optional - the optional contained the address of the target function.

function - the function descriptor of the target function.

options - the linker options associated with this linkage request.

Returns:

a downcall method handle.

toArray

public static <T> T[] toArray(MemorySegmentPREVIEW seg,
 T[] arr,
 Function<MemorySegmentPREVIEW,T> generator)

Gets the objects from an address array.

Type Parameters:

T - the array type

Parameters:

seg - the memory segment contained objects. native type: void**

arr - the array to hold the result

generator - the generator, from a zero-length address to the array type

Returns:

arr

toUnboundedArray

public static <T> T[] toUnboundedArray(MemorySegmentPREVIEW seg,
 T[] arr,
 Function<MemorySegmentPREVIEW,T> generator)

Gets the objects from an address array.

Type Parameters:

T - the array type

Parameters:

seg - the memory segment contained objects. native type: void**

arr - the array to hold the result

generator - the generator, from an unbounded address to the array type

Returns:

arr

toArray

public static MemorySegmentPREVIEW[] toArray(MemorySegmentPREVIEW seg,
 MemorySegmentPREVIEW[] arr)

Gets the addresses from an address array.

Parameters:

seg - the memory segment contained addresses. native type: void**

arr - the array to hold the result

Returns:

an array of the zero-length addresses.

toUnboundedArray

public static String[] toUnboundedArray(MemorySegmentPREVIEW seg,
 String[] arr)

Gets the strings from an unbounded address array.

Parameters:

seg - the memory segment contained strings. native type: char**

arr - the array to hold the result

Returns:

arr

toArray

public static boolean[] toArray(MemorySegmentPREVIEW seg,
 boolean[] arr)

Gets the booleans from a boolean array.

Parameters:

seg - the memory segment contained booleans. native type: boolean*

arr - the array to hold the result

Returns:

arr

toArray

public static byte[] toArray(MemorySegmentPREVIEW seg,
 byte[] arr)

Gets the bytes from a byte array.

Parameters:

seg - the memory segment contained bytes. native type: byte*

arr - the array to hold the result

Returns:

arr

toArray

public static short[] toArray(MemorySegmentPREVIEW seg,
 short[] arr)

Gets the shorts from a short array.

Parameters:

seg - the memory segment contained shorts. native type: short*

arr - the array to hold the result

Returns:

arr

toArray

public static int[] toArray(MemorySegmentPREVIEW seg,
 int[] arr)

Gets the ints from an int array.

Parameters:

seg - the memory segment contained ints. native type: int*

arr - the array to hold the result

Returns:

arr

toArray

public static long[] toArray(MemorySegmentPREVIEW seg,
 long[] arr)

Gets the longs from a long array.

Parameters:

seg - the memory segment contained longs. native type: long*

arr - the array to hold the result

Returns:

arr

toArray

public static float[] toArray(MemorySegmentPREVIEW seg,
 float[] arr)

Gets the floats from a float array.

Parameters:

seg - the memory segment contained floats. native type: float*

arr - the array to hold the result

Returns:

arr

toArray

public static double[] toArray(MemorySegmentPREVIEW seg,
 double[] arr)

Gets the doubles from a double array.

Parameters:

seg - the memory segment contained doubles. native type: double*

arr - the array to hold the result

Returns:

arr