Classes to support low-level, safe and efficient memory access. *
* The key abstractions introduced by this package are {@link jdk.incubator.foreign.MemorySegment} and {@link jdk.incubator.foreign.MemoryAddress}. * The first models a contiguous memory region, which can reside either inside or outside the Java heap; the latter models an address - which can * sometimes be expressed as an offset into a given segment. A memory address represents the main access coordinate of a memory access var handle, which can be obtained * using the combinator methods defined in the {@link jdk.incubator.foreign.MemoryHandles} class. Finally, the {@link jdk.incubator.foreign.MemoryLayout} class * hierarchy enables description of memory layouts and basic operations such as computing the size in bytes of a given * layout, obtain its alignment requirements, and so on. Memory layouts also provide an alternate, more abstract way, to produce * memory access var handles, e.g. using layout paths. * * For example, to allocate an off-heap memory region big enough to hold 10 values of the primitive type {@code int}, and fill it with values * ranging from {@code 0} to {@code 9}, we can use the following code: * *
{@code
static final VarHandle intHandle = MemoryHandles.varHandle(int.class, ByteOrder.nativeOrder());
try (MemorySegment segment = MemorySegment.allocateNative(10 * 4)) {
MemoryAddress base = segment.baseAddress();
for (long i = 0 ; i < 10 ; i++) {
intHandle.set(base.addOffset(i * 4), (int)i);
}
}
* }
*
* Here we create a var handle, namely {@code intHandle}, to manipulate values of the primitive type {@code int}, at
* a given memory location. Also, {@code intHandle} is stored in a {@code static} and {@code final} field, to achieve
* better performance and allow for inlining of the memory access operation through the {@link java.lang.invoke.VarHandle}
* instance. We then create a native memory segment, that is, a memory segment backed by
* off-heap memory; the size of the segment is 40 bytes, enough to store 10 values of the primitive type {@code int}.
* The segment is created inside a try-with-resources construct: this idiom ensures that all the memory resources
* associated with the segment will be released at the end of the block, according to the semantics described in
* Section {@jls 14.20.3} of The Java Language Specification. Inside the try-with-resources block, we initialize
* the contents of the memory segment; more specifically, if we view the memory segment as a set of 10 adjacent slots,
* {@code s[i]}, where {@code 0 <= i < 10}, where the size of each slot is exactly 4 bytes, the initialization logic above will set each slot
* so that {@code s[i] = i}, again where {@code 0 <= i < 10}.
*
* * The deterministic deallocation model differs significantly from the implicit strategies adopted within other APIs, most * notably the {@link java.nio.ByteBuffer} API: in that case, when a native byte buffer is created (see {@link java.nio.ByteBuffer#allocateDirect(int)}), * the underlying memory is not released until the byte buffer reference becomes unreachable. While implicit deallocation * models such as this can be very convenient - clients do not have to remember to close a direct buffer - such models can also make it * hard for clients to ensure that the memory associated with a direct buffer has indeed been released. * *
* Since memory segments can be closed (see above), a memory address is also validated (upon access) to make sure that * the segment it belongs to has not been closed prematurely. We call this guarantee temporal safety. Note that, * in the general case, guaranteeing temporal safety can be hard, as multiple threads could attempt to access and/or close * the same memory segment concurrently. The memory access API addresses this problem by imposing strong * thread-confinement guarantees on memory segments: each * memory segment is associated with an owner thread, which is the only thread that can either access or close the segment. *
* Together, spatial and temporal safety ensure that each memory access operation either succeeds - and accesses a valid * memory location - or fails. */ package jdk.incubator.foreign;