com.oracle.svm.core.os

Interface VirtualMemoryProvider

All Known Implementing Classes:

PosixVirtualMemoryProvider, WindowsVirtualMemoryProvider

public interface VirtualMemoryProvider

Primitive operations for low-level virtual memory management.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	VirtualMemoryProvider.Access Bitmask with the modes of protection for committed or mapped memory.

Method Summary

Modifier and Type	Method and Description
org.graalvm.word.Pointer	commit(org.graalvm.word.PointerBase start, org.graalvm.word.UnsignedWord nbytes, int access) Commit an address range so that physical memory or swap memory can be provisioned for it, and the memory can be accessed in the specified access modes.
int	free(org.graalvm.word.PointerBase start, org.graalvm.word.UnsignedWord nbytes) Free an entire reserved address range (which may be committed or partially committed).
static VirtualMemoryProvider	get()
default org.graalvm.word.UnsignedWord	getAlignment() Returns the alignment used by virtual memory management, which is generally equal to the granularity or a multiple thereof.
org.graalvm.word.UnsignedWord	getGranularity() Returns the granularity of virtual memory management, which is generally the operating system's page size.
org.graalvm.word.Pointer	mapFile(org.graalvm.word.PointerBase start, org.graalvm.word.UnsignedWord nbytes, org.graalvm.word.WordBase fileHandle, org.graalvm.word.UnsignedWord offset, int access) Map a region of an open file to the specified address range.
int	protect(org.graalvm.word.PointerBase start, org.graalvm.word.UnsignedWord nbytes, int access) Change the protection of a committed address range, or of a subrange of a committed address range, so that the memory can be accessed in the specified access modes.
org.graalvm.word.Pointer	reserve(org.graalvm.word.UnsignedWord nbytes, org.graalvm.word.UnsignedWord alignment) Reserve an address range that fits the specified number of bytes.
int	uncommit(org.graalvm.word.PointerBase start, org.graalvm.word.UnsignedWord nbytes) Uncommit a committed address range, or a subrange of a committed address range, so that it returns to reserved state in which the memory is not intended to be accessed, and no physical memory or swap memory is guaranteed to be provisioned for it.

Method Detail

get

static VirtualMemoryProvider get()

getGranularity

org.graalvm.word.UnsignedWord getGranularity()

Returns the granularity of virtual memory management, which is generally the operating system's page size.

getAlignment

default org.graalvm.word.UnsignedWord getAlignment()

Returns the alignment used by virtual memory management, which is generally equal to the granularity or a multiple thereof.

reserve

org.graalvm.word.Pointer reserve(org.graalvm.word.UnsignedWord nbytes,
                                 org.graalvm.word.UnsignedWord alignment)

Reserve an address range that fits the specified number of bytes. The reserved address range is not intended to be accessed until VirtualMemoryProvider.commit(org.graalvm.word.PointerBase, org.graalvm.word.UnsignedWord, int) is called on the range (or on a part of the range). Even then, the call to VirtualMemoryProvider.commit(org.graalvm.word.PointerBase, org.graalvm.word.UnsignedWord, int) is not guaranteed to succeed because no physical memory or swap memory is guaranteed to be provisioned for the reserved range.

Parameters:

nbytes - The size in bytes of the address range to be reserved, which will be rounded up to a multiple of the granularity.

alignment - The alignment in bytes of the start of the address range to be reserved.

Returns:

An aligned pointer to the beginning of the reserved address range, or WordFactory.nullPointer() in case of an error.

mapFile

org.graalvm.word.Pointer mapFile(org.graalvm.word.PointerBase start,
                                 org.graalvm.word.UnsignedWord nbytes,
                                 org.graalvm.word.WordBase fileHandle,
                                 org.graalvm.word.UnsignedWord offset,
                                 int access)

Map a region of an open file to the specified address range. When write access is requested and mapped memory is written, that memory is copied before writing, and no modifications are ever written to the underlying file (copy on write). If the file's contents change after it has been mapped, it is undefined whether these changes become visible through the mapping.

Parameters:

start - The start of the address range to contain the mapping, which must be a multiple of the granularity, or null to select an available (unreserved, uncommitted) address range in an arbitrary location.

nbytes - The size in bytes of the file region to be mapped, which need not be a multiple of the granularity.

fileHandle - A platform-specific open file handle.

offset - The offset in bytes of the region within the file to be mapped, which must be a multiple of the granularity.

access - The modes in which the memory is permitted to be accessed, see VirtualMemoryProvider.Access.

Returns:

The start of the mapped address range, or WordFactory.nullPointer() in case of an error.

commit

org.graalvm.word.Pointer commit(org.graalvm.word.PointerBase start,
                                org.graalvm.word.UnsignedWord nbytes,
                                int access)

Commit an address range so that physical memory or swap memory can be provisioned for it, and the memory can be accessed in the specified access modes. No guarantees are made about the memory contents.

This method may be called for a specific range that was previously reserved with VirtualMemoryProvider.reserve(org.graalvm.word.UnsignedWord, org.graalvm.word.UnsignedWord), or for a range committed with VirtualMemoryProvider.commit(org.graalvm.word.PointerBase, org.graalvm.word.UnsignedWord, int), or for a subrange of such ranges. If the provided range covers addresses outside of such ranges, or from multiple independently reserved ranges, undefined effects can occur.

Alternatively, NULL can be passed for the start address, in which case an available (unreserved, uncommitted) address range in an arbitrary but aligned location will be selected, reserved and committed in one step.

Parameters:

start - The start of the address range to be committed, which must be a multiple of the granularity, or NULL to select an available (unreserved, uncommitted) address range in an arbitrary but aligned location.

nbytes - The size in bytes of the address range to be committed, which will be rounded up to a multiple of the granularity.

access - The modes in which the memory is permitted to be accessed, see VirtualMemoryProvider.Access.

Returns:

The start of the committed address range, or WordFactory.nullPointer() in case of an error, such as inadequate physical memory.

protect

int protect(org.graalvm.word.PointerBase start,
            org.graalvm.word.UnsignedWord nbytes,
            int access)

Change the protection of a committed address range, or of a subrange of a committed address range, so that the memory can be accessed in the specified access modes.

Parameters:

start - The start of the address range to be protected, which must be a multiple of the granularity.

nbytes - The size in bytes of the address range to be protected, which will be rounded up to a multiple of the granularity.

access - The modes in which the memory is permitted to be accessed, see VirtualMemoryProvider.Access.

Returns:

0 when successful, or a non-zero implementation-specific error code.

uncommit

int uncommit(org.graalvm.word.PointerBase start,
             org.graalvm.word.UnsignedWord nbytes)

Uncommit a committed address range, or a subrange of a committed address range, so that it returns to reserved state in which the memory is not intended to be accessed, and no physical memory or swap memory is guaranteed to be provisioned for it. Calling this method for an already uncommitted (reserved) or only partially committed address range is not an error.

Parameters:

start - The start of the address range to be uncommitted, which must be a multiple of the granularity.

nbytes - The size in bytes of the address range to be uncommitted, which will be rounded up to a multiple of the granularity.

Returns:

0 when successful, or a non-zero implementation-specific error code.

free

int free(org.graalvm.word.PointerBase start,
         org.graalvm.word.UnsignedWord nbytes)

Free an entire reserved address range (which may be committed or partially committed). No subrange of a reserved range and no non-reserved range must be specified, or undefined effects can occur. After the address range has been successfully freed, it becomes available for reuse by the system and might be returned from future calls to VirtualMemoryProvider.reserve(org.graalvm.word.UnsignedWord, org.graalvm.word.UnsignedWord) and commit(NULL, ..).

Parameters:

start - The start of the address range to be freed, which must be the exact address that was originally returned by VirtualMemoryProvider.reserve(org.graalvm.word.UnsignedWord, org.graalvm.word.UnsignedWord) or commit(NULL, ..)

nbytes - The size in bytes of the address range to be freed, which must be the exact size that was originally passed to VirtualMemoryProvider.reserve(org.graalvm.word.UnsignedWord, org.graalvm.word.UnsignedWord) or commit(NULL, ..)

Returns:

0 when successful, or a non-zero implementation-specific error code.