< prev index next >
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
Print this page
M MemorySegment.java
@@ -175,11 +175,12 @@
* characteristics.
* <p>
* The returned spliterator splits the segment according to the specified sequence layout; that is,
* if the supplied layout is a sequence layout whose element count is {@code N}, then calling {@link Spliterator#trySplit()}
* will result in a spliterator serving approximatively {@code N/2} elements (depending on whether N is even or not).
- * As such, splitting is possible as long as {@code N >= 2}.
+ * As such, splitting is possible as long as {@code N >= 2}. The spliterator returns segments that feature the same
+ * <a href="#access-modes">access modes</a> as the given segment less the {@link #CLOSE} access mode.
* <p>
* The returned spliterator effectively allows to slice a segment into disjoint sub-segments, which can then
* be processed in parallel by multiple threads (if the access mode {@link #ACQUIRE} is set).
* While closing the segment (see {@link #close()}) during pending concurrent execution will generally
* fail with an exception, it is possible to close a segment when a spliterator has been obtained but no thread
@@ -318,10 +319,14 @@
/**
* Creates a new buffer memory segment that models the memory associated with the given byte
* buffer. The segment starts relative to the buffer's position (inclusive)
* and ends relative to the buffer's limit (exclusive).
* <p>
+ * The segment will feature all <a href="#access-modes">access modes</a>, unless the given
+ * buffer is {@linkplain ByteBuffer#isReadOnly() read-only} in which case the segment will
+ * not feature the {@link #WRITE} access mode.
+ * <p>
* The resulting memory segment keeps a reference to the backing buffer, to ensure it remains <em>reachable</em>
* for the life-time of the segment.
*
* @param bb the byte buffer backing the buffer memory segment.
* @return a new buffer memory segment.
@@ -332,11 +337,11 @@
/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated byte array.
* <p>
* The resulting memory segment keeps a reference to the backing array, to ensure it remains <em>reachable</em>
- * for the life-time of the segment.
+ * for the life-time of the segment. The segment will feature all <a href="#access-modes">access modes</a>.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(byte[] arr) {
@@ -345,11 +350,11 @@
/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated char array.
* <p>
* The resulting memory segment keeps a reference to the backing array, to ensure it remains <em>reachable</em>
- * for the life-time of the segment.
+ * for the life-time of the segment. The segment will feature all <a href="#access-modes">access modes</a>.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(char[] arr) {
@@ -358,11 +363,11 @@
/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated short array.
* <p>
* The resulting memory segment keeps a reference to the backing array, to ensure it remains <em>reachable</em>
- * for the life-time of the segment.
+ * for the life-time of the segment. The segment will feature all <a href="#access-modes">access modes</a>.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(short[] arr) {
@@ -371,11 +376,11 @@
/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated int array.
* <p>
* The resulting memory segment keeps a reference to the backing array, to ensure it remains <em>reachable</em>
- * for the life-time of the segment.
+ * for the life-time of the segment. The segment will feature all <a href="#access-modes">access modes</a>.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(int[] arr) {
@@ -384,11 +389,11 @@
/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated float array.
* <p>
* The resulting memory segment keeps a reference to the backing array, to ensure it remains <em>reachable</em>
- * for the life-time of the segment.
+ * for the life-time of the segment. The segment will feature all <a href="#access-modes">access modes</a>.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(float[] arr) {
@@ -397,11 +402,11 @@
/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated long array.
* <p>
* The resulting memory segment keeps a reference to the backing array, to ensure it remains <em>reachable</em>
- * for the life-time of the segment.
+ * for the life-time of the segment. The segment will feature all <a href="#access-modes">access modes</a>.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(long[] arr) {
@@ -410,11 +415,11 @@
/**
* Creates a new array memory segment that models the memory associated with a given heap-allocated double array.
* <p>
* The resulting memory segment keeps a reference to the backing array, to ensure it remains <em>reachable</em>
- * for the life-time of the segment.
+ * for the life-time of the segment. The segment will feature all <a href="#access-modes">access modes</a>.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(double[] arr) {
@@ -461,10 +466,14 @@
return allocateNative(bytesSize, 1);
}
/**
* Creates a new mapped memory segment that models a memory-mapped region of a file from a given path.
+ * <p>
+ * The segment will feature all <a href="#access-modes">access modes</a>, unless the given mapping mode
+ * is {@linkplain FileChannel.MapMode#READ_ONLY READ_ONLY}, in which case the segment will not feature
+ * the {@link #WRITE} access mode.
*
* @implNote When obtaining a mapped segment from a newly created file, the initialization state of the contents of the block
* of mapped memory associated with the returned mapped memory segment is unspecified and should not be relied upon.
*
* @param path the path to the file to memory map.
@@ -480,11 +489,11 @@
return MappedMemorySegmentImpl.makeMappedSegment(path, bytesSize, mapMode);
}
/**
* Creates a new native memory segment that models a newly allocated block of off-heap memory with given size and
- * alignment constraint (in bytes).
+ * alignment constraint (in bytes). The segment will feature all <a href="#access-modes">access modes</a>.
*
* @implNote The block of off-heap memory associated with the returned native memory segment is initialized to zero.
* Moreover, a client is responsible to call the {@link MemorySegment#close()} on a native memory segment,
* to make sure the backing off-heap memory block is deallocated accordingly. Failure to do so will result in off-heap memory leaks.
*
@@ -510,11 +519,11 @@
/**
* Returns a new native memory segment with given base address and size; the returned segment has its own temporal
* bounds, and can therefore be closed; closing such a segment can optionally result in calling an user-provided cleanup
* action. This method can be very useful when interacting with custom native memory sources (e.g. custom allocators,
* GPU memory, etc.), where an address to some underlying memory region is typically obtained from native code
- * (often as a plain {@code long} value).
+ * (often as a plain {@code long} value). The segment will feature all <a href="#access-modes">access modes</a>.
* <p>
* This method is <em>restricted</em>. Restricted method are unsafe, and, if used incorrectly, their use might crash
* the JVM crash or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
* restricted methods, and use safe and supported functionalities, where possible.
*
< prev index next >