force(MemorySegment)
,
and load(MemorySegment)
. The methods in these class are suitable replacements for some of the
functionality in the MappedByteBuffer
class. Note that, while it is possible to map a segment
into a byte buffer (see MemorySegment.asByteBuffer()
), and call e.g. MappedByteBuffer.force()
that way,
this can only be done when the source segment is small enough, due to the size limitation inherent to the
ByteBuffer API.
Clients requiring sophisticated, low-level control over mapped memory segments, should consider writing
custom mapped memory segment factories; using JNI, e.g. on Linux, it is possible to call mmap
with the desired parameters; the returned address can be easily wrapped into a memory segment, using
MemoryAddress.ofLong(long)
and MemoryAddress.asSegmentRestricted(long, Runnable, Object)
.
Unless otherwise specified, passing a null
argument, or an array argument containing one or more null
elements to a method in this class causes a NullPointerException
to be thrown.
- Implementation Note:
- The behavior of some the methods in this class (see
load(MemorySegment)
,unload(MemorySegment)
andisLoaded(MemorySegment)
) is highly platform-dependent; as a result, calling these methods might be a no-op on certain platforms.
-
Method Summary
Modifier and TypeMethodDescriptionstatic void
force(MemorySegment segment)
Forces any changes made to the contents of the given segment to be written to the storage device described by the mapped segment's file descriptor.static boolean
isLoaded(MemorySegment segment)
Tells whether or not the contents of the given segment is resident in physical memory.static void
load(MemorySegment segment)
Loads the contents of the given segment into physical memory.static void
unload(MemorySegment segment)
Unloads the contents of the given segment from physical memory.
-
Method Details
-
isLoaded
Tells whether or not the contents of the given segment is resident in physical memory.A return value of
true
implies that it is highly likely that all of the data in the given 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 offalse
does not necessarily imply that the 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 the segment's data by the time that an invocation of this method returns.
- Parameters:
segment
- the segment whose contents are to be tested.- Returns:
true
if it is likely that the contents of the given segment is resident in physical memory- Throws:
IllegalStateException
- if the given segment is not alive, or if the given segment is confined and this method is called from a thread other than the segment's owner thread.UnsupportedOperationException
- if the given segment is not a mapped memory segment, e.g. ifsegment.isMapped() == false
.
-
load
Loads the contents of the given segment into physical memory.This method makes a best effort to ensure that, when it returns, this contents of the given segment is resident in physical memory. Invoking this method may cause some number of page faults and I/O operations to occur.
- Parameters:
segment
- the segment whose contents are to be loaded.- Throws:
IllegalStateException
- if the given segment is not alive, or if the given segment is confined and this method is called from a thread other than the segment's owner thread.UnsupportedOperationException
- if the given segment is not a mapped memory segment, e.g. ifsegment.isMapped() == false
.
-
unload
Unloads the contents of the given segment from physical memory.This method makes a best effort to ensure that the contents of the given 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).
- Parameters:
segment
- the segment whose contents are to be unloaded.- Throws:
IllegalStateException
- if the given segment is not alive, or if the given segment is confined and this method is called from a thread other than the segment's owner thread.UnsupportedOperationException
- if the given segment is not a mapped memory segment, e.g. ifsegment.isMapped() == false
.
-
force
Forces any changes made to the contents of the given segment to be written to the storage device described by the mapped segment's file descriptor.If this mapping's file descriptor resides on a local storage device then when this method returns it is guaranteed that all changes made to the segment since it was created, or since this method was last invoked, will have been written to that device.
If this mapping's file descriptor does not reside on a local device then no such guarantee is made.
If the given 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.- Parameters:
segment
- the segment whose contents are to be written to the storage device described by the segment's file descriptor.- Throws:
IllegalStateException
- if the given segment is not alive, or if the given segment is confined and this method is called from a thread other than the segment's owner thread.UnsupportedOperationException
- if the given segment is not a mapped memory segment, e.g. ifsegment.isMapped() == false
.
-