archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-26 14:24:46 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8349653: Clarify the docs for MemorySegment::reinterpret

Browse source 
Reviewed-by: jvernee, mcimadamore
This commit is contained in:
Per Minborg 2025-02-24 07:38:29 +00:00
parent a5c9a4dbde
commit f755fadc3d
1 changed files with 18 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

36
src/java.base/share/classes/java/lang/foreign/MemorySegment.java
View file

@ -756,14 +756,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
/** /**
* Returns a new memory segment with the same address and size as this segment, but * Returns a new memory segment with the same address and size as this segment, but
* with the provided scope. As such, the returned segment cannot be accessed after * with the provided arena's scope. As such, the returned segment cannot be accessed
* the provided arena has been closed. Moreover, the returned segment can be * after the provided arena has been closed. Moreover, the returned segment can be
* accessed compatibly with the confinement restrictions associated with the provided * accessed compatibly with the confinement restrictions associated with the provided
* arena: that is, if the provided arena is a {@linkplain Arena#ofConfined() confined arena}, * arena: that is, if the provided arena is a {@linkplain Arena#ofConfined() confined arena},
* the returned segment can only be accessed by the arena's owner thread, regardless * the returned segment can only be accessed by the arena's owner thread, regardless
* of the confinement restrictions associated with this segment. In other words, this * of the confinement restrictions associated with this segment. In other words, this
* method returns a segment that can be used as any other segment allocated using the * method returns a segment that can be used as any other segment allocated using the
* provided arena. However, The returned segment is backed by the same memory region * provided arena. However, the returned segment is backed by the same memory region
* as that of the original segment. As such, the region of memory backing the * as that of the original segment. As such, the region of memory backing the
* returned segment is deallocated only when this segment's arena is closed. * returned segment is deallocated only when this segment's arena is closed.
* This might lead to <em>use-after-free</em> issues, as the returned segment can be * This might lead to <em>use-after-free</em> issues, as the returned segment can be
@ -771,15 +771,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* segment's arena. * segment's arena.
* <p> * <p>
* Clients can specify an optional cleanup action that should be executed when the * Clients can specify an optional cleanup action that should be executed when the
* provided scope becomes invalid. This cleanup action receives a fresh memory * provided arena's scope becomes invalid. This cleanup action receives a fresh memory
* segment that is obtained from this segment as follows: * segment that is obtained from this segment as follows:
* {@snippet lang=java : * {@snippet lang=java :
* MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address()) * MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
* .reinterpret(byteSize()); * .reinterpret(byteSize());
* } * }
* That is, the cleanup action receives a segment that is associated with the global * That is, the cleanup action receives a segment that is associated with the global
* scope, and is accessible from any thread. The size of the segment accepted by the * arena's scope, and is accessible from any thread. The size of the segment accepted
* cleanup action is {@link #byteSize()}. * by the cleanup action is {@link #byteSize()}.
* <p> * <p>
* If this segment is {@linkplain MemorySegment#isReadOnly() read-only}, * If this segment is {@linkplain MemorySegment#isReadOnly() read-only},
* the returned segment is also {@linkplain MemorySegment#isReadOnly() read-only}. * the returned segment is also {@linkplain MemorySegment#isReadOnly() read-only}.
@ -790,8 +790,8 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* @apiNote The cleanup action (if present) should take care not to leak the received * @apiNote The cleanup action (if present) should take care not to leak the received
* segment to external clients that might access the segment after its * segment to external clients that might access the segment after its
* backing region of memory is no longer available. Furthermore, if the * backing region of memory is no longer available. Furthermore, if the
* provided scope is the scope of an {@linkplain Arena#ofAuto() automatic arena}, * provided arena is an {@linkplain Arena#ofAuto() automatic arena},
* the cleanup action must not prevent the scope from becoming * the cleanup action must not prevent the arena from becoming
* {@linkplain java.lang.ref##reachability unreachable}. * {@linkplain java.lang.ref##reachability unreachable}.
* A failure to do so will permanently prevent the regions of memory * A failure to do so will permanently prevent the regions of memory
* allocated by the automatic arena from being deallocated. * allocated by the automatic arena from being deallocated.
@ -812,14 +812,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
/** /**
* Returns a new segment with the same address as this segment, but with the provided * Returns a new segment with the same address as this segment, but with the provided
* size and scope. As such, the returned segment cannot be accessed after the * size and the provided arena's scope. As such, the returned segment cannot be
* provided arena has been closed. Moreover, if the returned segment can be accessed * accessed after the provided arena has been closed. Moreover, if the returned
* compatibly with the confinement restrictions associated with the provided arena: * segment can be accessed compatibly with the confinement restrictions associated
* that is, if the provided arena is a {@linkplain Arena#ofConfined() confined arena}, * with the provided arena: that is, if the provided arena is a {@linkplain Arena#ofConfined() confined arena},
* the returned segment can only be accessed by the arena's owner thread, regardless * the returned segment can only be accessed by the arena's owner thread, regardless
* of the confinement restrictions associated with this segment. In other words, this * of the confinement restrictions associated with this segment. In other words, this
* method returns a segment that can be used as any other segment allocated using the * method returns a segment that can be used as any other segment allocated using the
* provided arena. However, The returned segment is backed by the same memory region * provided arena. However, the returned segment is backed by the same memory region
* as that of the original segment. As such, the region of memory backing the * as that of the original segment. As such, the region of memory backing the
* returned segment is deallocated only when this segment's arena is closed. * returned segment is deallocated only when this segment's arena is closed.
* This might lead to <em>use-after-free</em> issues, as the returned segment can be * This might lead to <em>use-after-free</em> issues, as the returned segment can be
@ -827,15 +827,15 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* segment's arena. * segment's arena.
* <p> * <p>
* Clients can specify an optional cleanup action that should be executed when the * Clients can specify an optional cleanup action that should be executed when the
* provided scope becomes invalid. This cleanup action receives a fresh memory * provided arena's scope becomes invalid. This cleanup action receives a fresh memory
* segment that is obtained from this segment as follows: * segment that is obtained from this segment as follows:
* {@snippet lang=java : * {@snippet lang=java :
* MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address()) * MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
* .reinterpret(newSize); * .reinterpret(newSize);
* } * }
* That is, the cleanup action receives a segment that is associated with the global * That is, the cleanup action receives a segment that is associated with the global
* scope, and is accessible from any thread. The size of the segment accepted by the * arena's scope, and is accessible from any thread. The size of the segment accepted
* cleanup action is {@code newSize}. * by the cleanup action is {@code newSize}.
* <p> * <p>
* If this segment is {@linkplain MemorySegment#isReadOnly() read-only}, * If this segment is {@linkplain MemorySegment#isReadOnly() read-only},
* the returned segment is also {@linkplain MemorySegment#isReadOnly() read-only}. * the returned segment is also {@linkplain MemorySegment#isReadOnly() read-only}.
@ -846,8 +846,8 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* @apiNote The cleanup action (if present) should take care not to leak the received * @apiNote The cleanup action (if present) should take care not to leak the received
* segment to external clients that might access the segment after its * segment to external clients that might access the segment after its
* backing region of memory is no longer available. Furthermore, if the * backing region of memory is no longer available. Furthermore, if the
* provided scope is the scope of an {@linkplain Arena#ofAuto() automatic arena}, * provided arena is an {@linkplain Arena#ofAuto() automatic arena},
* the cleanup action must not prevent the scope from becoming * the cleanup action must not prevent the arena from becoming
* {@linkplain java.lang.ref##reachability unreachable}. * {@linkplain java.lang.ref##reachability unreachable}.
* A failure to do so will permanently prevent the regions of memory * A failure to do so will permanently prevent the regions of memory
* allocated by the automatic arena from being deallocated. * allocated by the automatic arena from being deallocated.