< prev index next >
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
Print this page
M MemorySegment.java
*** 175,185 ****
* 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}.
* <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
--- 175,186 ----
* 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}. 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,327 ****
--- 319,332 ----
/**
* 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,342 ****
/**
* 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.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(byte[] arr) {
--- 337,347 ----
/**
* 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. 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,355 ****
/**
* 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.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(char[] arr) {
--- 350,360 ----
/**
* 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. 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,368 ****
/**
* 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.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(short[] arr) {
--- 363,373 ----
/**
* 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. 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,381 ****
/**
* 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.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(int[] arr) {
--- 376,386 ----
/**
* 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. 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,394 ****
/**
* 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.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(float[] arr) {
--- 389,399 ----
/**
* 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. 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,407 ****
/**
* 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.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(long[] arr) {
--- 402,412 ----
/**
* 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. 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,420 ****
/**
* 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.
*
* @param arr the primitive array backing the array memory segment.
* @return a new array memory segment.
*/
static MemorySegment ofArray(double[] arr) {
--- 415,425 ----
/**
* 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. 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,470 ****
--- 466,479 ----
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,490 ****
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).
*
* @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.
*
--- 489,499 ----
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). 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,520 ****
/**
* 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).
* <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.
*
--- 519,529 ----
/**
* 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). 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 >