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