public sealed interface MemorySegment
MemorySegment
is a preview API of the Java platform. There are two kinds of memory segments:
ofArray(int[])
factory methods. These methods return a memory segment backed by the on-heap region that holds the specified Java array. Native segments can be obtained by calling one of the Arena.allocate(long, long)
PREVIEW factory methods, which return a memory segment backed by a newly allocated off-heap region with the given size and aligned to the given alignment constraint. Alternatively, native segments can be obtained by mapping
PREVIEW a file into a new off-heap region (in some systems, this operation is sometimes referred to as mmap
). Segments obtained in this way are called mapped segments, and their contents can be persisted and loaded to and from the underlying memory-mapped file.
Both kinds of segments are read and written using the same methods, known as access operations. An access operation on a memory segment always and only provides access to the region for which the segment was obtained.
long
value. The nature of a segment's address depends on the kind of the segment: MemorySegment
API who see a stable virtualized address for a heap segment backed by the region. A heap segment obtained from one of the ofArray(int[])
factory methods has an address of zero. Every memory segment has a size. The size of a heap segment is derived from the Java array from which it is obtained. This size is predictable across Java runtimes. The size of a native segment is either passed explicitly (as in Arena.allocate(long, long)
PREVIEW) or derived from a MemoryLayout
PREVIEW (as in SegmentAllocator.allocate(MemoryLayout)
PREVIEW). The size of a memory segment is typically a positive number but may be zero, but never negative.
The address and size of a memory segment jointly ensure that access operations on the segment cannot fall outside the boundaries of the region of memory which backs the segment. That is, a memory segment has spatial bounds.
Every memory segment is associated with a scopePREVIEW. This ensures that access operations on a memory segment cannot occur when the region of memory which backs the memory segment is no longer available (e.g., after the scope associated with the accessed memory segment is no longer alivePREVIEW). That is, a memory segment has temporal bounds.
Finally, access operations on a memory segment can be subject to additional thread-confinement checks. Heap segments can be accessed from any thread. Conversely, native segments can only be accessed compatibly with the confinement characteristics of the arena used to obtain them.
get(ValueLayout.OfInt, long)
). Each access operation takes a value layoutPREVIEW, which specifies the size and shape of the value, and an offset, expressed in bytes. For instance, to read an int from a segment, using default endianness, the following code can be used: MemorySegment segment = ...
int value = segment.get(ValueLayout.JAVA_INT, 0);
MemorySegment segment = ...
int value = segment.get(ValueLayout.JAVA_INT.withOrder(BIG_ENDIAN), 0);
long
offset. More complex var handles can be obtained by adapting a segment var handle view using the var handle combinator functions defined in the MethodHandles
class: MemorySegment segment = ...
VarHandle intHandle = MethodHandles.memorySegmentViewVarHandle(ValueLayout.JAVA_INT);
MethodHandle multiplyExact = MethodHandles.lookup()
.findStatic(Math.class, "multiplyExact",
MethodType.methodType(long.class, long.class, long.class));
intHandle = MethodHandles.filterCoordinates(intHandle, 1,
MethodHandles.insertArguments(multiplyExact, 0, ValueLayout.JAVA_INT.byteSize()));
int value = (int) intHandle.get(segment, 3L); // get int element at offset 3 * 4 = 12
MemorySegment segment = ...
VarHandle intHandle = ValueLayout.JAVA_INT.arrayElementVarHandle();
int value = (int) intHandle.get(segment, 3L); // get int element at offset 3 * 4 = 12
Arena arena = ...
MemorySegment segment = arena.allocate(100);
MemorySegment slice = segment.asSlice(50, 10);
slice.get(ValueLayout.JAVA_INT, 20); // Out of bounds!
arena.close();
slice.get(ValueLayout.JAVA_INT, 0); // Already closed!
segment
, and is 10 bytes long. That is, the address of the slice
is segment.address() + 50
, and its size is 10. As a result, attempting to read an int value at offset 20 of the slice
segment will result in an exception. The temporal boundsPREVIEW of the original segment is inherited by its slices; that is, when the scope associated with segment
is no longer alivePREVIEW, slice
will also be become inaccessible. A client might obtain a Stream
from a segment, which can then be used to slice the segment (according to a given element layout) and even allow multiple threads to work in parallel on disjoint segment slices (to do this, the segment has to be accessible from multiple threads). The following code can be used to sum all int values in a memory segment in parallel:
try (Arena arena = Arena.ofShared()) {
SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.sequenceLayout(1024, ValueLayout.JAVA_INT);
MemorySegment segment = arena.allocate(SEQUENCE_LAYOUT);
int sum = segment.elements(ValueLayout.JAVA_INT).parallel()
.mapToInt(s -> s.get(ValueLayout.JAVA_INT, 0))
.sum();
}
VarHandle
are only permitted at aligned addresses. In addition, alignment applies to an access operation whether the segment being accessed is a native segment or a heap segment. If the segment being accessed is a native segment, then its address in physical memory can be combined with the offset to obtain the target address in physical memory. The pseudo-function below demonstrates this:
boolean isAligned(MemorySegment segment, long offset, MemoryLayout layout) {
return ((segment.address() + offset) % layout.byteAlignment()) == 0;
}
The alignment constraint used to access a segment is typically dictated by the shape of the data structure stored in the segment. For example, if the programmer wishes to store a sequence of 8-byte values in a native segment, then the segment should be allocated by specifying a 8-byte alignment constraint, either via Arena.allocate(long, long)
PREVIEW or SegmentAllocator.allocate(MemoryLayout)
PREVIEW. These factories ensure that the off-heap region of memory backing the returned segment has a starting address that is 8-byte aligned. Subsequently, the programmer can access the segment at the offsets of interest -- 0, 8, 16, 24, etc -- in the knowledge that every such access is aligned.
If the segment being accessed is a heap segment, then determining whether access is aligned is more complex. The address of the segment in physical memory is not known, and is not even fixed (it may change when the segment is relocated during garbage collection). This means that the address cannot be combined with the specified offset to determine a target address in physical memory. Since the alignment constraint always refers to alignment of addresses in physical memory, it is not possible in principle to determine if any offset in a heap segment is aligned. For example, suppose the programmer chooses a 8-byte alignment constraint and tries to access offset 16 in a heap segment. If the heap segment's address 0 corresponds to physical address 1000, then the target address (1016) would be aligned, but if address 0 corresponds to physical address 1004, then the target address (1020) would not be aligned. It is undesirable to allow access to target addresses that are aligned according to the programmer's chosen alignment constraint, but might not be predictably aligned in physical memory (e.g. because of platform considerations and/or garbage collection behavior).
In practice, the Java runtime lays out arrays in memory so that each n-byte element occurs at an n-byte aligned physical address (except for long[]
and double[]
, where alignment is platform-dependent, as explained below). The runtime preserves this invariant even if the array is relocated during garbage collection. Access operations rely on this invariant to determine if the specified offset in a heap segment refers to an aligned address in physical memory. For example:
short[]
array will be 2-byte aligned (e.g. 1006) so that successive short elements occur at 2-byte aligned addresses (e.g. 1006, 1008, 1010, 1012, etc). A heap segment backed by a short[]
array can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint. The segment cannot be accessed at any offset under a 4-byte alignment constraint, because there is no guarantee that the target address would be 4-byte aligned, e.g., offset 0 would correspond to physical address 1006 while offset 1 would correspond to physical address 1007. Similarly, the segment cannot be accessed at any offset under an 8-byte alignment constraint, because because there is no guarantee that the target address would be 8-byte aligned, e.g., offset 2 would correspond to physical address 1008 but offset 4 would correspond to physical address 1010.long[]
array will be 8-byte aligned (e.g. 1000) on 64-bit platforms, so that successive long elements occur at 8-byte aligned addresses (e.g., 1000, 1008, 1016, 1024, etc.) On 64-bit platforms, a heap segment backed by a long[]
array can be accessed at offsets 0, 8, 16, 24, etc under an 8-byte alignment constraint. In addition, the segment can be accessed at offsets 0, 4, 8, 12, etc under a 4-byte alignment constraint, because the target addresses (1000, 1004, 1008, 1012) are 4-byte aligned. And, the segment can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint, because the target addresses (e.g. 1000, 1002, 1004, 1006) are 2-byte aligned.long[]
array will be 4-byte aligned (e.g. 1004) on 32-bit platforms, so that successive long elements occur at 4-byte aligned addresses (e.g., 1004, 1008, 1012, 1016, etc.) On 32-bit platforms, a heap segment backed by a long[]
array can be accessed at offsets 0, 4, 8, 12, etc under a 4-byte alignment constraint, because the target addresses (1004, 1008, 1012, 1016) are 4-byte aligned. And, the segment can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint, because the target addresses (e.g. 1000, 1002, 1004, 1006) are 2-byte aligned.In other words, heap segments feature a (platform-dependent) maximum alignment which is derived from the size of the elements of the Java array backing the segment, as shown in the following table:
Heap segments can only be accessed using a layout whose alignment is smaller or equal to the maximum alignment associated with the heap segment. Attempting to access a heap segment using a layout whose alignment is greater than the maximum alignment associated with the heap segment will fail, as demonstrated in the following example:
Array type (of backing region) Maximum supported alignment (in bytes) boolean[]
ValueLayout.JAVA_BOOLEAN.byteAlignment()
byte[]
ValueLayout.JAVA_BYTE.byteAlignment()
char[]
ValueLayout.JAVA_CHAR.byteAlignment()
short[]
ValueLayout.JAVA_SHORT.byteAlignment()
int[]
ValueLayout.JAVA_INT.byteAlignment()
float[]
ValueLayout.JAVA_FLOAT.byteAlignment()
long[]
ValueLayout.JAVA_LONG.byteAlignment()
double[]
ValueLayout.JAVA_DOUBLE.byteAlignment()
MemorySegment byteSegment = MemorySegment.ofArray(new byte[10]);
byteSegment.get(ValueLayout.JAVA_INT, 0); // fails: ValueLayout.JAVA_INT.byteAlignment() > ValueLayout.JAVA_BYTE.byteAlignment()
long[]
), capable of supporting greater maximum alignment. More specifically, the maximum alignment associated with long[]
is set to ValueLayout.JAVA_LONG.byteAlignment()
which is a platform-dependent value (set to ValueLayout.ADDRESS.byteSize()
). That is, long[]
) is guaranteed to provide at least 8-byte alignment in 64-bit platforms, but only 4-byte alignment in 32-bit platforms: MemorySegment longSegment = MemorySegment.ofArray(new long[10]);
longSegment.get(ValueLayout.JAVA_INT, 0); // ok: ValueLayout.JAVA_INT.byteAlignment() <= ValueLayout.JAVA_LONG.byteAlignment()
ValueLayout.JAVA_INT_UNALIGNED
PREVIEW) have their alignment constraint set to 1: MemorySegment byteSegment = MemorySegment.ofArray(new byte[10]);
byteSegment.get(ValueLayout.JAVA_INT_UNALIGNED, 0); // ok: ValueLayout.JAVA_INT_UNALIGNED.byteAlignment() == ValueLayout.JAVA_BYTE.byteAlignment()
char*
might return a pointer to a region containing a single char
value, or to a region containing an array of char
values, where the size of the array might be provided in a separate parameter. The size of the array is not readily apparent to the code calling the foreign function and hoping to use its result. In addition to having no insight into the size of the region of memory backing a pointer returned from a foreign function, it also has no insight into the lifetime intended for said region of memory by the foreign function that allocated it. The MemorySegment
API uses zero-length memory segments to represent:
IndexOutOfBoundsException
. This is a crucial safety feature: as these segments are associated with a region of memory whose size is not known, any access operations involving these segments cannot be validated. In effect, a zero-length memory segment wraps an address, and it cannot be used without explicit intent (see below); To demonstrate how clients can work with zero-length memory segments, consider the case of a client that wants to read a pointer from some memory segment. This can be done via the get(AddressLayout, long) access method. This method accepts an address layoutPREVIEW (e.g. ValueLayout.ADDRESS
PREVIEW), the layout of the pointer to be read. For instance on a 64-bit platform, the size of an address layout is 8 bytes. The access operation also accepts an offset, expressed in bytes, which indicates the position (relative to the start of the memory segment) at which the pointer is stored. The access operation returns a zero-length native memory segment, backed by a region of memory whose starting address is the 64-bit value read at the specified offset.
The returned zero-length memory segment cannot be accessed directly by the client: since the size of the segment is zero, any access operation would result in out-of-bounds access. Instead, the client must, unsafely, assign new spatial bounds to the zero-length memory segment. This can be done via the reinterpret(long)
method, as follows:
MemorySegment z = segment.get(ValueLayout.ADDRESS, ...); // size = 0
MemorySegment ptr = z.reinterpret(16); // size = 16
int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3); // ok
In some cases, the client might additionally want to assign new temporal bounds to a zero-length memory segment. This can be done via the reinterpret(long, Arena, Consumer)
method, which returns a new native segment with the desired size and the same temporal bounds as those of the provided arena:
MemorySegment ptr = null;
try (Arena arena = Arena.ofConfined()) {
MemorySegment z = segment.get(ValueLayout.ADDRESS, ...); // size = 0, scope = always alive
ptr = z.reinterpret(16, arena, null); // size = 4, scope = arena.scope()
int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3); // ok
}
int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3); // throws IllegalStateException
AddressLayout intArrPtrLayout = ValueLayout.ADDRESS.withTargetLayout(
MemoryLayout.sequenceLayout(4, ValueLayout.JAVA_INT)); // layout for int (*ptr)[4]
MemorySegment ptr = segment.get(intArrPtrLayout, ...); // size = 16
int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3); // ok
All the methods which can be used to manipulate zero-length memory segments (reinterpret(long)
, reinterpret(Arena, Consumer)
, reinterpret(long, Arena, Consumer)
and AddressLayout.withTargetLayout(MemoryLayout)
PREVIEW) are restricted methods, and should be used with caution: assigning a segment incorrect spatial and/or temporal bounds could result in a VM crash when attempting to access the memory segment.
Modifier and Type | Interface | Description |
---|---|---|
static interface |
MemorySegment.ScopePREVIEW |
Preview. A scope models the lifetime of all the memory segments associated with it. |
Modifier and Type | Field | Description |
---|---|---|
static final MemorySegmentPREVIEW |
NULL |
A zero-length native segment modelling the NULL address. |
Modifier and Type | Method | Description |
---|---|---|
long |
address() |
Returns the address of this memory segment. |
ByteBuffer |
asByteBuffer() |
Wraps this segment in a ByteBuffer . |
Optional |
asOverlappingSlice |
Returns a slice of this segment that is the overlap between this and the provided segment. |
MemorySegmentPREVIEW |
asReadOnly() |
Returns a read-only view of this segment. |
MemorySegmentPREVIEW |
asSlice |
Returns a slice of this memory segment, at the given offset. |
MemorySegmentPREVIEW |
asSlice |
Returns a slice of this memory segment, at the given offset. |
MemorySegmentPREVIEW |
asSlice |
Returns a slice of this memory segment, at the given offset, with the provided alignment constraint. |
default MemorySegmentPREVIEW |
asSlice |
Returns a slice of this memory segment with the given layout, at the given offset. |
long |
byteSize() |
Returns the size (in bytes) of this memory segment. |
static void |
copy |
Performs a bulk copy from source segment to destination segment. |
static void |
copy |
Performs a bulk copy from source segment to destination segment. |
static void |
copy |
Copies a number of elements from a source memory segment to a destination array. |
static void |
copy |
Copies a number of elements from a source array to a destination memory segment. |
default MemorySegmentPREVIEW |
copyFrom |
Performs a bulk copy from given source segment to this segment. |
Stream |
elements |
Returns a sequential Stream over disjoint slices (whose size matches that of the specified layout) in this segment. |
boolean |
equals |
Compares the specified object with this memory segment for equality. |
MemorySegmentPREVIEW |
fill |
Fills the contents of this memory segment with the given value. |
void |
force() |
Forces any changes made to the contents of this mapped segment to be written to the storage device described by the mapped segment's file descriptor. |
default MemorySegmentPREVIEW |
get |
Reads an address from this segment at the given offset, with the given layout. |
default boolean |
get |
Reads a boolean from this segment at the given offset, with the given layout. |
default byte |
get |
Reads a byte from this segment at the given offset, with the given layout. |
default char |
get |
Reads a char from this segment at the given offset, with the given layout. |
default double |
get |
Reads a double from this segment at the given offset, with the given layout. |
default float |
get |
Reads a float from this segment at the given offset, with the given layout. |
default int |
get |
Reads an int from this segment at the given offset, with the given layout. |
default long |
get |
Reads a long from this segment at the given offset, with the given layout. |
default short |
get |
Reads a short from this segment at the given offset, with the given layout. |
default MemorySegmentPREVIEW |
getAtIndex |
Reads an address from this segment at the given at the given index, scaled by the given layout size. |
default boolean |
getAtIndex |
Reads a boolean from this segment at the given index, scaled by the given layout size. |
default byte |
getAtIndex |
Reads a byte from this segment at the given index, scaled by the given layout size. |
default char |
getAtIndex |
Reads a char from this segment at the given index, scaled by the given layout size. |
default double |
getAtIndex |
Reads a double from this segment at the given index, scaled by the given layout size. |
default float |
getAtIndex |
Reads a float from this segment at the given index, scaled by the given layout size. |
default int |
getAtIndex |
Reads an int from this segment at the given index, scaled by the given layout size. |
default long |
getAtIndex |
Reads a long from this segment at the given index, scaled by the given layout size. |
default short |
getAtIndex |
Reads a short from this segment at the given index, scaled by the given layout size. |
default String |
getUtf8String |
Reads a UTF-8 encoded, null-terminated string from this segment at the given offset. |
int |
hashCode() |
Returns the hash code value for this memory segment. |
Optional |
heapBase() |
Returns the Java object stored in the on-heap region of memory backing this memory segment, if any. |
boolean |
isAccessibleBy |
Returns true if this segment can be accessed from the provided thread. |
boolean |
isLoaded() |
Determines whether the contents of this mapped segment is resident in physical memory. |
boolean |
isMapped() |
Returns true if this segment is a mapped segment. |
boolean |
isNative() |
Returns true if this segment is a native segment. |
boolean |
isReadOnly() |
Returns true , if this segment is read-only. |
void |
load() |
Loads the contents of this mapped segment into physical memory. |
default long |
mismatch |
Finds and returns the offset, in bytes, of the first mismatch between this segment and the given other segment. |
static long |
mismatch |
Finds and returns the relative offset, in bytes, of the first mismatch between the source and the destination segments. |
static MemorySegmentPREVIEW |
ofAddress |
Creates a zero-length native segment from the given address value. |
static MemorySegmentPREVIEW |
ofArray |
Creates a heap segment backed by the on-heap region of memory that holds the given byte array. |
static MemorySegmentPREVIEW |
ofArray |
Creates a heap segment backed by the on-heap region of memory that holds the given char array. |
static MemorySegmentPREVIEW |
ofArray |
Creates a heap segment backed by the on-heap region of memory that holds the given double array. |
static MemorySegmentPREVIEW |
ofArray |
Creates a heap segment backed by the on-heap region of memory that holds the given float array. |
static MemorySegmentPREVIEW |
ofArray |
Creates a heap segment backed by the on-heap region of memory that holds the given int array. |
static MemorySegmentPREVIEW |
ofArray |
Creates a heap segment backed by the on-heap region of memory that holds the given long array. |
static MemorySegmentPREVIEW |
ofArray |
Creates a heap segment backed by the on-heap region of memory that holds the given short array. |
static MemorySegmentPREVIEW |
ofBuffer |
Creates a memory segment that is backed by the same region of memory that backs the given Buffer instance. |
MemorySegmentPREVIEW |
reinterpret |
Returns a new memory segment that has the same address and scope as this segment, but with the provided size. |
MemorySegmentPREVIEW |
reinterpret |
Returns a new segment with the same address as this segment, but with the provided size and scope. |
MemorySegmentPREVIEW |
reinterpret |
Returns a new memory segment with the same address and size as this segment, but with the provided scope. |
MemorySegment.ScopePREVIEW |
scope() |
Returns the scope associated with this memory segment. |
long |
segmentOffset |
Returns the offset, in bytes, of the provided segment, relative to this segment. |
default void |
set |
Writes an address into this segment at the given offset, with the given layout. |
default void |
set |
Writes a boolean into this segment at the given offset, with the given layout. |
default void |
set |
Writes a byte into this segment at the given offset, with the given layout. |
default void |
set |
Writes a char into this segment at the given offset, with the given layout. |
default void |
set |
Writes a double into this segment at the given offset, with the given layout. |
default void |
set |
Writes a float into this segment at the given offset, with the given layout. |
default void |
set |
Writes an int into this segment at the given offset, with the given layout. |
default void |
set |
Writes a long into this segment at the given offset, with the given layout. |
default void |
set |
Writes a short into this segment at the given offset, with the given layout. |
default void |
setAtIndex |
Writes an address into this segment at the given index, scaled by the given layout size. |
default void |
setAtIndex |
Writes a boolean into this segment at the given index, scaled by the given layout size. |
default void |
setAtIndex |
Writes a byte into this segment at the given index, scaled by the given layout size. |
default void |
setAtIndex |
Writes a char into this segment at the given index, scaled by the given layout size. |
default void |
setAtIndex |
Writes a double into this segment at the given index, scaled by the given layout size. |
default void |
setAtIndex |
Writes a float into this segment at the given index, scaled by the given layout size. |
default void |
setAtIndex |
Writes an int into this segment at the given index, scaled by the given layout size. |
default void |
setAtIndex |
Writes a long into this segment at the given index, scaled by the given layout size. |
default void |
setAtIndex |
Writes a short into this segment at the given index, scaled by the given layout size. |
default void |
setUtf8String |
Writes the given string into this segment at the given offset, converting it to a null-terminated byte sequence using UTF-8 encoding. |
Spliterator |
spliterator |
Returns a spliterator for this memory segment. |
byte[] |
toArray |
Copy the contents of this memory segment into a new byte array. |
char[] |
toArray |
Copy the contents of this memory segment into a new char array. |
double[] |
toArray |
Copy the contents of this memory segment into a new double array. |
float[] |
toArray |
Copy the contents of this memory segment into a new float array. |
int[] |
toArray |
Copy the contents of this memory segment into a new int array. |
long[] |
toArray |
Copy the contents of this memory segment into a new long array. |
short[] |
toArray |
Copy the contents of this memory segment into a new short array. |
void |
unload() |
Unloads the contents of this mapped segment from physical memory. |
static final MemorySegmentPREVIEW NULL
NULL
address.long address()
Optional<Object> heapBase()
ofArray(byte[])
factory method, this method will return the byte[]
object which was used to obtain the segment. This method returns an empty Optional
value if either this segment is a native segment, or if this segment is read-only.Spliterator<MemorySegmentPREVIEW> spliterator(MemoryLayoutPREVIEW elementLayout)
Spliterator.SIZED
, Spliterator.SUBSIZED
, Spliterator.IMMUTABLE
, Spliterator.NONNULL
and Spliterator.ORDERED
characteristics. The returned spliterator splits this segment according to the specified element layout; that is, if the supplied layout has size N, then calling Spliterator.trySplit()
will result in a spliterator serving approximately S/N
elements (depending on whether N is even or not), where S
is the size of this segment. As such, splitting is possible as long as S/N >= 2
. The spliterator returns segments that have the same lifetime as that of this segment.
The returned spliterator effectively allows to slice this segment into disjoint slices, which can then be processed in parallel by multiple threads.
elementLayout
- the layout to be used for splitting.IllegalArgumentException
- if elementLayout.byteSize() == 0
.IllegalArgumentException
- if byteSize() % elementLayout.byteSize() != 0
.IllegalArgumentException
- if elementLayout.byteSize() % elementLayout.byteAlignment() != 0
.IllegalArgumentException
- if this segment is incompatible with the alignment constraint in the provided layout.Stream<MemorySegmentPREVIEW> elements(MemoryLayoutPREVIEW elementLayout)
Stream
over disjoint slices (whose size matches that of the specified layout) in this segment. Calling this method is equivalent to the following code: StreamSupport.stream(segment.spliterator(elementLayout), false);
elementLayout
- the layout to be used for splitting.Stream
over disjoint slices in this segment.IllegalArgumentException
- if elementLayout.byteSize() == 0
.IllegalArgumentException
- if byteSize() % elementLayout.byteSize() != 0
.IllegalArgumentException
- if elementLayout.byteSize() % elementLayout.byteAlignment() != 0
.IllegalArgumentException
- if this segment is incompatible with the alignment constraint in the provided layout.MemorySegment.ScopePREVIEW scope()
boolean isAccessibleBy(Thread thread)
true
if this segment can be accessed from the provided thread.thread
- the thread to be tested.true
if this segment can be accessed from the provided threadlong byteSize()
MemorySegmentPREVIEW asSlice(long offset, long newSize)
Equivalent to the following code:
asSlice(offset, newSize, 1);
offset
- The new segment base offset (relative to the address of this segment), specified in bytes.newSize
- The new segment size, specified in bytes.IndexOutOfBoundsException
- if offset < 0
, offset > byteSize()
, newSize < 0
, or newSize > byteSize() - offset
MemorySegmentPREVIEW asSlice(long offset, long newSize, long byteAlignment)
offset
- The new segment base offset (relative to the address of this segment), specified in bytes.newSize
- The new segment size, specified in bytes.byteAlignment
- The alignment constraint (in bytes) of the returned slice.IndexOutOfBoundsException
- if offset < 0
, offset > byteSize()
, newSize < 0
, or newSize > byteSize() - offset
IllegalArgumentException
- if this segment cannot be accessed at offset
under the provided alignment constraint.IllegalArgumentException
- if byteAlignment <= 0
, or if byteAlignment
is not a power of 2.default MemorySegmentPREVIEW asSlice(long offset, MemoryLayoutPREVIEW layout)
Equivalent to the following code:
asSlice(offset, layout.byteSize(), layout.byteAlignment());
offset
- The new segment base offset (relative to the address of this segment), specified in bytes.layout
- The layout of the segment slice.IndexOutOfBoundsException
- if offset < 0
, offset > byteSize()
, or layout.byteSize() > byteSize() - offset
IllegalArgumentException
- if this segment cannot be accessed at offset
under the alignment constraint specified by layout
.MemorySegmentPREVIEW asSlice(long offset)
Equivalent to the following code:
asSlice(offset, byteSize() - offset);
offset
- The new segment base offset (relative to the address of this segment), specified in bytes.IndexOutOfBoundsException
- if offset < 0
, or offset > byteSize()
.MemorySegmentPREVIEW reinterpret(long newSize)
This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.
newSize
- the size of the returned segment.IllegalArgumentException
- if newSize < 0
.UnsupportedOperationException
- if this segment is not a native segment.IllegalCallerException
- If the caller is in a module that does not have native access enabled.MemorySegmentPREVIEW reinterpret(ArenaPREVIEW arena, Consumer<MemorySegmentPREVIEW> cleanup)
Clients can specify an optional cleanup action that should be executed when the provided scope becomes invalid. This cleanup action receives a fresh memory segment that is obtained from this segment as follows:
MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
.reinterpret(byteSize());
byteSize()
. This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.
arena
- the arena to be associated with the returned segment.cleanup
- the cleanup action that should be executed when the provided arena is closed (can be null
).IllegalStateException
- if arena.scope().isAlive() == false
.UnsupportedOperationException
- if this segment is not a native segment.IllegalCallerException
- If the caller is in a module that does not have native access enabled.MemorySegmentPREVIEW reinterpret(long newSize, ArenaPREVIEW arena, Consumer<MemorySegmentPREVIEW> cleanup)
Clients can specify an optional cleanup action that should be executed when the provided scope becomes invalid. This cleanup action receives a fresh memory segment that is obtained from this segment as follows:
MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
.reinterpret(newSize);
newSize
. This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.
newSize
- the size of the returned segment.arena
- the arena to be associated with the returned segment.cleanup
- the cleanup action that should be executed when the provided arena is closed (can be null
).UnsupportedOperationException
- if this segment is not a native segment.IllegalArgumentException
- if newSize < 0
.IllegalStateException
- if arena.scope().isAlive() == false
.IllegalCallerException
- If the caller is in a module that does not have native access enabled.boolean isReadOnly()
true
, if this segment is read-only.true
, if this segment is read-onlyMemorySegmentPREVIEW asReadOnly()
boolean isNative()
true
if this segment is a native segment. A native segment is created e.g. using the Arena.allocate(long, long)
PREVIEW (and related) factory, or by wrapping a direct buffer.true
if this segment is native segment.boolean isMapped()
true
if this segment is a mapped segment. A mapped memory segment is created e.g. using the FileChannel.map(FileChannel.MapMode, long, long, Arena)
PREVIEW factory, or by wrapping a mapped byte buffer.true
if this segment is a mapped segment.Optional<MemorySegmentPREVIEW> asOverlappingSlice(MemorySegmentPREVIEW other)
Two segments S1
and S2
are said to overlap if it is possible to find at least two slices L1
(from S1
) and L2
(from S2
) that are backed by the same region of memory. As such, it is not possible for a native segment to overlap with a heap segment; in this case, or when no overlap occurs, an empty Optional
is returned.
other
- the segment to test for an overlap with this segment.long segmentOffset(MemorySegmentPREVIEW other)
The offset is relative to the address of this segment and can be a negative or positive value. For instance, if both segments are native segments, or heap segments backed by the same array, the resulting offset can be computed as follows:
other.address() - address()
0
is returned. If other
is a slice of this segment, the offset is always 0 <= x < this.byteSize()
.other
- the segment to retrieve an offset to.UnsupportedOperationException
- if the two segments cannot be compared, e.g. because they are of different kinds, or because they are backed by different Java arrays.MemorySegmentPREVIEW fill(byte value)
More specifically, the given value is written into each address of this segment. Equivalent to (but likely more efficient than) the following code:
for (long offset = 0; offset < segment.byteSize(); offset++) {
byteHandle.set(ValueLayout.JAVA_BYTE, offset, value);
}
This method can be useful to initialize or reset the contents of a memory segment.
value
- the value to write into this segment.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.UnsupportedOperationException
- if this segment is read-only.default MemorySegmentPREVIEW copyFrom(MemorySegmentPREVIEW src)
0
through src.byteSize() - 1
in the source segment are copied into this segment at offset 0
through src.byteSize() - 1
. Calling this method is equivalent to the following code:
MemorySegment.copy(src, 0, this, 0, src.byteSize());
src
- the source segment.IndexOutOfBoundsException
- if src.byteSize() > this.byteSize()
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalStateException
- if the scope associated with src
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that src.isAccessibleBy(T) == false
.UnsupportedOperationException
- if this segment is read-only.default long mismatch(MemorySegmentPREVIEW other)
If the two segments share a common prefix then the returned offset is the length of the common prefix, and it follows that there is a mismatch between the two segments at that offset within the respective segments. If one segment is a proper prefix of the other, then the returned offset is the smallest of the segment sizes, and it follows that the offset is only valid for the larger segment. Otherwise, there is no mismatch and
-1
is returned.
other
- the segment to be tested for a mismatch with this segment.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalStateException
- if the scope associated with other
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that other.isAccessibleBy(T) == false
.boolean isLoaded()
A return value of true
implies that it is highly likely that all the data in this segment is resident in physical memory and may therefore be accessed without incurring any virtual-memory page faults or I/O operations. A return value of false
does not necessarily imply that this segment's content is not resident in physical memory.
The returned value is a hint, rather than a guarantee, because the underlying operating system may have paged out some of this segment's data by the time that an invocation of this method returns.
true
if it is likely that the contents of this segment is resident in physical memoryIllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.UnsupportedOperationException
- if this segment is not a mapped memory segment, e.g. if isMapped() == false
.void load()
This method makes a best effort to ensure that, when it returns, this contents of this segment is resident in physical memory. Invoking this method may cause some number of page faults and I/O operations to occur.
IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.UnsupportedOperationException
- if this segment is not a mapped memory segment, e.g. if isMapped() == false
.void unload()
This method makes a best effort to ensure that the contents of this segment are are no longer resident in physical memory. Accessing this segment's contents after invoking this method may cause some number of page faults and I/O operations to occur (as this segment's contents might need to be paged back in).
IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.UnsupportedOperationException
- if this segment is not a mapped memory segment, e.g. if isMapped() == false
.void force()
If the file descriptor associated with this mapped segment resides on a local storage device then when this method returns it is guaranteed that all changes made to this segment since it was created, or since this method was last invoked, will have been written to that device.
If the file descriptor associated with this mapped segment does not reside on a local device then no such guarantee is made.
If this segment was not mapped in read/write mode (FileChannel.MapMode.READ_WRITE
) then invoking this method may have no effect. In particular, the method has no effect for segments mapped in read-only or private mapping modes. This method may or may not have an effect for implementation-specific mapping modes.
IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.UnsupportedOperationException
- if this segment is not a mapped memory segment, e.g. if isMapped() == false
.UncheckedIOException
- if there is an I/O error writing the contents of this segment to the associated storage deviceByteBuffer asByteBuffer()
ByteBuffer
. Some properties of the returned buffer are linked to the properties of this segment. More specifically, the resulting buffer has the following characteristics: Integer.MAX_VALUE
; The life-cycle of the returned buffer is tied to that of this segment. That is, accessing the returned buffer after the scope associated with this segment is no longer alivePREVIEW, will throw an IllegalStateException
. Similarly, accessing the returned buffer from a thread T
such that isAccessible(T) == false
will throw a WrongThreadException
.
If this segment is accessible from a single thread, calling read/write I/O operations on the resulting buffer might result in unspecified exceptions being thrown. Examples of such problematic operations are AsynchronousSocketChannel.read(ByteBuffer)
and AsynchronousSocketChannel.write(ByteBuffer)
.
Finally, the resulting buffer's byte order is ByteOrder.BIG_ENDIAN
; this can be changed using ByteBuffer.order(java.nio.ByteOrder)
.
ByteBuffer
view of this memory segment.UnsupportedOperationException
- if this segment cannot be mapped onto a ByteBuffer
instance, e.g. if it is a heap segment backed by an array other than byte[]
), or if its size is greater than Integer.MAX_VALUE
.byte[] toArray(ValueLayout.OfBytePREVIEW elementLayout)
elementLayout
- the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalStateException
- if this segment's contents cannot be copied into a byte[]
instance, e.g. its size is greater than Integer.MAX_VALUE
.short[] toArray(ValueLayout.OfShortPREVIEW elementLayout)
elementLayout
- the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalStateException
- if this segment's contents cannot be copied into a short[]
instance, e.g. because byteSize() % 2 != 0
, or byteSize() / 2 > Integer.MAX_VALUE
char[] toArray(ValueLayout.OfCharPREVIEW elementLayout)
elementLayout
- the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalStateException
- if this segment's contents cannot be copied into a char[]
instance, e.g. because byteSize() % 2 != 0
, or byteSize() / 2 > Integer.MAX_VALUE
.int[] toArray(ValueLayout.OfIntPREVIEW elementLayout)
elementLayout
- the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalStateException
- if this segment's contents cannot be copied into a int[]
instance, e.g. because byteSize() % 4 != 0
, or byteSize() / 4 > Integer.MAX_VALUE
.float[] toArray(ValueLayout.OfFloatPREVIEW elementLayout)
elementLayout
- the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalStateException
- if this segment's contents cannot be copied into a float[]
instance, e.g. because byteSize() % 4 != 0
, or byteSize() / 4 > Integer.MAX_VALUE
.long[] toArray(ValueLayout.OfLongPREVIEW elementLayout)
elementLayout
- the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalStateException
- if this segment's contents cannot be copied into a long[]
instance, e.g. because byteSize() % 8 != 0
, or byteSize() / 8 > Integer.MAX_VALUE
.double[] toArray(ValueLayout.OfDoublePREVIEW elementLayout)
elementLayout
- the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalStateException
- if this segment's contents cannot be copied into a double[]
instance, e.g. because byteSize() % 8 != 0
, or byteSize() / 8 > Integer.MAX_VALUE
.default String getUtf8String(long offset)
This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement string. The CharsetDecoder
class should be used when more control over the decoding process is required.
offset
- offset in bytes (relative to this segment address) at which this access operation will occur.'\0'
terminator character (assuming one is found).IllegalArgumentException
- if the size of the UTF-8 string is greater than the largest string supported by the platform.IndexOutOfBoundsException
- if offset < 0
or offset > byteSize() - S
, where S
is the size of the UTF-8 string (including the terminator character).IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.default void setUtf8String(long offset, String str)
This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement string. The CharsetDecoder
class should be used when more control over the decoding process is required.
If the given string contains any '\0'
characters, they will be copied as well. This means that, depending on the method used to read the string, such as getUtf8String(long)
, the string will appear truncated when read again.
offset
- offset in bytes (relative to this segment address) at which this access operation will occur. the final address of this write operation can be expressed as address() + offset
.str
- the Java string to be written into this segment.IndexOutOfBoundsException
- if offset < 0
or offset > byteSize() - str.getBytes().length() + 1
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.static MemorySegmentPREVIEW ofBuffer(Buffer buffer)
Buffer
instance. The segment starts relative to the buffer's position (inclusive) and ends relative to the buffer's limit (exclusive). If the buffer is read-only, the resulting segment is also read-only. Moreover, if the buffer is a direct buffer, the returned segment is a native segment; otherwise the returned memory segment is a heap segment.
If the provided buffer has been obtained by calling asByteBuffer()
on a memory segment whose scopePREVIEW is S
, the returned segment will be associated with the same scope S
. Otherwise, the scope of the returned segment is a fresh scope that is always alive.
The scope associated with the returned segment keeps the provided buffer reachable. As such, if the provided buffer is a direct buffer, its backing memory region will not be deallocated as long as the returned segment (or any of its slices) are kept reachable.
buffer
- the buffer instance to be turned into a new memory segment.IllegalArgumentException
- if the provided buffer
is a heap buffer but is not backed by an array. For example, buffers directly or indirectly obtained via (CharBuffer.wrap(CharSequence)
or CharBuffer.wrap(char[], int, int)
are not backed by an array.static MemorySegmentPREVIEW ofArray(byte[] byteArray)
address()
is set to zero.byteArray
- the primitive array backing the heap memory segment.static MemorySegmentPREVIEW ofArray(char[] charArray)
address()
is set to zero.charArray
- the primitive array backing the heap segment.static MemorySegmentPREVIEW ofArray(short[] shortArray)
address()
is set to zero.shortArray
- the primitive array backing the heap segment.static MemorySegmentPREVIEW ofArray(int[] intArray)
address()
is set to zero.intArray
- the primitive array backing the heap segment.static MemorySegmentPREVIEW ofArray(float[] floatArray)
address()
is set to zero.floatArray
- the primitive array backing the heap segment.static MemorySegmentPREVIEW ofArray(long[] longArray)
address()
is set to zero.longArray
- the primitive array backing the heap segment.static MemorySegmentPREVIEW ofArray(double[] doubleArray)
address()
is set to zero.doubleArray
- the primitive array backing the heap segment.static MemorySegmentPREVIEW ofAddress(long address)
On 32-bit platforms, the given address value will be normalized such that the highest-order ("leftmost") 32 bits of the address
of the returned memory segment are set to zero.
address
- the address of the returned native segment.static void copy(MemorySegmentPREVIEW srcSegment, long srcOffset, MemorySegmentPREVIEW dstSegment, long dstOffset, long bytes)
srcOffset
through srcOffset + bytes - 1
in the source segment are copied into the destination segment at offset dstOffset
through dstOffset + bytes - 1
. If the source segment overlaps with the destination segment, then the copying is performed as if the bytes at offset srcOffset
through srcOffset + bytes - 1
in the source segment were first copied into a temporary segment with size bytes
, and then the contents of the temporary segment were copied into the destination segment at offset dstOffset
through dstOffset + bytes - 1
.
The result of a bulk copy is unspecified if, in the uncommon case, the source segment and the destination segment do not overlap, but refer to overlapping regions of the same backing storage using different addresses. For example, this may occur if the same file is mapped to two segments.
Calling this method is equivalent to the following code:
MemorySegment.copy(srcSegment, ValueLayout.JAVA_BYTE, srcOffset, dstSegment, ValueLayout.JAVA_BYTE, dstOffset, bytes);
srcSegment
- the source segment.srcOffset
- the starting offset, in bytes, of the source segment.dstSegment
- the destination segment.dstOffset
- the starting offset, in bytes, of the destination segment.bytes
- the number of bytes to be copied.IllegalStateException
- if the scope associated with srcSegment
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that srcSegment.isAccessibleBy(T) == false
.IllegalStateException
- if the scope associated with dstSegment
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that dstSegment.isAccessibleBy(T) == false
.IndexOutOfBoundsException
- if srcOffset > srcSegment.byteSize() - bytes
or if dstOffset > dstSegment.byteSize() - bytes
, or if either srcOffset
, dstOffset
or bytes
are < 0
.UnsupportedOperationException
- if dstSegment
is read-only.static void copy(MemorySegmentPREVIEW srcSegment, ValueLayoutPREVIEW srcElementLayout, long srcOffset, MemorySegmentPREVIEW dstSegment, ValueLayoutPREVIEW dstElementLayout, long dstOffset, long elementCount)
S
is the byte size of the element layouts, the bytes at offset srcOffset
through srcOffset + (elementCount * S) - 1
in the source segment are copied into the destination segment at offset dstOffset
through dstOffset + (elementCount * S) - 1
. The copy occurs in an element-wise fashion: the bytes in the source segment are interpreted as a sequence of elements whose layout is srcElementLayout
, whereas the bytes in the destination segment are interpreted as a sequence of elements whose layout is dstElementLayout
. Both element layouts must have same size S
. If the byte order of the two element layouts differ, the bytes corresponding to each element to be copied are swapped accordingly during the copy operation.
If the source segment overlaps with the destination segment, then the copying is performed as if the bytes at offset srcOffset
through srcOffset + (elementCount * S) - 1
in the source segment were first copied into a temporary segment with size bytes
, and then the contents of the temporary segment were copied into the destination segment at offset dstOffset
through dstOffset + (elementCount * S) - 1
.
The result of a bulk copy is unspecified if, in the uncommon case, the source segment and the destination segment do not overlap, but refer to overlapping regions of the same backing storage using different addresses. For example, this may occur if the same file is mapped to two segments.
srcSegment
- the source segment.srcElementLayout
- the element layout associated with the source segment.srcOffset
- the starting offset, in bytes, of the source segment.dstSegment
- the destination segment.dstElementLayout
- the element layout associated with the destination segment.dstOffset
- the starting offset, in bytes, of the destination segment.elementCount
- the number of elements to be copied.IllegalArgumentException
- if the element layouts have different sizes, if the source (resp. destination) segment/offset are incompatible with the alignment constraint in the source (resp. destination) element layout, or if the source (resp. destination) element layout alignment is greater than its size.IllegalStateException
- if the scope associated with srcSegment
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that srcSegment().isAccessibleBy(T) == false
.IllegalStateException
- if the scope associated with dstSegment
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that dstSegment().isAccessibleBy(T) == false
.UnsupportedOperationException
- if dstSegment
is read-only.IndexOutOfBoundsException
- if elementCount * srcLayout.byteSize()
or elementCount * dtsLayout.byteSize()
overflows.IndexOutOfBoundsException
- if dstOffset > dstSegment.byteSize() - (elementCount * dstLayout.byteSize())
.IndexOutOfBoundsException
- if either srcOffset
, dstOffset
or elementCount
are < 0
.default byte get(ValueLayout.OfBytePREVIEW layout, long offset)
layout
- the layout of the region of memory to be read.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.default void set(ValueLayout.OfBytePREVIEW layout, long offset, byte value)
layout
- the layout of the region of memory to be written.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.value
- the byte value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default boolean get(ValueLayout.OfBooleanPREVIEW layout, long offset)
layout
- the layout of the region of memory to be read.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.default void set(ValueLayout.OfBooleanPREVIEW layout, long offset, boolean value)
layout
- the layout of the region of memory to be written.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.value
- the boolean value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default char get(ValueLayout.OfCharPREVIEW layout, long offset)
layout
- the layout of the region of memory to be read.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.default void set(ValueLayout.OfCharPREVIEW layout, long offset, char value)
layout
- the layout of the region of memory to be written.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.value
- the char value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default short get(ValueLayout.OfShortPREVIEW layout, long offset)
layout
- the layout of the region of memory to be read.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.default void set(ValueLayout.OfShortPREVIEW layout, long offset, short value)
layout
- the layout of the region of memory to be written.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.value
- the short value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default int get(ValueLayout.OfIntPREVIEW layout, long offset)
layout
- the layout of the region of memory to be read.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.default void set(ValueLayout.OfIntPREVIEW layout, long offset, int value)
layout
- the layout of the region of memory to be written.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.value
- the int value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default float get(ValueLayout.OfFloatPREVIEW layout, long offset)
layout
- the layout of the region of memory to be read.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.default void set(ValueLayout.OfFloatPREVIEW layout, long offset, float value)
layout
- the layout of the region of memory to be written.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.value
- the float value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default long get(ValueLayout.OfLongPREVIEW layout, long offset)
layout
- the layout of the region of memory to be read.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.default void set(ValueLayout.OfLongPREVIEW layout, long offset, long value)
layout
- the layout of the region of memory to be written.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.value
- the long value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default double get(ValueLayout.OfDoublePREVIEW layout, long offset)
layout
- the layout of the region of memory to be read.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.default void set(ValueLayout.OfDoublePREVIEW layout, long offset, double value)
layout
- the layout of the region of memory to be written.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.value
- the double value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default MemorySegmentPREVIEW get(AddressLayoutPREVIEW layout, long offset)
0
. However, if the provided address layout has a target layoutPREVIEW T
, then the size of the returned segment is set to T.byteSize()
.layout
- the layout of the region of memory to be read.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IllegalArgumentException
- if provided address layout has a target layoutPREVIEW T
, and the address of the returned segment incompatible with the alignment constraint in T
.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.default void set(AddressLayoutPREVIEW layout, long offset, MemorySegmentPREVIEW value)
layout
- the layout of the region of memory to be written.offset
- offset in bytes (relative to this segment address) at which this access operation will occur.value
- the address value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout.IndexOutOfBoundsException
- if offset > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.UnsupportedOperationException
- if value
is not a native segment.default byte getAtIndex(ValueLayout.OfBytePREVIEW layout, long index)
layout
- the layout of the region of memory to be read.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.default boolean getAtIndex(ValueLayout.OfBooleanPREVIEW layout, long index)
layout
- the layout of the region of memory to be read.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.default char getAtIndex(ValueLayout.OfCharPREVIEW layout, long index)
layout
- the layout of the region of memory to be read.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.default void setAtIndex(ValueLayout.OfCharPREVIEW layout, long index, char value)
layout
- the layout of the region of memory to be written.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.value
- the char value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default short getAtIndex(ValueLayout.OfShortPREVIEW layout, long index)
layout
- the layout of the region of memory to be read.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.default void setAtIndex(ValueLayout.OfBytePREVIEW layout, long index, byte value)
layout
- the layout of the region of memory to be written.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.value
- the short value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default void setAtIndex(ValueLayout.OfBooleanPREVIEW layout, long index, boolean value)
layout
- the layout of the region of memory to be written.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.value
- the short value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default void setAtIndex(ValueLayout.OfShortPREVIEW layout, long index, short value)
layout
- the layout of the region of memory to be written.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.value
- the short value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default int getAtIndex(ValueLayout.OfIntPREVIEW layout, long index)
layout
- the layout of the region of memory to be read.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.default void setAtIndex(ValueLayout.OfIntPREVIEW layout, long index, int value)
layout
- the layout of the region of memory to be written.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.value
- the int value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default float getAtIndex(ValueLayout.OfFloatPREVIEW layout, long index)
layout
- the layout of the region of memory to be read.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.default void setAtIndex(ValueLayout.OfFloatPREVIEW layout, long index, float value)
layout
- the layout of the region of memory to be written.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.value
- the float value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default long getAtIndex(ValueLayout.OfLongPREVIEW layout, long index)
layout
- the layout of the region of memory to be read.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.default void setAtIndex(ValueLayout.OfLongPREVIEW layout, long index, long value)
layout
- the layout of the region of memory to be written.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.value
- the long value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default double getAtIndex(ValueLayout.OfDoublePREVIEW layout, long index)
layout
- the layout of the region of memory to be read.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.default void setAtIndex(ValueLayout.OfDoublePREVIEW layout, long index, double value)
layout
- the layout of the region of memory to be written.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.value
- the double value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.default MemorySegmentPREVIEW getAtIndex(AddressLayoutPREVIEW layout, long index)
0
. However, if the provided address layout has a target layoutPREVIEW T
, then the size of the returned segment is set to T.byteSize()
.layout
- the layout of the region of memory to be read.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IllegalArgumentException
- if provided address layout has a target layoutPREVIEW T
, and the address of the returned segment incompatible with the alignment constraint in T
.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.default void setAtIndex(AddressLayoutPREVIEW layout, long index, MemorySegmentPREVIEW value)
layout
- the layout of the region of memory to be written.index
- a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as (index * layout.byteSize())
.value
- the address value to be written.IllegalStateException
- if the scope associated with this segment is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that isAccessibleBy(T) == false
.IllegalArgumentException
- if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.IndexOutOfBoundsException
- if index * byteSize()
overflows.IndexOutOfBoundsException
- if index * byteSize() > byteSize() - layout.byteSize()
.UnsupportedOperationException
- if this segment is read-only.UnsupportedOperationException
- if value
is not a native segment.boolean equals(Object that)
true
if and only if the specified object is also a memory segment, and if the two segments refer to the same location, in some region of memory. More specifically, for two segments s1
and s2
to be considered equals, all the following must be true: s1.heapBase().equals(s2.heapBase())
, that is, the two segments must be of the same kind; either both are native segments, backed by off-heap memory, or both are backed by the same on-heap Java object; s1.address() == s2.address()
, that is, the address of the two segments should be the same. This means that the two segments either refer to the same location in some off-heap region, or they refer to the same offset inside their associated Java object.equals
in class Object
mismatch(MemorySegment)
method instead. Note that this method does not compare the temporal and spatial bounds of two segments. As such it is suitable to check whether two segments have the same address.that
- the object to be compared for equality with this memory segment.true
if the specified object is equal to this memory segment.int hashCode()
static void copy(MemorySegmentPREVIEW srcSegment, ValueLayoutPREVIEW srcLayout, long srcOffset, Object dstArray, int dstIndex, int elementCount)
byte[]
, char[]
, short[]
, int[]
, float[]
, long[]
and double[]
.srcSegment
- the source segment.srcLayout
- the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.srcOffset
- the starting offset, in bytes, of the source segment.dstArray
- the destination array.dstIndex
- the starting index of the destination array.elementCount
- the number of array elements to be copied.IllegalStateException
- if the scope associated with srcSegment
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that srcSegment().isAccessibleBy(T) == false
.IllegalArgumentException
- if dstArray
is not an array, or if it is an array but whose type is not supported.IllegalArgumentException
- if the destination array component type does not match srcLayout.carrier()
.IllegalArgumentException
- if offset
is incompatible with the alignment constraint in the source element layout.IllegalArgumentException
- if srcLayout.byteAlignment() > srcLayout.byteSize()
.IndexOutOfBoundsException
- if elementCount * srcLayout.byteSize()
overflows.IndexOutOfBoundsException
- if srcOffset > srcSegment.byteSize() - (elementCount * srcLayout.byteSize())
.IndexOutOfBoundsException
- if dstIndex > dstArray.length - elementCount
.IndexOutOfBoundsException
- if either srcOffset
, dstIndex
or elementCount
are < 0
.static void copy(Object srcArray, int srcIndex, MemorySegmentPREVIEW dstSegment, ValueLayoutPREVIEW dstLayout, long dstOffset, int elementCount)
byte[]
, char[]
, short[]
, int[]
, float[]
, long[]
and double[]
.srcArray
- the source array.srcIndex
- the starting index of the source array.dstSegment
- the destination segment.dstLayout
- the destination element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.dstOffset
- the starting offset, in bytes, of the destination segment.elementCount
- the number of array elements to be copied.IllegalStateException
- if the scope associated with dstSegment
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that dstSegment().isAccessibleBy(T) == false
.IllegalArgumentException
- if srcArray
is not an array, or if it is an array but whose type is not supported.IllegalArgumentException
- if the source array component type does not match srcLayout.carrier()
.IllegalArgumentException
- if offset
is incompatible with the alignment constraint in the source element layout.IllegalArgumentException
- if dstLayout.byteAlignment() > dstLayout.byteSize()
.UnsupportedOperationException
- if dstSegment
is read-only.IndexOutOfBoundsException
- if elementCount * dstLayout.byteSize()
overflows.IndexOutOfBoundsException
- if dstOffset > dstSegment.byteSize() - (elementCount * dstLayout.byteSize())
.IndexOutOfBoundsException
- if srcIndex > srcArray.length - elementCount
.IndexOutOfBoundsException
- if either srcIndex
, dstOffset
or elementCount
are < 0
.static long mismatch(MemorySegmentPREVIEW srcSegment, long srcFromOffset, long srcToOffset, MemorySegmentPREVIEW dstSegment, long dstFromOffset, long dstToOffset)
srcFromOffset
through srcToOffset - 1
in the source segment are compared against the bytes at offset dstFromOffset
through dstToOffset - 1
in the destination segment. If the two segments, over the specified ranges, share a common prefix then the returned offset is the length of the common prefix, and it follows that there is a mismatch between the two segments at that relative offset within the respective segments. If one segment is a proper prefix of the other, over the specified ranges, then the returned offset is the smallest range, and it follows that the relative offset is only valid for the segment with the larger range. Otherwise, there is no mismatch and -1
is returned.
srcSegment
- the source segment.srcFromOffset
- the offset (inclusive) of the first byte in the source segment to be tested.srcToOffset
- the offset (exclusive) of the last byte in the source segment to be tested.dstSegment
- the destination segment.dstFromOffset
- the offset (inclusive) of the first byte in the destination segment to be tested.dstToOffset
- the offset (exclusive) of the last byte in the destination segment to be tested.IllegalStateException
- if the scope associated with srcSegment
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that srcSegment.isAccessibleBy(T) == false
.IllegalStateException
- if the scope associated with dstSegment
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread T
, such that dstSegment.isAccessibleBy(T) == false
.IndexOutOfBoundsException
- if srcFromOffset < 0
, srcToOffset < srcFromOffset
or srcToOffset > srcSegment.byteSize()
IndexOutOfBoundsException
- if dstFromOffset < 0
, dstToOffset < dstFromOffset
or dstToOffset > dstSegment.byteSize()
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/MemorySegment.html
MemorySegment
when preview features are enabled.