Interface MemorySegment

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/2 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 feature the same scope as this given segment.

The returned spliterator effectively allows to slice this segment into disjoint sub-segments, which can then be processed in parallel by multiple threads.

    StreamSupport.stream(segment.spliterator(elementLayout), false);
 

Equivalent to the following code:

    asSlice(newBase.segmentOffset(this), newSize);
 

Equivalent to the following code:

    asSlice(offset, byteSize() - offset);
 

Equivalent to the following code:

    asSlice(newBase.segmentOffset(this));
 

More specifically, the given value is filled into each address of this segment. Equivalent to (but likely more efficient than) the following code:

byteHandle = MemoryLayout.ofSequence(MemoryLayouts.JAVA_BYTE)
         .varHandle(byte.class, MemoryLayout.PathElement.sequenceElement());
for (long l = 0; l < segment.byteSize(); l++) {
     byteHandle.set(segment.address(), l, value);
}
 

Fill can be useful to initialize or reset the memory of a segment.

The result of a bulk copy is unspecified if, in the uncommon case, the source segment and this 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.

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 smaller 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.

A return value of true implies that it is highly likely that all of 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.

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.

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).

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.

The returned buffer's position (see Buffer.position() is initially set to zero, while the returned buffer's capacity and limit (see Buffer.capacity() and Buffer.limit(), respectively) are set to this segment' size (see byteSize()). For this reason, a byte buffer cannot be returned if this segment' size is greater than Integer.MAX_VALUE.

The life-cycle of the returned buffer will be tied to that of this segment. That is, accessing the returned buffer after the scope associated with this segment has been closed (see ResourceScope.close(), will throw an IllegalStateException.

If this segment is associated with a confined scope, calling read/write I/O operations on the resulting buffer might result in an unspecified exception 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).

If the buffer is read-only, the resulting segment will also be read-only. The scope associated with this segment can either be the global resource scope, in case the buffer has been created independently, or to some other (possibly closeable) resource scope, in case the buffer has been obtained using asByteBuffer().

The resulting memory segment keeps a reference to the backing buffer, keeping it reachable.

This is equivalent to the following code:

    allocateNative(layout.bytesSize(), layout.bytesAlignment(), scope);
 

The block of off-heap memory associated with the returned native memory segment is initialized to zero.

This is equivalent to the following code:

    allocateNative(bytesSize, 1, scope);
 

The block of off-heap memory associated with the returned native memory segment is initialized to zero.

The block of off-heap memory associated with the returned native memory segment is initialized to zero.

If the specified mapping mode is READ_ONLY, the resulting segment will be read-only (see isReadOnly()).

The content of a mapped memory segment can change at any time, for example if the content of the corresponding region of the mapped file is changed by this (or another) program. Whether or not such changes occur, and when they occur, is operating-system dependent and therefore unspecified.

All or part of a mapped memory segment may become inaccessible at any time, for example if the backing mapped file is truncated. An attempt to access an inaccessible region of a mapped memory segment will not change the segment's content and will cause an unspecified exception to be thrown either at the time of the access or at some later time. It is therefore strongly recommended that appropriate precautions be taken to avoid the manipulation of a mapped file by this (or another) program, except to read or write the file's content.

    MemoryAddress.NULL.asSegment(Long.MAX_VALUE)
 

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.