Module overrungl.core

Package overrungl.util

Class MemoryUtil

java.lang.Object

overrungl.util.MemoryUtil

public final class MemoryUtil
extends Object

MemoryUtil relies on preview features of the Java platform:

• MemoryUtil refers to one or more preview APIs: AddressLayout, MemoryLayout, MemorySegment.

Programs can only use MemoryUtil when preview features are enabled.

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

The standard-C memory allocator.

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 long	NULL	The address of NULL.

Method Summary

Modifier and Type	Method	Description
static MemorySegmentPREVIEW	calloc(long number, long size)	Allocates an array in memory with elements initialized to 0.
static MemorySegmentPREVIEW	calloc(long number, MemoryLayoutPREVIEW layout)	Allocates an array in memory with elements initialized to 0.
static void	checkAlignment(long alignment)	Checks whether alignment is greater than 0 and is a power-of-two value.
static void	checkByteSize(long byteSize)	Checks whether byteSize is greater than 0 or equals to 0.
static void	free(@Nullable MemorySegmentPREVIEW memblock)	Deallocates or frees a memory block.
static boolean	isNullptr(long address)	Returns true if address is 0L.
static boolean	isNullptr(@Nullable MemorySegmentPREVIEW segment)	Returns true if segment is a null pointer.
static MemorySegmentPREVIEW	malloc(long size)	Allocates memory blocks.
static MemorySegmentPREVIEW	malloc(MemoryLayoutPREVIEW layout)	The layout version of malloc(long)PREVIEW.
static MemorySegmentPREVIEW	memcpy(MemorySegmentPREVIEW dest, MemorySegmentPREVIEW src, long count)	Copies bytes between buffers.
static MemorySegmentPREVIEW	memmove(MemorySegmentPREVIEW dest, MemorySegmentPREVIEW src, long count)	Moves one buffer to another.
static MemorySegmentPREVIEW	memset(MemorySegmentPREVIEW dest, int c, long count)	Sets a buffer to a specified character.
static MemorySegmentPREVIEW	realloc(@Nullable MemorySegmentPREVIEW memblock, long size)	Reallocate memory blocks.

Methods inherited from class java.lang.Object

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

Field Details

NULL

public static final long NULL

The address of NULL.

See Also:

• Constant Field Values

ADDRESS_UNBOUNDED

public static final AddressLayoutPREVIEW ADDRESS_UNBOUNDED

An unbounded address layout.

Method Details

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

isNullptr

public static boolean isNullptr(long address)

Returns true if address is 0L.

Parameters:

address - the address.

Returns:

true if address is 0L

checkByteSize

public static void checkByteSize(long byteSize)
                          throws IllegalArgumentException

Checks whether byteSize is greater than 0 or equals to 0.

Parameters:

byteSize - the size, in bytes.

Throws:

IllegalArgumentException - if byteSize < 0.

checkAlignment

public static void checkAlignment(long alignment)
                           throws IllegalArgumentException

Checks whether alignment is greater than 0 and is a power-of-two value.

Parameters:

alignment - the alignment, in bytes.

Throws:

IllegalArgumentException - if alignment <= 0, or if alignment is not a power of 2.

malloc

public static MemorySegmentPREVIEW malloc(long size)

Allocates memory blocks.

The malloc function allocates a memory block of at least size bytes. The block may be larger than size bytes because of the space that's required for alignment and maintenance information.

Parameters:

size - Bytes to allocate.

Returns:

malloc returns a void pointer to the allocated space, or NULL^PREVIEW if there is insufficient memory available. The storage space pointed to by the return value is suitably aligned for storage of any type of object that has an alignment requirement less than or equal to that of the fundamental alignment.

See Also:

• malloc(MemoryLayout)^PREVIEW

malloc

public static MemorySegmentPREVIEW malloc(MemoryLayoutPREVIEW layout)

The layout version of malloc(long)^PREVIEW.

Parameters:

layout - the memory layout.

Returns:

the allocated space.

See Also:

• malloc(long)^PREVIEW

calloc

public static MemorySegmentPREVIEW calloc(long number,
 long size)

Allocates an array in memory with elements initialized to 0.

The calloc function allocates storage space for an array of number elements, each of length size bytes. Each element is initialized to 0.

Parameters:

number - Number of elements.

size - Length in bytes of each element.

Returns:

calloc returns a pointer to the allocated space. The storage space pointed to by the return value is suitably aligned for storage of any type of object.

See Also:

• calloc(long, MemoryLayout)^PREVIEW

calloc

public static MemorySegmentPREVIEW calloc(long number,
 MemoryLayoutPREVIEW layout)

Allocates an array in memory with elements initialized to 0.

The calloc function allocates storage space for an array of number elements, each of length size bytes. Each element is initialized to 0.

Parameters:

number - Number of elements.

layout - Length in bytes of each element.

Returns:

calloc returns a pointer to the allocated space. The storage space pointed to by the return value is suitably aligned for storage of any type of object.

See Also:

• calloc(long, long)^PREVIEW

realloc

public static MemorySegmentPREVIEW realloc(@Nullable
 @Nullable MemorySegmentPREVIEW memblock,
 long size)

Reallocate memory blocks.

The realloc function changes the size of an allocated memory block. The memblock argument points to the beginning of the memory block. If memblock is NULL, realloc behaves the same way as malloc and allocates a new block of size bytes. If memblock is not NULL, it should be a pointer returned by a previous call to calloc, malloc, or realloc.

The size argument gives the new size of the block, in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes, although the new block can be in a different location. Because the new block can be in a new memory location, the pointer returned by realloc is not guaranteed to be the pointer passed through the memblock argument. realloc does not zero newly allocated memory in the case of buffer growth.

Parameters:

memblock - Pointer to previously allocated memory block.

size - New size in bytes.

Returns:

realloc returns a MemorySegment^PREVIEW to the reallocated (and possibly moved) memory block.

If there is not enough available memory to expand the block to the given size, the original block is left unchanged, and NULL is returned.

If size is zero, then the block pointed to by memblock is freed; the return value is NULL, and memblock is left pointing at a freed block.

The return value points to a storage space that is suitably aligned for storage of any type of object.

free

public static void free(@Nullable
 @Nullable MemorySegmentPREVIEW memblock)

Deallocates or frees a memory block.

The free function deallocates a memory block (memblock) that was previously allocated by a call to calloc, malloc, or realloc. The number of freed bytes is equivalent to the number of bytes requested when the block was allocated (or reallocated, in the case of realloc). If memblock is NULL, the pointer is ignored and free immediately returns. Attempting to free an invalid pointer (a pointer to a memory block that wasn't allocated by calloc, malloc, or realloc) may affect subsequent allocation requests and cause errors.

Parameters:

memblock - Previously allocated memory block to be freed.

memcpy

public static MemorySegmentPREVIEW memcpy(MemorySegmentPREVIEW dest,
 MemorySegmentPREVIEW src,
 long count)

Copies bytes between buffers.

memcpy copies count bytes from src to dest. If the source and destination overlap, the behavior of memcpy is undefined. Use memmove to handle overlapping regions.

Make sure that the destination buffer is the same size or larger than the source buffer.

Parameters:

dest - New buffer.

src - Buffer to copy from.

count - Number of characters to copy.

Returns:

The value of dest.

memmove

public static MemorySegmentPREVIEW memmove(MemorySegmentPREVIEW dest,
 MemorySegmentPREVIEW src,
 long count)

Moves one buffer to another.

Copies count bytes from src to dest. If some regions of the source area and the destination overlap, both functions ensure that the original source bytes in the overlapping region are copied before being overwritten.

Security Note Make sure that the destination buffer is the same size or larger than the source buffer.

Parameters:

dest - Destination object.

src - Source object.

count - Number of bytes to copy.

Returns:

The value of dest.

memset

public static MemorySegmentPREVIEW memset(MemorySegmentPREVIEW dest,
 int c,
 long count)

Sets a buffer to a specified character.

Sets the first count characters of dest to the character c.

Security Note Make sure that the destination buffer has enough room for at least count characters.

Parameters:

dest - Pointer to destination.

c - Character to set.

count - Number of characters.

Returns:

The value of dest.